From 245653f469baa0227c0b07fd6a232629ed53e9ee Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 13 Sep 2010 15:31:44 +0200 Subject: Doc: Added a missing file. --- doc/src/declarative/positioners.qdoc | 193 +++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 doc/src/declarative/positioners.qdoc diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc new file mode 100644 index 0000000..8c9b8b7 --- /dev/null +++ b/doc/src/declarative/positioners.qdoc @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** Copyright (C) 2010 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$ +** Commercial Usage +** Licensees holding valid Qt Commercial licenses may use this file in +** accordance with the Qt Commercial License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in a +** written agreement between you and Nokia. +** +** 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-positioners.html +\title Using QML Positioner and Repeater Items + +\section1 Introduction + +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 and repeaters 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 +\o \l{#Column}{Column} arranges its children in a column +\o \l{#Row}{Row} arranges its children in a row +\o \l{#Grid}{Grid} arranges its children in a grid +\o \l{#Flow}{Flow} arranges its children like words on a page +\endlist + +\section2 Column + +\beginfloatright +\image qml-column.png +\endfloat + +\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. + +\clearfloat +\snippet doc/src/snippets/declarative/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 + +\beginfloatright +\image qml-row.png +\endfloat + +\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. + +\clearfloat +\snippet doc/src/snippets/declarative/row.qml document + +\section2 Grid + +\beginfloatright +\image qml-grid-spacing.png +\endfloat + +\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. + +\clearfloat +\snippet doc/src/snippets/declarative/grid/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 + +\beginfloatright +\image qml-flow-text1.png +\image qml-flow-text2.png +\endfloat + +\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. + +\clearfloat +\snippet doc/src/snippets/declarative/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 Repeaters + +\beginfloatright +\image qml-repeater-grid-index.png +\endfloat + +Repeaters create items from a template for use with positioners, using data +from a model. Combining repeaters and positioners is an easy way to lay out +lots of items. A \l Repeater item is placed inside a positioner, and generates +items that the enclosing positioner arranges. + +Each Repeater creates a number of items by combining each element of data +from a model, specified using the \l{Repeater::model}{model} property, with +the template item, defined as a child item within the Repeater. +The total number of items is determined by the amount of data in the model. + +The following example shows a repeater used with a \l{#Grid}{Grid} item to +arrange a set of Rectangle items. The Repeater item creates a series of 24 +rectangles for the Grid item to position in a 5 by 5 arrangement. + +\clearfloat +\snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document + +The number of items created by a Repeater is held by its \l{Repeater::}{count} +property. It is not possible to set this property to determine the number of +items to be created. Instead, as in the above example, we use an integer as +the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} +document. + +It is also possible to use a delegate as the template for the items created +by a Repeater. This is specified using the \l{Repeater::}{delegate} property. + +\section1 Using Transitions + +Transitions can be used to animate items that are added to, moved within, +or removed from a positioner. + +Transitions for adding items apply to items that are created as part of a +positioner, as well as those that are reparented to become children of a +positioner. +Transitions for removing items apply to items within a positioner that are +deleted, as well as those that are removed from a positioner and given new +parents in a document. + +Additionally, changing the opacity of items to zero will cause them to +disappear using the remove transition, and making the opacity non-zero will +cause them to appear using the add transition. + +\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}. +*/ -- cgit v0.12