diff options
Diffstat (limited to 'doc/src/declarative/propertybinding.qdoc')
| -rw-r--r-- | doc/src/declarative/propertybinding.qdoc | 414 |
1 files changed, 260 insertions, 154 deletions
diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 379a4ec..88ec5c3 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -27,192 +27,298 @@ /*! \page propertybinding.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Basic Types}{Data Types} +\nextpage {Using QML Positioner and Repeater Items}{Component Layouts} \title Property Binding -Property binding is a declarative way of specifying the value of a property. Binding allows -a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is -automatically kept up to date if the other properties or data values change. +\section1 Properties -Property bindings are created implicitly in QML whenever a property is assigned an JavaScript -expression. The following QML uses two property bindings to connect the size of the rectangle -to that of \c otherItem. +QML components have \e properties that can be read and modified by other objects. +In QML, properties serve many purposes but their main function is to bind to +values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. -\code -Rectangle { - width: otherItem.width - height: otherItem.height -} -\endcode +The syntax for properties is: -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be -used as a property binding. Bindings can access object properties, make function calls and even -use builtin JavaScript objects like \e {Date} and \e {Math}. Assigning a constant value to a -property can even be thought of as a binding - after all, a constant is a valid JavaScript -expression! Here are some examples of more complex bindings: - -\code -Rectangle { - function calculateMyHeight() { - return Math.max(otherItem.height, thirdItem.height); - } - - anchors.centerIn: parent - width: Math.min(otherItem.width, 10) - height: calculateMyHeight() - color: { if (width > 10) "blue"; else "red" } -} -\endcode +\tt{[default] property <type> <name>[: defaultValue]} -While syntactically bindings can be of arbitrary complexity, if a binding starts to become -overly complex - such as involving multiple lines, or imperative loops - it may be better -to refactor the component entirely, or at least factor the binding out into a separate -function. +Elements already possess useful properties but, to create custom properties, +precede the property name with the keyword \c property. -\section1 Changing Bindings - -The \l PropertyChanges element can be used within a state change to modify the bindings on -properties. - -This example modifies the \l Rectangle's width property binding to be \c {otherItem.height} -when in the "square" state. When it returns to its default state, width's original property -binding will have been restored. - -\code -Rectangle { - id: rectangle - width: otherItem.width - height: otherItem.height - - states: State { - name: "square" - PropertyChanges { - target: rectangle - width: otherItem.height - } - } -} -\endcode +\snippet doc/src/snippets/declarative/properties.qml parent begin +\snippet doc/src/snippets/declarative/properties.qml inherited properties +\snippet doc/src/snippets/declarative/properties.qml custom properties +\snippet doc/src/snippets/declarative/properties.qml parent end +QML property rules coincide with many of JavaScript's property rules, for example, +property names must begin with a lowercase letter. +\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property +names. -\section1 Binding Properties from JavaScript +\section1 Property Binding -When working with both QML and JavaScript, it is important to differentiate between -\l {Property Binding} syntax in QML and simple \e {property assignment} in JavaScript. Take -the example below, which uses property binding to ensure the item's \c height is always twice -its \c width: - -\qml -Item { - width: 100 - height: width * 2 -} -\endqml - -On the other hand, take the following JavaScript code snippet, which \e assigns, rather -than \e binds, the value of the \c height property: - -\code -Item { - width: 100 - - Component.onCompleted: { - height = width * 2 // if width changes later, height is not updated! - } -} -\endcode +Property binding is a declarative way of specifying the value of a property. Binding allows +a property's value to be expressed as an JavaScript expression that defines the value relative +to other property values or data accessible in the application. The property value is +automatically kept up to date if the other properties or data values change. -Instead of creating a property binding, this simply sets the \c height property to the correct -value \e {at the time that} the JavaScript code is invoked. Unlike the first example, the -\c height will never change if \c width changes. +Property bindings are created in QML using the colon "\c {:}" before the value: +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. -The \e {property : value} syntax for property binding is QML-specific and cannot be used in -JavaScript. Instead, to bind a property from JavaScript, assign a \e function to the property -that returns the required value. The following code correctly sets the property binding -created in the first example, but creates the binding in JavaScript rather than QML: +QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be +used as a property binding. Bindings can access object properties, make function calls and even +use built-in JavaScript objects such as \c {Date} and \c {Math}. +\snippet doc/src/snippets/declarative/properties.qml JavaScript sample -\qml -Item { - width: 100 +While syntactically bindings can be of arbitrary complexity, if a binding starts to become +overly complex - such as involving multiple lines, or imperative loops - it may be better +to refactor the component entirely, or at least factor the binding out into a separate +function. - Component.onCompleted: { - height = (function() { return width * 2 }) - } -} -\endqml +\keyword qml-javascript-assignment +\section1 Property Assignment versus Property Binding +When working with both QML and JavaScript, it is important to differentiate between +QML property binding and JavaScript value assignment. In QML, a property +binding is created using the colon "\c {:}". +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. -\section2 Using \c this to create a binding +Assigning a property value (using the equals sign "\c {=}") does not create a +property binding. +\snippet doc/src/snippets/declarative/properties.qml property assignment -When creating a property binding from JavaScript, QML allows the use of the \c this keyword to -refer to the object to which the property binding will be assigned. This allows one to -explicitly refer to a property within an object when there may be ambiguity about the exact -property that should be used for the binding. +Instead of creating a property binding, the assignment simply sets the \c Rectangle +\c width value to a number when the \c Component.onCompleted code is invoked. -For example, the \c Component.onCompleted handler below is defined within the scope of the -\l Item, and references to \c width within this scope would refer to the \l Item's width, rather -than that of the \l Rectangle. To bind the \l Rectangle's \c height to its own \c width, the -function needs to explicitly refer to \c this.width rather than just \c width. Otherwise, the -height of the \l Rectangle would be bound to the width of the \l Item and not the \l Rectangle. +Assigning a value to a property that is already bound will remove the previous binding. +A property can only have one value at a time (a list of property is one value), +and if any code explicitly re-sets this value, the property binding is removed. -\qml -Item { - width: 500 - height: 500 +There is no way to create a property binding directly from imperative JavaScript code, +although it is possible to use the \l {Using the Binding Element}{Binding} element. - Rectangle { - id: rect - width: 100 - color: "yellow" - } +\section1 Types of Properties - Component.onCompleted: { - rect.height = (function() { return this.width * 2 }) - } -} -\endqml +Properties may bind to different types, but they are are \e type-safe. That is, +properties only allow you to assign a value that matches the property type. For +example, if a property is a real, and if you try to assign a string to it you +will get an error. -(In this case, the function could also have referred to \c rect.width rather than \c this.width.) +\badcode +property real volume: "four" //generates an error +\endcode -Note that the value of \c this is not defined outside of its use in property binding. -See \l {QML JavaScript Restrictions} for details. +Certain properties bind to more complex types such as other elements and objects. + +\keyword qml-basic-property-types +\section2 Basic Property Types +Basic types such as \l int, \l real, and other Qt structures may be bound to +properties. For a list of types, visit the \l {QML Basic Types} document. -\section2 Effects of property assignment +\keyword qml-id-property +\section2 The \c id Property + +Each QML object may be given a special unique property called an \c id. +No other object within the same QML component (see \l{QML Documents}) can have +the same \c id value. QML objects may then access an object using the \c id +property. +\snippet doc/src/snippets/declarative/properties.qml id property +A component may readily access its parent's properties by using the \c parent +property. -Note that assigning a value to a property that is currently bound will remove the binding. -A property can only have one value at a time, and if any code explicitly sets this value, the -binding is removed. In the following example, although \c width has been bound to \c height, -the binding is removed by the JavaScript code that assigns \c width to 50: +Note that an \c id must begin with a lower-case letter or an underscore. The +\c id cannot contain characters other than letters, numbers, underscores, and +\l {JavaScript Reserved Words}{JavaScript reserved words}. + +\section2 Elements and Objects as Property Values -\code -Item { - width: height * 2 - height: 100 +Many properties bind to objects. For example, the \l Item element has a +\c states property that can bind to \l State elements. This type of property +binding allows elements to carry additional non-children elements. \c Item's +\c transitions property behaves in a similar way; it can bind to \l Transition +elements. + +Care must be taken when referring to the parent of an object property binding. +Elements and components that are bound to properties are not necessarily set +as children of the properties' component. + +\snippet doc/src/snippets/declarative/properties.qml object binding +The code snippet has a \l Gradient element that attempts to print its parent's +\c width value. However, the \c Gradient element is bound to the \c gradient +property, not the \c children property of the \c Rectangle. As a result, the +\c Gradient does not have the \c Rectangle as its parent. Printing the value +of \c{parent.width} generates an error. Printing the \c Rectangle object's +first child's \c name will print \c {childrectangle} because the second +\c Rectangle is bound to the \c children property. + +For more information about the \c children property, please read the +\l {Default Properties} section. + +\keyword attached-properties +\section2 Attached Properties + +Certain objects provide additional properties by \e attaching properties to other +objects. For example, the \l Keys element have properties that can \e attach to other QML +objects to provide keyboard handling. + +\snippet doc/src/snippets/declarative/properties.qml list attached property +The element \l ListView provides the delegate, \c listdelegate, the property +\c isCurrentItem as an attached property. The \c ListView.isCurrentItem +\e{attached property} provides highlight information to the delegate. +Effectively, the \l ListView element attaches the \c ListView.isCurrentItem +property to each delegate it creates. + +\keyword attached-signalhandlers +\section2 Attached Signal Handlers + +\e {Attached signal handlers} are similar +to \l{Attached Properties}{attached properties} in that they attach to objects +to provide additional functionality to objects. Two prominent elements, +\l Component and \l Keys element provide +\l{QML Signal and Handler Event System}{signal handlers} as attached signal +handlers. +\snippet doc/src/snippets/declarative/properties.qml attached signal handler + +Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} +articles for more information. + +\section2 List properties + +Some properties may accept a binding to a list property, where more than one +component can bind to the property. List properties allow multiple +\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a +single property. +\snippet doc/src/snippets/declarative/properties.qml list property +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you may omit the square brackets. +\snippet doc/src/snippets/declarative/properties.qml single property + +To access the list, use the \c index property. +\snippet doc/src/snippets/declarative/properties.qml print list property +The snippet code simply prints the name of the first state, \c FETCH. + + See the \l{list}{list type} documentation +for more details about list properties and their available operations. + +\keyword qml-grouped-properties +\section2 Grouped Properties + +In some cases properties form a logical group and use either the \e dot notation +or \e group notation. + +Grouped properties may be written both ways: +\snippet doc/src/snippets/declarative/properties.qml grouped properties + +In the element documentation grouped properties are shown using the dot notation. + +\section2 Property Aliases + +Unlike a property definition, which allocates a new, unique storage space for +the property, a property alias connects the newly declared property, called the +\e{aliasing property} as a direct reference to an existing property, the +\e{aliased property}. Read or write operations on the aliasing property results +in a read or write operations on the aliased property, respectively. + +A property alias declaration is similar to an ordinary property definition: + +\tt{[default] property alias <name>: <alias reference>} + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special \c alias keyword is before the property name. +Instead of a default value, a property alias has a compulsory alias reference. +Accessing the aliasing property is similar to accessing a regular property. In +addition, the optional \c default keyword indicates that the aliasing property +is a \l{Default Properties}{default property}. + +\snippet doc/src/snippets/declarative/Button.qml property alias +When importing the component as a \c Button, the \c buttonlabel is directly +accessible through the \c label property. +\snippet doc/src/snippets/declarative/properties.qml alias usage +In addition, the \c id property may also be aliased and referred outside the +component. +\snippet doc/src/snippets/declarative/Button.qml parent begin +\snippet doc/src/snippets/declarative/Button.qml id alias +\snippet doc/src/snippets/declarative/Button.qml parent end +The \c imagebutton component has the ability to modify the child \l Image object + and its properties. +\snippet doc/src/snippets/declarative/properties.qml image alias + +Using aliases, properties may be exposed to the +\l{qml-top-level-component}{top level component}. Exposing properties to the +top-level component allows components to have interfaces similar to Qt widgets. + +\section3 Considerations for property aliases + +Aliases are only activated once the component +\l{Component::onCompleted}{completes} its initialization. An error is generated +when an uninitialized alias is referenced. Likewise, aliasing an aliasing +property will also result in an error. + +\snippet doc/src/snippets/declarative/properties.qml alias complete + +When importing the component, however, aliasing properties appear as regular Qt +properties and consequently can be used in alias references. + +It is possible for an aliasing property to have the same name as an existing +property, effectively overwriting the existing property. For example, +the following component has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet doc/src/snippets/declarative/properties.qml alias overwrite + +Any object that use this component and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. +Internally, however, the \c coloredrectangle can correctly set its \c color +property and refer to the actual defined property rather than the alias. + +The \l{declarative/ui-components/tabwidget}{TabWidget} example uses +aliases to reassign children to the \l ListView, creating a tab effect. + +\keyword default-properties +\section2 Default Properties - Component.onCompleted: { - width = 50; - } -} -\endcode +When imported, QML components will bind declared children to their designated +\e{default properties}. The optional \c default attribute specifies a property +as the \e {default property}. For example, the State element's default property +is its \l{State::changes}{changes} property. \l PropertyChanges elements +may simply be placed as the \c{State}'s children and they will be bound to the +\c changes property. +\snippet doc/src/snippets/declarative/properties.qml state default + +Similarly, the \l Item element's default property is its +\l{Item::data}{data} property. The \c data property manages Item's +\c children and \c resources properties. This way, different data types may be +placed as direct children of the \c Item. +\snippet doc/src/snippets/declarative/properties.qml default property +Reassigning a default property is useful when a component is reused. For +example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses +the \c default attribute to reassign children to the \l ListView, creating +a tab effect. -\section1 The Binding Element +\section1 Using the Binding Element -The implicit binding syntax shown previously is easy to use and works perfectly for most uses -of bindings. In some advanced cases, it is necessary to create bindings explicitly using the -\l Binding element. +In some advanced cases, it may be necessary to create bindings explicitly with +the\l Binding element. -For example, to bind a property exposed from C++ (\c system.brightness) to a value -coming from QML (\c slider.value), you could use the Binding element as follows: -\qml -Binding { - target: system - property: "brightness" - value: slider.value -} -\endqml +For example, to bind a property exposed from C++ (\c system.brightness) to a +value written in QML (\c slider.value), you could use the \l Binding element as +follows: +\snippet doc/src/snippets/declarative/properties.qml binding element +\section1 Changing Property Values in States +The \l PropertyChanges element is for setting property bindings within a +\l State element to set a property binding. + +\snippet doc/src/snippets/declarative/properties.qml PropertyChanges element +The rectangle's \c color property will bind to the \c warning component's +\c color property when its \c state is set to the \c WARNING state. */ - |