Improvements to anchoring docs

Make it clear that anchor margins only apply to anchors. Also
document that anchor and absolute positioning cannot be mixed.

1 files changed, 49 insertions, 17 deletions

diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc
index b77ce36..f5d5697 100644
--- a/doc/src/declarative/anchor-layout.qdoc
+++ b/doc/src/declarative/anchor-layout.qdoc
@@ -30,6 +30,8 @@
 \target anchor-layout
 \title Anchor-based Layout in QML
 
+\section1 Overview
+
 In addition to the more traditional \l Grid, \l Row, and \l Column,
 QML also provides a way to layout items using the concept of \e anchors.
 Each item can be thought of as having a set of 7 invisible "anchor lines":
@@ -54,20 +56,6 @@ In this case, the left edge of \e rect2 is bound to the right edge of \e rect1,
 
 \image edge1.png
 
-The anchoring system also allows you to specify margins and offsets. Margins specify the amount of empty space to leave to the outside of an item, while offsets allow you to manipulate positioning using the center anchor lines. Note that margins specified using the anchor layout system only have meaning for anchors; they won't have any effect when using other layouts or absolute positioning.
-
-\image margins_qml.png
-
-The following example specifies a left margin:
-
-\code
-Rectangle { id: rect1; ... }
-Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }
-\endcode
-
-In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following:
-
-\image edge2.png
 
 You can specify multiple anchors. For example:
 
@@ -78,7 +66,9 @@ Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ...
 
 \image edge3.png
 
-By specifying multiple horizontal or vertical anchors you can control the size of an item. For example:
+By specifying multiple horizontal or vertical anchors you can control the size of an item. Below,
+\e rect2 is anchored to the right of \e rect1 and the left of \e rect3. If either of the blue
+rectangles are moved, \e rect2 will stretch and shrink as necessary:
 
 \code
 Rectangle { id: rect1; x: 0; ... }
@@ -88,9 +78,42 @@ Rectangle { id: rect3; x: 150; ... }
 
 \image edge4.png
 
-\section1 Limitations
 
-For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor would be considered invalid and would produce a warning:
+\section1 Anchor Margins and Offsets
+
+The anchoring system also allows \e margins and \e offsets to be specified for an item's anchors.
+Margins specify the amount of empty space to leave to the outside of an item's anchor, while
+offsets allow positioning to be manipulated using the center anchor lines.  An item can
+specify its anchor margins individually through \l {Item::anchors.leftMargin}{leftMargin},
+\l {Item::anchors.rightMargin}{rightMargin}, \l {Item::anchors.topMargin}{topMargin} and
+\l {Item::anchors.bottomMargin}{bottomMargin}, or use \l {Item::}{anchors.margins} to
+specify the same margin value for all four edges. Anchor offsets are specified using
+\l {Item::anchors.horizontalCenterOffset}{horizontalCenterOffset},
+\l {Item::anchors.verticalCenterOffset}{verticalCenterOffset} and
+\l {Item::anchors.baselineOffset}{baselineOffset}.
+
+\image margins_qml.png
+
+The following example specifies a left margin:
+
+\code
+Rectangle { id: rect1; ... }
+Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }
+\endcode
+
+In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following:
+
+\image edge2.png
+
+\note Anchor margins only apply to anchors; they are \e not a generic means of applying margins to an \l Item.
+If an anchor margin is specified for an edge but the item is not anchored to any item on that
+edge, the margin is not applied.
+
+
+\section1 Restrictions
+
+For performance reasons, you can only anchor an item to its siblings and direct parent. For example,
+the following anchor is invalid and would produce a warning:
 
 \badcode
 Item {
@@ -103,4 +126,13 @@ Item {
 }
 \endcode
 
+Also, anchor-based layouts cannot be mixed with absolute positioning. If an item specifies its
+\l {Item::}{x} position and also sets \l {Item::}{anchors.left},
+or anchors its left and right edges but additionally sets a \l {Item::}{width}, the
+result is undefined, as it would not be clear whether the item should use anchoring or absolute
+positioning. The same can be said for setting an item's \l {Item::}{y} and \l {Item::}{height}
+with \l {Item::}{anchors.top} and \l {Item::}{anchors.bottom}, or setting \l {Item::}{anchors.fill}
+as well as \l {Item::}{width} or \l {Item::}{height}. If you wish to change from using
+anchor-based to absolute positioning, you can clear an anchor value by setting it to \c undefined.
+
 */