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