doc/src/declarative/positioners.qdoc

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