diff options
author | Jerome Pasion <jerome.pasion@nokia.com> | 2012-02-09 17:31:02 +0100 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-02-14 12:53:21 +0100 |
commit | 2d4e6ff9dd1e0e3410c4dc002c25d80fecfeafd2 (patch) | |
tree | b12aec803acf837024b4426526f1ce69cb3080ae /doc/src/qml/propertybinding.qdoc | |
parent | d95178153a0f15991b2e6e91216dbcf5c0be2af3 (diff) |
Doc: Overhaul of doc/src/declarative and QtQuick2 docs.
-Consolidated model/view documentation into one.
-Added a new navigation for all overviews (grouped the pages)
-New front page that shows the grouping
-Separated the Qt C++ from the main QML overviews
-Consolidated Qt C++ into the "declarative runtime" section
-New articles about JavaScript, the engine, and plugins
-Fixed the older examples. New snippet comments
-Renamed some of the articles
-kept the qtquick2 qmlmodule
-"Qt Quick Elements"
Moved contents of doc/src/declarative into respective
module dirs.
-Qt Quick 2, LocalStorage, Particles, and QML are now
separate.
-Removed unused or duplicate documentation.
-edited C++ examples
-removed navigation and "\inqmlmodule QtQuick 2" for
those pages that are not in Qt Quick 2
-fixed doc/src/ licenses to header.FDL from qtbase
Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a
Reviewed-by: Sergio Ahumada <sergio.ahumada@nokia.com>
Diffstat (limited to 'doc/src/qml/propertybinding.qdoc')
-rw-r--r-- | doc/src/qml/propertybinding.qdoc | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/doc/src/qml/propertybinding.qdoc b/doc/src/qml/propertybinding.qdoc new file mode 100644 index 0000000000..b89b3d7a61 --- /dev/null +++ b/doc/src/qml/propertybinding.qdoc @@ -0,0 +1,363 @@ +/**************************************************************************** +** +** 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 \i 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/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 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/declarative/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/declarative/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/declarative/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. +\snippet doc/src/snippets/declarative/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 a \c +function to the property that returns the required value. The following code +correctly creates +the binding in JavaScript rather than QML: + +\qml +Item { + width: 100 + + Component.onCompleted: { + height = (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 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. + +\qml +Item { + width: 500 + height: 500 + + Rectangle { + id: rect + width: 100 + color: "yellow" + } + + Component.onCompleted: { + rect.height = (function() { return this.width * 2 }) + } +} +\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 \i 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/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 \i attaching properties to other +objects. For example, the \l Keys element have properties that can \i 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 +\i{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 + +\i {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 \i dot notation +or \i 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 +\i{aliasing property} as a direct reference to an existing property, the +\i{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 + +When imported, QML components will bind declared children to their designated +\i{default properties}. The optional \c default attribute specifies a property +as the \i {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 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/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. +*/ |