doc/src/declarative/scope.qdoc

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