diff options
Diffstat (limited to 'src/quick/doc/src/positioners.qdoc')
-rw-r--r-- | src/quick/doc/src/positioners.qdoc | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/src/quick/doc/src/positioners.qdoc b/src/quick/doc/src/positioners.qdoc new file mode 100644 index 0000000000..d73d1cdbac --- /dev/null +++ b/src/quick/doc/src/positioners.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtquick-positioners.html +\ingroup qml-features +\title Item Layouts + +Positioner items are container items that manage the positions and sizes of +items in a declarative user interface. Positioners behave in a similar way to +the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, +except that they are also containers in their own right. + +Positioners make it easier to work with many items when they need +to be arranged in a regular layout. + +\section1 Positioners + +A set of standard positioners are provided in the basic set of Qt Quick +graphical elements: + +\list +\li \l{#Column}{Column} arranges its children in a column +\li \l{#Row}{Row} arranges its children in a row +\li \l{#Grid}{Grid} arranges its children in a grid +\li \l{#Flow}{Flow} arranges its children like words on a page +\endlist + +\section2 Column + +\div {class="float-right"} +\inlineimage qml-column.png +\enddiv + +\l Column items are used to vertically arrange items. The following example +uses a Column item to arrange three \l Rectangle items in an area defined +by an outer \l Item. The \l{Column::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +\snippet doc/snippets/qml/column/column.qml document + +Note that, since Column inherits directly from Item, any background color +must be added to a parent Rectangle, if desired. + +\section2 Row + +\div {class="float-right"} +\inlineimage qml-row.png +\enddiv + +\l Row items are used to horizontally arrange items. The following example +uses a Row item to arrange three rounded \l Rectangle items in an area defined +by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +We ensure that the parent Rectangle is large enough so that there is some space +left around the edges of the horizontally centered Row item. + +\snippet doc/snippets/qml/row.qml document + +\section2 Grid + +\div {class="float-right"} +\inlineimage qml-grid-spacing.png +\enddiv + +\l Grid items are used to place items in a grid or table arrangement. +The following example uses a Grid item to place four \l Rectangle items +in a 2-by-2 grid. As with the other positioners, the spacing between items +can be specified using the \l{Grid::spacing}{spacing} property. + +\snippet doc/snippets/qml/grid-spacing.qml document + +There is no difference between horizontal and vertical spacing inserted +between items, so any additional space must be added within the items +themselves. + +Any empty cells in the grid must be created by defining placeholder items +at the appropriate places in the Grid definition. + +\section2 Flow + +\div {class="float-right"} +\inlineimage qml-flow-text1.png +\inlineimage qml-flow-text2.png +\enddiv + +\l Flow items are used to place items like words on a page, with rows or +columns of non-overlapping items. + +Flow items arrange items in a similar way to \l Grid items, with items +arranged in lines along one axis (the minor axis), and lines of items +placed next to each other along another axis (the major axis). The +direction of flow, as well as the spacing between items, are controlled +by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties. + +The following example shows a Flow item containing a number of \l Text +child items. These are arranged in a similar way to those shown in the +screenshots. + +\snippet doc/snippets/qml/flow.qml document + +The main differences between the Grid and Flow positioners are that items +inside a Flow will wrap when they run out of space on the minor axis, and +items on one line may not be aligned with items on another line if the +items do not have uniform sizes. As with Grid items, there is no independent +control of spacing between items and between lines of items. + +\section1 Other Ways to Position Items + +There are several other ways to position items in a user interface. In addition +to the basic technique of specifying their coordinates directly, they can be +positioned relative to other items with \l{anchor-layout}{anchors}, or used +with \l{QML Data Models} such as +\l{QML Data Models#VisualItemModel}{VisualItemModel}. +*/ |