diff options
Diffstat (limited to 'doc/src/declarative/anchor-layout.qdoc')
-rw-r--r-- | doc/src/declarative/anchor-layout.qdoc | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc new file mode 100644 index 0000000000..4dd5eb988a --- /dev/null +++ b/doc/src/declarative/anchor-layout.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-anchor-layout.html +\target anchor-layout +\contentspage QML Features +\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} +\nextpage {QML Mouse Events}{Mouse Events} +\title Anchor-based Layout in QML + +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": +\l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter}, +\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, +\l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline}, +and \l {Item::anchors.bottom}{bottom}. + +\image edges_qml.png + +The baseline (not pictured above) corresponds to the imaginary line on which +text would sit. For items with no text it is the same as \e top. + +The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; ... } +\endcode + +In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following: + +\image edge1.png + + +You can specify multiple anchors. For example: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... } +\endcode + +\image edge3.png + +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; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: rect3.left; ... } +Rectangle { id: rect3; x: 150; ... } +\endcode + +\image edge4.png + +There are also some convenience anchors. anchors.fill is a convenience that is the same as setting the left,right,top and bottom anchors +to the left,right,top and bottom of the target item. anchors.centerIn is another convenience anchor, and is the same as setting the verticalCenter +and horizontalCenter anchors to the verticalCenter and horizontalCenter of the target item. + +\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 { + id: group1 + Rectangle { id: rect1; ... } +} +Item { + id: group2 + Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor! +} +\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. + +*/ |