← Back to branch summary

~saviq/ubuntu/saucy/qtdeclarative-opensource-src/add-qtquick-delegate-range

« back to all changes in this revision

Viewing changes to src/quick/doc/src/concepts/positioning/topic.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 14:17:19 UTC
  • Revision ID: package-import@ubuntu.com-20130205141719-qqeyml8wslpyez52
Tags: upstream-5.0.1
Import upstream version 5.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/quick/doc/src/concepts/positioning/topic.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
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 Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/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 qtquick-positioning-topic.html
 
30
\title Important Concepts In Qt Quick - Positioning
 
31
\brief Overview of positioning concepts
 
32
 
 
33
Visual items in QML can be positioned in a variety of ways.  The most important
 
34
positioning-related concept is that of anchoring, a form of relative
 
35
positioning where items can be anchored (or attached) to each other at certain
 
36
boundaries.  Other positioning concepts include absolute positioning,
 
37
positioning with coordinate bindings, and layouts.
 
38
 
 
39
 
 
40
\section1 Manual Positioning
 
41
 
 
42
Items can be positioned manually.  If the user-interface is going to be
 
43
static, manual positioning provides the most efficient form of positioning.
 
44
 
 
45
In any user-interface, the visual elements exist at a particular location in
 
46
the screen coordinates at any instant in time.  While fluidly animated and
 
47
dynamic user-interfaces are a major focus of Qt Quick, statically-positioned
 
48
user interfaces are still a viable option.  What's more, if the position of
 
49
those elements does not change, it can often be more performant to specify
 
50
the position manually than to use the more dynamic positioning methods
 
51
documented in proceeding sections.
 
52
 
 
53
In Qt Quick, every visual object is positioned within the
 
54
\l{qtquick-visual-coordinates.html}{coordinate system}
 
55
provided by the Qt Quick visual canvas.  As described in that document, the
 
56
x and y coordinates of a visual object are relative to those of its visual
 
57
parent, with the top-left corner having the coordinate (0, 0).
 
58
 
 
59
Thus, the following example will display two rectangles positioned manually:
 
60
 
 
61
\table
 
62
    \header
 
63
    \li Example Code
 
64
    \li Resultant Layout
 
65
 
 
66
    \row
 
67
    \li
 
68
        \qml
 
69
        import QtQuick 2.0
 
70
 
 
71
        Item {
 
72
            width: 200
 
73
            height: 200
 
74
 
 
75
            Rectangle {
 
76
                x: 50
 
77
                y: 50
 
78
                width: 100
 
79
                height: 100
 
80
                color: "green"
 
81
             }
 
82
 
 
83
             Rectangle {
 
84
                x: 100
 
85
                y: 100
 
86
                width: 50
 
87
                height: 50
 
88
                color: "yellow"
 
89
             }
 
90
        }
 
91
        \endqml
 
92
    \li
 
93
        \image manual-layout.png
 
94
\endtable
 
95
 
 
96
\section1 Positioning With Bindings
 
97
 
 
98
Items may also be positioned by assigning binding expressions to the properties
 
99
associated with their location in the visual canvas.  This type of positioning
 
100
is the most highly dynamic, however some performance cost is associated with
 
101
positioning items in this manner.
 
102
 
 
103
The position and dimensions of a visual object can also be set through property
 
104
bindings.  This has the advantage that the values will automatically be updated
 
105
as the dependencies of the bindings change.  For example, the width of one
 
106
Rectangle might depend on the width of the Rectangle next to it.
 
107
 
 
108
While bindings provide a very flexible and intuitive way of creating dynamic
 
109
layouts, it should be noted that there is some performance cost associated with
 
110
them, and where possible, pristine Anchor layouts should be preferred.
 
111
 
 
112
 
 
113
\section1 Anchors
 
114
 
 
115
Anchors allows an item to be placed either adjacent to or inside of another,
 
116
by attaching one or more of the item's anchor-points (boundaries) to an
 
117
anchor-point of the other.  These anchors will remain even if the dimensions
 
118
or location of one of the items changes, allowing for highly dynamic
 
119
user-interfaces.
 
120
 
 
121
A visual object can be thought of as having various anchor-points (or more
 
122
correctly, anchor-lines).  Other items can be anchored to those points, which
 
123
means that as any object changes, the other objects which are anchored to it
 
124
will adjust automatically to maintain the anchoring.
 
125
 
 
126
Qt Quick provides anchors as a top-level concept.  See the documentation about
 
127
\l{qtquick-positioning-anchors.html}{positioning with anchors}
 
128
for in-depth information on the topic.
 
129
 
 
130
It is important to note that anchor-based layouts are generally far more
 
131
performant than binding-based layouts, if pristine.  A "pristine" anchor layout
 
132
is one which uses only anchors (with object nesting) to determine the
 
133
positioning, whereas a "contaminated" anchor layout is one which uses both
 
134
anchoring and bindings (either on position-related [x,y] properties or on
 
135
dimension-related [width,height] properties) to determine the position.
 
136
 
 
137
\section1 Layouts
 
138
 
 
139
Qt Quick also provides some built-in layout items.  For many use cases, the
 
140
best layout to use is a simple grid, row, or column, and Qt Quick provides
 
141
items which will layout children in these formations in the most efficient
 
142
manner possible.
 
143
 
 
144
There are many well-known layouts which work well in user-interfaces, such as
 
145
grids and lists, rows and columns.  Qt Quick supports these sort of pre-defined
 
146
layouts, which can often be more performant to draw than anchor or
 
147
binding-based layouts.  See the documentation on
 
148
\l{qtquick-positioning-layouts.html}{layout elements} for more
 
149
information about utilizing pre-defined layouts.
 
150
 
 
151
 
 
152
 
 
153
\section1 Right-To-Left Support
 
154
 
 
155
The directionality of the written form of a language often has a great impact
 
156
on how the visual elements of a user-interface should be positioned.  Qt Quick
 
157
supports right-to-left positioning of elements through the predefined-layouts
 
158
as well as right-to-left text layouts.
 
159
 
 
160
Please see the documentation about
 
161
\l{qtquick-positioning-righttoleft.html}
 
162
{right-to-left support in Qt Quick} for in-depth information on the topic.
 
163
 
 
164
 
 
165
*/
 
166