path: root/doc/src/declarative/propertybinding.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\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

\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 bind 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.

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.

\section1 Types of Properties

Properties may bind to different types, but they 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.

\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 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

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

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 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 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.
*/