doc/src/declarative/positioners.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-positioners.html
  30 \inqmlmodule QtQuick 2
  31 \ingroup qml-features
  32 \previouspage Property Binding
  33 \nextpage Anchor-based Layout in QML
  34 \contentspage QML Features
  35 \title Using QML Positioner and Repeater Items
  36
  37
  38 Positioner items are container items that manage the positions and sizes of
  39 items in a declarative user interface. Positioners behave in a similar way to
  40 the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets,
  41 except that they are also containers in their own right.
  42
  43 Positioners and repeaters make it easier to work with many items when they need
  44 to be arranged in a regular layout.
  45
  46 \section1 Positioners
  47
  48 A set of standard positioners are provided in the basic set of Qt Quick
  49 graphical elements:
  50
  51 \list
  52 \o \l{#Column}{Column} arranges its children in a column
  53 \o \l{#Row}{Row} arranges its children in a row
  54 \o \l{#Grid}{Grid} arranges its children in a grid
  55 \o \l{#Flow}{Flow} arranges its children like words on a page
  56 \endlist
  57
  58 \section2 Column
  59
  60 \div {class="float-right"}
  61 \inlineimage qml-column.png
  62 \enddiv
  63
  64 \l Column items are used to vertically arrange items. The following example
  65 uses a Column item to arrange three \l Rectangle items in an area defined
  66 by an outer \l Item. The \l{Column::spacing}{spacing} property is set to
  67 include a small amount of space between the rectangles.
  68
  69 \clearfloat
  70 \snippet doc/src/snippets/declarative/column/column.qml document
  71
  72 Note that, since Column inherits directly from Item, any background color
  73 must be added to a parent Rectangle, if desired.
  74
  75 \section2 Row
  76
  77 \div {class="float-right"}
  78 \inlineimage qml-row.png
  79 \enddiv
  80
  81 \l Row items are used to horizontally arrange items. The following example
  82 uses a Row item to arrange three rounded \l Rectangle items in an area defined
  83 by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to
  84 include a small amount of space between the rectangles.
  85
  86 We ensure that the parent Rectangle is large enough so that there is some space
  87 left around the edges of the horizontally centered Row item.
  88
  89 \clearfloat
  90 \snippet doc/src/snippets/declarative/row.qml document
  91
  92 \section2 Grid
  93
  94 \div {class="float-right"}
  95 \inlineimage qml-grid-spacing.png
  96 \enddiv
  97
  98 \l Grid items are used to place items in a grid or table arrangement.
  99 The following example uses a Grid item to place four \l Rectangle items
 100 in a 2-by-2 grid. As with the other positioners, the spacing between items
 101 can be specified using the \l{Grid::spacing}{spacing} property.
 102
 103 \clearfloat
 104 \snippet doc/src/snippets/declarative/grid-spacing.qml document
 105
 106 There is no difference between horizontal and vertical spacing inserted
 107 between items, so any additional space must be added within the items
 108 themselves.
 109
 110 Any empty cells in the grid must be created by defining placeholder items
 111 at the appropriate places in the Grid definition.
 112
 113 \section2 Flow
 114
 115 \div {class="float-right"}
 116 \inlineimage qml-flow-text1.png
 117 \inlineimage qml-flow-text2.png
 118 \enddiv
 119
 120 \l Flow items are used to place items like words on a page, with rows or
 121 columns of non-overlapping items.
 122
 123 Flow items arrange items in a similar way to \l Grid items, with items
 124 arranged in lines along one axis (the minor axis), and lines of items
 125 placed next to each other along another axis (the major axis). The
 126 direction of flow, as well as the spacing between items, are controlled
 127 by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties.
 128
 129 The following example shows a Flow item containing a number of \l Text
 130 child items. These are arranged in a similar way to those shown in the
 131 screenshots.
 132
 133 \clearfloat
 134 \snippet doc/src/snippets/declarative/flow.qml document
 135
 136 The main differences between the Grid and Flow positioners are that items
 137 inside a Flow will wrap when they run out of space on the minor axis, and
 138 items on one line may not be aligned with items on another line if the
 139 items do not have uniform sizes. As with Grid items, there is no independent
 140 control of spacing between items and between lines of items.
 141
 142 \section1 Repeaters
 143
 144 \div {class="float-right"}
 145 \inlineimage qml-repeater-grid-index.png
 146 \enddiv
 147
 148 Repeaters create items from a template for use with positioners, using data
 149 from a model. Combining repeaters and positioners is an easy way to lay out
 150 lots of items. A \l Repeater item is placed inside a positioner, and generates
 151 items that the enclosing positioner arranges.
 152
 153 Each Repeater creates a number of items by combining each element of data
 154 from a model, specified using the \l{Repeater::model}{model} property, with
 155 the template item, defined as a child item within the Repeater.
 156 The total number of items is determined by the amount of data in the model.
 157
 158 The following example shows a repeater used with a \l{#Grid}{Grid} item to
 159 arrange a set of Rectangle items. The Repeater item creates a series of 24
 160 rectangles for the Grid item to position in a 5 by 5 arrangement.
 161
 162 \clearfloat
 163 \snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document
 164
 165 The number of items created by a Repeater is held by its \l{Repeater::}{count}
 166 property. It is not possible to set this property to determine the number of
 167 items to be created. Instead, as in the above example, we use an integer as
 168 the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models}
 169 document.
 170
 171 It is also possible to use a delegate as the template for the items created
 172 by a Repeater. This is specified using the \l{Repeater::}{delegate} property.
 173
 174 \section1 Using Transitions
 175
 176 Transitions can be used to animate items that are added to, moved within,
 177 or removed from a positioner.
 178
 179 Transitions for adding items apply to items that are created as part of a
 180 positioner, as well as those that are reparented to become children of a
 181 positioner.
 182 Transitions for removing items apply to items within a positioner that are
 183 deleted, as well as those that are removed from a positioner and given new
 184 parents in a document.
 185
 186 Additionally, changing the opacity of items to zero will cause them to
 187 disappear using the remove transition, and making the opacity non-zero will
 188 cause them to appear using the add transition.
 189
 190 \section1 Other Ways to Position Items
 191
 192 There are several other ways to position items in a user interface. In addition
 193 to the basic technique of specifying their coordinates directly, they can be
 194 positioned relative to other items with \l{anchor-layout}{anchors}, or used
 195 with \l{QML Data Models} such as
 196 \l{QML Data Models#VisualItemModel}{VisualItemModel}.
 197 */