doc/src/declarative/propertybinding.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 /*!
  29 \page propertybinding.html
  30 \ingroup qml-features
  31 \contentspage QML Features
  32 \previouspage {QML Basic Types}{Data Types}
  33 \nextpage {Using QML Positioner and Repeater Items}{Component Layouts}
  34 \title Property Binding
  35
  36 \section1 Properties
  37
  38 QML components have \e properties that can be read and modified by other objects.
  39 In QML, properties serve many purposes but their main function is to bind to
  40 values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements.
  41
  42 The syntax for properties is:
  43
  44 \tt{[default] property <type> <name>[: defaultValue]}
  45
  46 Elements already possess useful properties but, to create custom properties,
  47 precede the property name with the keyword \c property.
  48
  49 \snippet doc/src/snippets/declarative/properties.qml parent begin
  50 \snippet doc/src/snippets/declarative/properties.qml inherited properties
  51 \snippet doc/src/snippets/declarative/properties.qml custom properties
  52 \snippet doc/src/snippets/declarative/properties.qml parent end
  53
  54 QML property rules coincide with many of JavaScript's property rules, for example,
  55 property names must begin with a lowercase letter.
  56 \l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property
  57 names.
  58
  59 \section1 Property Binding
  60
  61 Property binding is a declarative way of specifying the value of a property. Binding allows
  62 a property's value to be expressed as an JavaScript expression that defines the value relative
  63 to other property values or data accessible in the application. The property value is
  64 automatically kept up to date if the other properties or data values change.
  65
  66 Property bindings are created in QML using the colon "\c {:}" before the value:
  67 \snippet doc/src/snippets/declarative/properties.qml property binding
  68 The property binding causes the width of the \c Rectangle to update whenever the
  69 \c {parent}'s width changes.
  70
  71 QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be
  72 used as a property binding. Bindings can access object properties, make function calls and even
  73 use built-in JavaScript objects such as \c {Date} and \c {Math}.
  74 \snippet doc/src/snippets/declarative/properties.qml JavaScript sample
  75
  76 While syntactically bindings can be of arbitrary complexity, if a binding starts to become
  77 overly complex - such as involving multiple lines, or imperative loops - it may be better
  78 to refactor the component entirely, or at least factor the binding out into a separate
  79 function.
  80
  81 \keyword qml-javascript-assignment
  82 \section1 Property Assignment versus Property Binding
  83
  84 When working with both QML and JavaScript, it is important to differentiate between
  85 QML property binding and JavaScript value assignment. In QML, a property
  86 binding is created using the colon "\c {:}".
  87 \snippet doc/src/snippets/declarative/properties.qml property binding
  88 The property binding causes the width of the \c Rectangle to update whenever the
  89 \c {parent}'s width changes.
  90
  91 Assigning a property value (using the equals sign "\c {=}") does not create a
  92 property binding.
  93 \snippet doc/src/snippets/declarative/properties.qml property assignment
  94
  95 Instead of creating a property binding, the assignment simply sets the \c Rectangle
  96 \c width value to a number when the \c Component.onCompleted code is invoked.
  97
  98 Assigning a value to a property that is already bound will remove the previous binding.
  99 A property can only have one value at a time (a list of property is one value),
 100 and if any code explicitly re-sets this value, the property binding is removed.
 101
 102 There is no way to create a property binding directly from imperative JavaScript code,
 103 although it is possible to use the \l {Using the Binding Element}{Binding} element.
 104
 105 \section1 Types of Properties
 106
 107 Properties may bind to different types, but they are are \e type-safe. That is,
 108 properties only allow you to assign a value that matches the property type. For
 109 example, if a property is a real, and if you try to assign a string to it you
 110 will get an error.
 111
 112 \badcode
 113 property real volume: "four"  //generates an error
 114 \endcode
 115
 116 Certain properties bind to more complex types such as other elements and objects.
 117
 118 \keyword qml-basic-property-types
 119 \section2 Basic Property Types
 120
 121 Basic types such as \l int, \l real, and other Qt structures may be bound to
 122 properties. For a list of types, visit the \l {QML Basic Types} document.
 123
 124 \keyword qml-id-property
 125 \section2 The \c id Property
 126
 127 Each QML object may be given a special unique property called an \c id.
 128 No other object within the same QML component (see \l{QML Documents}) can have
 129 the same \c id value. QML objects may then access an object using the \c id
 130 property.
 131 \snippet doc/src/snippets/declarative/properties.qml id property
 132 A component may readily access its parent's properties by using the \c parent
 133 property.
 134
 135 Note that an \c id must begin with a lower-case letter or an underscore. The
 136 \c id cannot contain characters other than letters, numbers, underscores, and
 137 \l {JavaScript Reserved Words}{JavaScript reserved words}.
 138
 139 \section2 Elements and Objects as Property Values
 140
 141 Many properties bind to objects. For example, the \l Item element has a
 142 \c states property that can bind to \l State elements. This type of property
 143 binding allows elements to carry additional non-children elements. \c Item's
 144 \c transitions property behaves in a similar way; it can bind to \l Transition
 145 elements.
 146
 147 Care must be taken when referring to the parent of an object property binding.
 148 Elements and components that are bound to properties are not necessarily set
 149 as children of the properties' component.
 150
 151 \snippet doc/src/snippets/declarative/properties.qml object binding
 152 The code snippet has a \l Gradient element that attempts to print its parent's
 153 \c width value. However, the \c Gradient element is bound to the \c gradient
 154 property, not the \c children property of the \c Rectangle. As a result, the
 155 \c Gradient does not have the \c Rectangle as its parent. Printing the value
 156 of \c{parent.width} generates an error. Printing the \c Rectangle object's
 157 first child's \c name will print \c {childrectangle} because the second
 158 \c Rectangle is bound to the \c children property.
 159
 160 For more information about the \c children property, please read the
 161 \l {Default Properties} section.
 162
 163 \keyword attached-properties
 164 \section2 Attached Properties
 165
 166 Certain objects provide additional properties by \e attaching properties to other
 167 objects. For example, the \l Keys element have properties that can \e attach to other QML
 168 objects to provide keyboard handling.
 169
 170 \snippet doc/src/snippets/declarative/properties.qml list attached property
 171 The element \l ListView provides the delegate, \c listdelegate, the property
 172 \c isCurrentItem as an attached property. The \c ListView.isCurrentItem
 173 \e{attached property} provides highlight information to the delegate.
 174 Effectively, the \l ListView element attaches the \c ListView.isCurrentItem
 175 property to each delegate it creates.
 176
 177 \keyword attached-signalhandlers
 178 \section2 Attached Signal Handlers
 179
 180 \e {Attached signal handlers} are similar
 181 to \l{Attached Properties}{attached properties} in that they attach to objects
 182 to provide additional functionality to objects. Two prominent elements,
 183 \l Component and \l Keys element provide
 184 \l{QML Signal and Handler Event System}{signal handlers} as attached signal
 185 handlers.
 186 \snippet doc/src/snippets/declarative/properties.qml attached signal handler
 187
 188 Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML}
 189 articles for more information.
 190
 191 \section2 List properties
 192
 193 Some properties may accept a binding to a list property, where more than one
 194 component can bind to the property. List properties allow multiple
 195 \l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a
 196 single property.
 197 \snippet doc/src/snippets/declarative/properties.qml list property
 198 The list is enclosed in square brackets, with a comma separating the
 199 list elements. In cases where you are only assigning a single item to a
 200 list, you may omit the square brackets.
 201 \snippet doc/src/snippets/declarative/properties.qml single property
 202
 203 To access the list, use the \c index property.
 204 \snippet doc/src/snippets/declarative/properties.qml print list property
 205 The snippet code simply prints the name of the first state, \c FETCH.
 206
 207  See the \l{list}{list type} documentation
 208 for more details about list properties and their available operations.
 209
 210 \keyword qml-grouped-properties
 211 \section2 Grouped Properties
 212
 213 In some cases properties form a logical group and use either the \e dot notation
 214 or \e group notation.
 215
 216 Grouped properties may be written both ways:
 217 \snippet doc/src/snippets/declarative/properties.qml grouped properties
 218
 219 In the element documentation grouped properties are shown using the dot notation.
 220
 221 \section2 Property Aliases
 222
 223 Unlike a property definition, which allocates a new, unique storage space for
 224 the property, a property alias connects the newly declared property, called the
 225 \e{aliasing property} as a direct reference to an existing property, the
 226 \e{aliased property}. Read or write operations on the aliasing property results
 227 in a read or write operations on the aliased property, respectively.
 228
 229 A property alias declaration is similar to an ordinary property definition:
 230
 231 \tt{[default] property alias <name>: <alias reference>}
 232
 233 As the aliasing property has the same type as the aliased property, an explicit
 234 type is omitted, and the special \c alias keyword is before the property name.
 235 Instead of a default value, a property alias has a compulsory alias reference.
 236 Accessing the aliasing property is similar to accessing a regular property. In
 237 addition, the optional \c default keyword indicates that the aliasing property
 238 is a \l{Default Properties}{default property}.
 239
 240 \snippet doc/src/snippets/declarative/Button.qml property alias
 241 When importing the component as a \c Button, the \c buttonlabel is directly
 242 accessible through the \c label property.
 243 \snippet doc/src/snippets/declarative/properties.qml alias usage
 244 In addition, the \c id property may also be aliased and referred outside the
 245 component.
 246 \snippet doc/src/snippets/declarative/Button.qml parent begin
 247 \snippet doc/src/snippets/declarative/Button.qml id alias
 248 \snippet doc/src/snippets/declarative/Button.qml parent end
 249 The \c imagebutton component has the ability to modify the child \l Image object
 250  and its properties.
 251 \snippet doc/src/snippets/declarative/properties.qml image alias
 252
 253 Using aliases, properties may be exposed to the
 254 \l{qml-top-level-component}{top level component}. Exposing properties to the
 255 top-level component allows components to have interfaces similar to Qt widgets.
 256
 257 \section3 Considerations for property aliases
 258
 259 Aliases are only activated once the component
 260 \l{Component::onCompleted}{completes} its initialization. An error is generated
 261 when an uninitialized alias is referenced. Likewise, aliasing an aliasing
 262 property will also result in an error.
 263
 264 \snippet doc/src/snippets/declarative/properties.qml alias complete
 265
 266 When importing the component, however, aliasing properties appear as regular Qt
 267 properties and consequently can be used in alias references.
 268
 269 It is possible for an aliasing property to have the same name as an existing
 270 property, effectively overwriting the existing property. For example,
 271 the following component has a \c color alias property, named the same as the built-in
 272 \l {Rectangle::color} property:
 273
 274 \snippet doc/src/snippets/declarative/properties.qml alias overwrite
 275
 276 Any object that use this component and refer to its \c color property will be
 277 referring to the alias rather than the ordinary \l {Rectangle::color} property.
 278 Internally, however, the \c coloredrectangle can correctly set its \c color
 279 property and refer to the actual defined property rather than the alias.
 280
 281 The \l{declarative/ui-components/tabwidget}{TabWidget} example uses
 282 aliases to reassign children to the \l ListView, creating a tab effect.
 283
 284 \keyword default-properties
 285 \section2 Default Properties
 286
 287 When imported, QML components will bind declared children to their designated
 288 \e{default properties}. The optional \c default attribute specifies a property
 289 as the \e {default property}. For example, the State element's default property
 290 is its \l{State::changes}{changes} property. \l PropertyChanges elements
 291 may simply be placed as the \c{State}'s children and they will be bound to the
 292 \c changes property.
 293 \snippet doc/src/snippets/declarative/properties.qml state default
 294
 295 Similarly, the \l Item element's default property is its
 296 \l{Item::data}{data} property. The \c data property manages Item's
 297 \c children and \c resources properties. This way, different data types may be
 298 placed as direct children of the \c Item.
 299 \snippet doc/src/snippets/declarative/properties.qml default property
 300
 301 Reassigning a default property is useful when a component is reused. For
 302 example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses
 303 the \c default attribute to reassign children to the \l ListView, creating
 304 a tab effect.
 305
 306 \section1 Using the Binding Element
 307
 308 In some advanced cases, it may be necessary to create bindings explicitly with
 309 the\l Binding element.
 310
 311 For example, to bind a property exposed from C++ (\c system.brightness) to a
 312 value written in QML (\c slider.value), you could use the \l Binding element as
 313 follows:
 314 \snippet doc/src/snippets/declarative/properties.qml binding element
 315
 316 \section1 Changing Property Values in States
 317
 318 The \l PropertyChanges element is for setting property bindings within a
 319 \l State element to set a property binding.
 320
 321 \snippet doc/src/snippets/declarative/properties.qml PropertyChanges element
 322 The rectangle's \c color property will bind to the \c warning component's
 323 \c color property when its \c state is set to the \c WARNING state.
 324 */