src/quick/doc/src/concepts/positioning/topic.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  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 have the value [0, 0].
  58
  59 Thus, the following example will display three 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         Rectangle {
  72             id: r1
  73             x: 0
  74             y: 0
  75             width: 200
  76             height: 200
  77
  78             Rectangle {
  79                 id: r2
  80                 x: 0
  81                 y: 100
  82                 width: 100
  83                 height: 100
  84             }
  85
  86             Rectangle {
  87                 id: r3
  88                 x: 100
  89                 y: 100
  90                 width: 50
  91                 height: 100
  92             }
  93         }
  94         \endqml
  95     \li
  96         \image manual-layout.png
  97 \endtable
  98
  99 \section1 Positioning With Bindings
 100
 101 Items may also be positioned by assigning binding expressions to the properties
 102 associated with their location in the visual canvas.  This type of positioning
 103 is the most highly dynamic, however some performance cost is associated with
 104 positioning items in this manner.
 105
 106 The position and dimensions of a visual object can also be set through property
 107 bindings.  This has the advantage that the values will automatically be updated
 108 as the dependencies of the bindings change.  For example, the width of one
 109 Rectangle might depend on the width of the Rectangle next to it.
 110
 111 While bindings provide a very flexible and intuitive way of creating dynamic
 112 layouts, it should be noted that there is some performance cost associated with
 113 them, and where possible, pristine Anchor layouts should be preferred.
 114
 115
 116 \section1 Anchors
 117
 118 Anchors allows an item to be placed either adjacent to or inside of another,
 119 by attaching one or more of the item's anchor-points (boundaries) to an
 120 anchor-point of the other.  These anchors will remain even if the dimensions
 121 or location of one of the items changes, allowing for highly dynamic
 122 user-interfaces.
 123
 124 A visual object can be thought of as having various anchor-points (or more
 125 correctly, anchor-lines).  Other items can be anchored to those points, which
 126 means that as any object changes, the other objects which are anchored to it
 127 will adjust automatically to maintain the anchoring.
 128
 129 Qt Quick provides anchors as a top-level concept.  See the documentation about
 130 \l{qtquick-positioning-anchors.html}{positioning with anchors}
 131 for in-depth information on the topic.
 132
 133 It is important to note that anchor-based layouts are generally far more
 134 performant than binding-based layouts, if pristine.  A "pristine" anchor layout
 135 is one which uses only anchors (with object nesting) to determine the
 136 positioning, whereas a "contaminated" anchor layout is one which uses both
 137 anchoring and bindings (either on position-related [x,y] properties or on
 138 dimension-related [width,height] properties) to determine the position.
 139
 140 \section1 Layouts
 141
 142 Qt Quick also provides some built-in layout items.  For many use cases, the
 143 best layout to use is a simple grid, row, or column, and Qt Quick provides
 144 items which will layout children in these formations in the most efficient
 145 manner possible.
 146
 147 There are many well-known layouts which work well in user-interfaces, such as
 148 grids and lists, rows and columns.  Qt Quick supports these sort of pre-defined
 149 layouts, which can often be more performant to draw than anchor or
 150 binding-based layouts.  See the documentation on
 151 \l{qtquick-positioning-layouts.html}{layout elements} for more
 152 information about utilizing pre-defined layouts.
 153
 154
 155
 156 \section1 Right-To-Left Support
 157
 158 The directionality of the written form of a language often has a great impact
 159 on how the visual elements of a user-interface should be positioned.  Qt Quick
 160 supports right-to-left positioning of elements through the predefined-layouts
 161 as well as right-to-left text layouts.
 162
 163 Please see the documentation about
 164 \l{qtquick-positioning-righttoleft.html}
 165 {right-to-left support in Qt Quick} for in-depth information on the topic.
 166
 167
 168 */
 169