doc/src/declarative/scope.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qdeclarativescope.html
  29 \title QML Scope
  30
  31 \tableofcontents
  32
  33 QML property bindings, inline functions and imported JavaScript files all
  34 run in a JavaScript scope.  Scope controls which variables an expression can
  35 access, and which variable takes precedence when two or more names conflict.
  36
  37 As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit
  38 more naturally with the QML language extensions.
  39
  40 \section1 JavaScript Scope
  41
  42 QML's scope extensions do not interfere with JavaScript's natural scoping.
  43 JavaScript programmers can reuse their existing knowledge when programming
  44 functions, property bindings or imported JavaScript files in QML.
  45
  46 In the following example, the \c {addConstant()} method will add 13 to the
  47 parameter passed just as the programmer would expect irrespective of the
  48 value of the QML object's \c a and \c b properties.
  49
  50 \code
  51 QtObject {
  52     property int a: 3
  53     property int b: 9
  54
  55     function addConstant(b) {
  56         var a = 13;
  57         return b + a;
  58     }
  59 }
  60 \endcode
  61
  62 That QML respects JavaScript's normal scoping rules even applies in bindings.
  63 This totally evil, abomination of a binding will assign 12 to the QML object's
  64 \c a property.
  65
  66 \code
  67 QtObject {
  68     property int a
  69
  70     a: { var a = 12; a; }
  71 }
  72 \endcode
  73
  74 Every JavaScript expression, function or file in QML has its own unique
  75 variable object.  Local variables declared in one will never conflict
  76 with local variables declared in another.
  77
  78 \section1 Element Names and Imported JavaScript Files
  79
  80 \l {QML Document}s include import statements that define the element names
  81 and JavaScript files visible to the document.  In addition to their use in the
  82 QML declaration itself, element names are used by JavaScript code when accessing
  83 \l {Attached Properties} and enumeration values.
  84
  85 The effect of an import applies to every property binding, and JavaScript
  86 function in the QML document, even those in nested inline components.  The
  87 following example shows a simple QML file that accesses some enumeration
  88 values and calls an imported JavaScript function.
  89
  90 \code
  91 import QtQuick 1.0
  92 import "code.js" as Code
  93
  94 ListView {
  95     snapMode: ListView.SnapToItem
  96
  97     delegate: Component {
  98         Text {
  99             elide: Text.ElideMiddle
 100             text: "A really, really long string that will require eliding."
 101             color: Code.defaultColor()
 102         }
 103     }
 104 }
 105 \endcode
 106
 107 \section1 Binding Scope Object
 108
 109 Property bindings are the most common use of JavaScript in QML.  Property
 110 bindings associate the result of a JavaScript expression with a property of an
 111 object.  The object to which the bound property belongs is known as the binding's
 112 scope object.  In this QML simple declaration the \l Item object is the
 113 binding's scope object.
 114
 115 \code
 116 Item {
 117     anchors.left: parent.left
 118 }
 119 \endcode
 120
 121 Bindings have access to the scope object's properties without qualification.
 122 In the previous example, the binding accesses the \l Item's \c parent property
 123 directly, without needing any form of object prefix.  QML introduces a more
 124 structured, object-oriented approach to JavaScript, and consequently does not
 125 require the use of the JavaScript \c this property.
 126
 127 Care must be used when accessing \l {Attached Properties} from bindings due
 128 to their interaction with the scope object.  Conceptually attached properties
 129 exist on \e all objects, even if they only have an effect on a subset of those.
 130 Consequently unqualified attached property reads will always resolve to an
 131 attached property on the scope object, which is not always what the programmer
 132 intended.
 133
 134 For example, the \l PathView element attaches interpolated value properties to
 135 its delegates depending on their position in the path.  As PathView only
 136 meaningfully attaches these properties to the root element in the delegate, any
 137 sub-element that accesses them must explicitly qualify the root object, as shown
 138 below.
 139
 140 \code
 141 PathView {
 142     delegate: Component {
 143         Rectangle {
 144             id: root
 145             Image {
 146                 scale: root.PathView.scale
 147             }
 148         }
 149     }
 150 }
 151 \endcode
 152
 153 If the \l Image element omitted the \c root prefix, it would inadvertently access
 154 the unset \c {PathView.scale} attached property on itself.
 155
 156 \section1 Component Scope
 157
 158 Each QML component in a QML document defines a logical scope.  Each document
 159 has at least one root component, but can also have other inline sub-components.
 160 The component scope is the union of the object ids within the component and the
 161 component's root element's properties.
 162
 163 \code
 164 Item {
 165     property string title
 166
 167     Text {
 168         id: titleElement
 169         text: "<b>" + title + "</b>"
 170         font.pixelSize: 22
 171         anchors.top: parent.top
 172     }
 173
 174     Text {
 175         text: titleElement.text
 176         font.pixelSize: 18
 177         anchors.bottom: parent.bottom
 178     }
 179 }
 180 \endcode
 181
 182 The example above shows a simple QML component that displays a rich text title
 183 string at the top, and a smaller copy of the same text at the bottom.  The first
 184 \c Text element directly accesses the component's \c title property when
 185 forming the text to display.  That the root element's properties are directly
 186 accessible makes it trivial to distribute data throughout the component.
 187
 188 The second \c Text element uses an id to access the first's text directly.  IDs
 189 are specified explicitly by the QML programmer so they always take precedence
 190 over other property names (except for those in the \l {JavaScript Scope}).  For
 191 example, in the unlikely event that the binding's \l {Binding Scope Object}{scope
 192 object}  had a \c titleElement property in the previous example, the \c titleElement
 193 id would still take precedence.
 194
 195 \section1 Component Instance Hierarchy
 196
 197 In QML, component instances connect their component scopes together to form a
 198 scope hierarchy.  Component instances can directly access the component scopes of
 199 their ancestors.
 200
 201 The easiest way to demonstrate this is with inline sub-components whose component
 202 scopes are implicitly scoped as children of the outer component.
 203
 204 \code
 205 Item {
 206     property color defaultColor: "blue"
 207
 208     ListView {
 209         delegate: Component {
 210             Rectangle {
 211                 color: defaultColor
 212             }
 213         }
 214     }
 215 }
 216 \endcode
 217
 218 The component instance hierarchy allows instances of the delegate component
 219 to access the \c defaultColor property of the \c Item element.  Of course,
 220 had the delegate component had a property called \c defaultColor that would
 221 have taken precedence.
 222
 223 The component instance scope hierarchy extends to out-of-line components, too.
 224 In the following example, the \c TitlePage.qml component creates two
 225 \c TitleText instances.  Even though the \c TitleText element is in a separate
 226 file, it still has access to the \c title property when it is used from within
 227 the \c TitlePage.  QML is a dynamically scoped language - depending on where it
 228 is used, the \c title property may resolve differently.
 229
 230 \code
 231 // TitlePage.qml
 232 import QtQuick 1.0
 233 Item {
 234     property string title
 235
 236     TitleText {
 237         size: 22
 238         anchors.top: parent.top
 239     }
 240
 241     TitleText {
 242         size: 18
 243         anchors.bottom: parent.bottom
 244     }
 245 }
 246
 247 // TitleText.qml
 248 import QtQuick 1.0
 249 Text {
 250     property int size
 251     text: "<b>" + title + "</b>"
 252     font.pixelSize: size
 253 }
 254 \endcode
 255
 256 Dynamic scoping is very powerful, but it must be used cautiously to prevent
 257 the behavior of QML code from becoming difficult to predict.  In general it
 258 should only be used in cases where the two components are already tightly
 259 coupled in another way.  When building reusable components, it is preferable
 260 to use property interfaces, like this:
 261
 262 \code
 263 // TitlePage.qml
 264 import QtQuick 1.0
 265 Item {
 266     id: root
 267     property string title
 268
 269     TitleText {
 270         title: root.title
 271         size: 22
 272         anchors.top: parent.top
 273     }
 274
 275     TitleText {
 276         title: root.title
 277         size: 18
 278         anchors.bottom: parent.bottom
 279     }
 280 }
 281
 282 // TitleText.qml
 283 import QtQuick 1.0
 284 Text {
 285     property string title
 286     property int size
 287
 288     text: "<b>" + title + "</b>"
 289     font.pixelSize: size
 290 }
 291 \endcode
 292
 293 \section1 JavaScript Global Object
 294
 295 In addition to all the properties that a developer would normally expect on
 296 the JavaScript global object, QML adds some custom extensions to make UI or
 297 QML specific tasks a little easier.  These extensions are described in the
 298 \l {QML Global Object} documentation.
 299
 300 QML disallows element, id and property names that conflict with the properties
 301 on the global object to prevent any confusion.  Programmers can be confident
 302 that \c Math.min(10, 9) will always work as expected!
 303
 304 */