diff options
Diffstat (limited to 'doc/src/qml/propertybinding.qdoc')
-rw-r--r-- | doc/src/qml/propertybinding.qdoc | 362 |
1 files changed, 0 insertions, 362 deletions
diff --git a/doc/src/qml/propertybinding.qdoc b/doc/src/qml/propertybinding.qdoc deleted file mode 100644 index 6922f54003..0000000000 --- a/doc/src/qml/propertybinding.qdoc +++ /dev/null @@ -1,362 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-properties.html -\ingroup qml-features -\title Properties and Property Binding in QML -\brief declaring and binding properties - -\section1 Properties - -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 hold to -values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. - -The syntax for properties is: - -\tt{[default] property <type> <name>[: defaultValue]} - -Elements already possess useful properties but, to create custom properties, -precede the property name with the keyword \c property. - -\snippet doc/src/snippets/qml/properties.qml parent begin -\snippet doc/src/snippets/qml/properties.qml inherited properties -\snippet doc/src/snippets/qml/properties.qml custom properties -\snippet doc/src/snippets/qml/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 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. - -Property bindings are created in QML using the colon "\c {:}" before the value: -\snippet doc/src/snippets/qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -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/qml/properties.qml JavaScript sample - -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. - -\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/qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -Assigning a property value (using the equals sign "\c {=}") does not create a -property binding (unless explicitly assigned, see below). -\snippet doc/src/snippets/qml/properties.qml property assignment - -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. - -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. - -\section1 Binding to JavaScript Functions - -The \c{property : value} syntax for property binding is QML-specific and cannot -be used in JavaScript. Instead, to bind a property from JavaScript, assign the -result returned by the \c{Qt.binding()} function to the property. This will cause -a binding assignment on the specified property. The following code correctly creates -the binding in JavaScript rather than QML: - -\qml -Item { - width: 100 - - Component.onCompleted: { - height = Qt.binding(function() { return width * 2 }) - } -} -\endqml - -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. - -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 passed to Qt.binding() -needs to explicitly refer to \c this.width rather than just \c width. - -\qml -Item { - width: 500 - height: 500 - - Rectangle { - id: rect - width: 100 - color: "yellow" - } - - Component.onCompleted: { - rect.height = Qt.binding(function() { return this.width * 2 }) - console.log("rect.height = " + rect.height) // prints 200 - } -} -\endqml - -In this case, the function could also have referred to \c rect.width rather than -\c this.width. - -Note that the value of \c this is not defined outside of its use in property binding. -See \l {QML JavaScript Restrictions} for details. - -The \l{Binding} element provides more control for binding properties with -JavaScript code. - -\section1 Types of Properties - -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. - -\badcode -property real volume: "four" //generates an error -\endcode - -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 Elements and Objects as Property Values - -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/qml/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/qml/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/qml/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/qml/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/qml/properties.qml single property - -To access the list, use the \c index property. -\snippet doc/src/snippets/qml/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/qml/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/qml/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/qml/properties.qml alias usage -In addition, the \c id property may also be aliased and referred outside the -component. -\snippet doc/src/snippets/qml/Button.qml parent begin -\snippet doc/src/snippets/qml/Button.qml id alias -\snippet doc/src/snippets/qml/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/qml/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/qml/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/qml/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 - -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/qml/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/qml/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 Using the 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 the \l{The QML Engine}{declarative -runtime} or \l{QmlGlobalQtObject}{Qt object}, such as the \c system.brightness -property, to a value written in QML, you could use the \l Binding element as -follows: -\snippet doc/src/snippets/qml/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/qml/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. -*/ |