Rewrote QML Property Binding document. Added snippet code.

Task-number: QTBUG-16071

1 files changed, 248 insertions, 254 deletions

diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
index 6f7c40a..7328b4c 100644
--- a/doc/src/declarative/propertybinding.qdoc
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -29,296 +29,290 @@
 \page propertybinding.html
 \ingroup qml-features
 \contentspage QML Features
-\previouspage QML Syntax
-\nextpage {QML Basic Types}{Data Types}
+\previouspage {QML Basic Types}{Data Types}
+\nextpage {Using QML Positioner and Repeater Items}{Component Layouts}
 \title Property Binding
 
 \section1 Properties
 
-QML property rules coincide with many of JavaScript's property rules.
-Properties begin with a lowercase letter (with the exception of
-\l{Attached Properties}). \l {JavaScript Reserved Words}{JavaScript reserved words}
-are not valid property names.
+A property is a value of a QML component that can be read and modified by other objects.
+In QML, properties serve many purpose. Their main function is to bind to values.
+Values may be a \l{QML Basic Types}{basic type}, or other QML elements.
 
-\section1 Property types
+Elements already possess useful properties but, to create custom properties,
+precede the property name with the keyword \c property.
 
-QML supports properties of many types (see \l{QML Basic Types}). The basic types
-include int, real, bool, string, color, and lists.
+\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
 
-\code
-Item {
-    x: 10.5             // a 'real' property
-    ...
-    state: "details"    // a 'string' property
-    focus: true         // a 'bool' property
-}
-\endcode
-
-QML properties are \i type-safe. That is, properties only allow you to assign
-a value that matches the property type. For example, the \c x property of item is a real, and if you try to assign
-a string to it you will get an error.
-
-\badcode
-Item {
-    property real value: "hello"  // illegal!
-}
-\endcode
-
-\section1 The \c id Property
-
-Each object can 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. Assigning an id enables the object
-to be referred to by other objects and scripts.
-
-The first Rectangle element below has an \c id, "myRect". The second Rectangle element defines its
-own width by referring to \tt myRect.width, which means it will have the same \tt width
-value as the first Rectangle element.
-
-\code
-Item {
-    Rectangle {
-        id: myRect
-        width: 100
-        height: 100
-    }
-    Rectangle {
-        width: myRect.width
-        height: 200
-    }
-}
-\endcode
-
-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}.
-
-
-\section1 List properties
-
-List properties look like this:
-
-\code
-Item {
-    children: [
-        Image {},
-        Text {}
-    ]
-}
-\endcode
-
-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 can omit the square brackets:
+QML property rules coincide with many of JavaScript's property rules, for example,
+properti names must begin with a lowercase letter.
+\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property
+names.
 
-\code
-Image {
-    children: Rectangle {}
-}
-\endcode
-
-Items in the list can be accessed by the \c index. See the \l{list}{list type} documentation
-for more details about list properties and their available operations.
-
-
-\section1 Default Properties
-
-Each object type can specify one of its list or object properties as its default property.
-If a property has been declared as the default property, the property tag can be omitted.
-
-For example this code:
-\code
-State {
-    changes: [
-        PropertyChanges {},
-        PropertyChanges {}
-    ]
-}
-\endcode
-
-can be simplified to:
-
-\code
-State {
-    PropertyChanges {}
-    PropertyChanges {}
-}
-\endcode
-
-because \c changes is the default property of the \c State type.
-
-\section1 Grouped Properties
-\target dot properties
-
-In some cases properties form a logical group and use a 'dot' or grouped notation
-to show this.
-
-Grouped properties can be written like this:
-\qml
-Text {
-    font.pixelSize: 12
-    font.bold: true
-}
-\endqml
-
-or like this:
-\qml
-Text {
-    font { pixelSize: 12; bold: true }
-}
-\endqml
-
-In the element documentation grouped properties are shown using the 'dot' notation.
-
-\section1 Attached Properties
-\target attached-properties
-
-Some objects attach properties to another object.  Attached Properties
-are of the form \c {Type.property} where \c Type is the type of the
-element that attaches \c property.
-
-For example:
-\code
-Component {
-    id: myDelegate
-    Text {
-        text: "Hello"
-        color: ListView.isCurrentItem ? "red" : "blue"
-    }
-}
-ListView {
-    delegate: myDelegate
-}
-\endcode
-
-The \l ListView element attaches the \c ListView.isCurrentItem property
-to each delegate it creates.
-
-Another example of attached properties is the \l Keys element which
-attaches properties for handling key presses to
-any visual Item, for example:
-
-\code
-Item {
-    focus: true
-    Keys.onSelectPressed: console.log("Selected")
-}
-\endcode
 \section1 Property Binding
-Property binding is a declarative way of specifying the value of a property.  Binding allows
+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
+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 implicitly in QML whenever a property is assigned a JavaScript
-expression.  The following QML  code uses two property bindings to connect the size of the rectangle
-to that of \c otherItem.
-
-\code
-Rectangle {
-    width: otherItem.width
-    height: otherItem.height
-}
-\endcode
+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 like \c {Date} and \c {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
+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.
 
-\section1 Changing Bindings
+\section1 Property Assignment versus Property Binding
 
-The \l PropertyChanges element can be used within a state change to modify the bindings on
-properties.
+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.
 
-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.
+Assigning a property value (using the equals sign "\c {=}") does not create a
+property binding.
+\snippet doc/src/snippets/declarative/properties.qml property assignment
 
-\code
-Rectangle {
-    id: rectangle
-    width: otherItem.width
-    height: otherItem.height
-
-    states: State {
-        name: "square"
-        PropertyChanges {
-            target: rectangle
-            width: otherItem.height
-        }
-    }
-}
-\endcode
+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 Effects of Property Assignment in JavaScript
+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.
 
-Assigning a property value from JavaScript does \e not create a property binding.
-For example:
+\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.
+\qml
+    property real volume: "four"  //generates an error
+\endqml
 
-\code
-Rectangle {
+Certain properties bind to more complex types such as other elements and objects.
+
+\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
 
-    Component.onCompleted: {
-        width = otherItem.width;
-    }
-}
-\endcode
+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.
 
-Instead of creating a property binding, this simply sets the \c width of the \l Rectangle
-to the value of \c other.width at the time the JavaScript code is invoked.  See
-\l {Property Assignment vs Property Binding} for more details.
+ See the \l{list}{list type} documentation
+for more details about list properties and their available operations.
 
-Also note that assigning a value to a property that is currently bound will remove the previous binding.
-A property can only have one value at a time, and if any code explicitly sets
-this value, the binding is removed.  The \l Rectangle in the example below will have
-a width of 13, regardless of the \c otherItem's width.
+\section2 Grouped Properties
+\target dot properties
 
-\code
-Rectangle {
-    width: otherItem.width
+In some cases properties form a logical group and use either the \e dot notation
+or \e group notation.
 
-    Component.onCompleted: {
-        width = 13;
-    }
-}
-\endcode
+Grouped properties may be written both ways:
+\snippet doc/src/snippets/declarative/properties.qml grouped properties
 
-There is no way to create a property binding directly from imperative JavaScript code,
-although it is possible to set up a \l Binding object (shown below).
+In the element documentation grouped properties are shown using the dot notation.
 
+\section2 Property Aliases
 
-\section1 Binding Element
+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.
 
-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.
+A property alias declaration is similar to an ordinary property definition:
+\code
+    [default] property alias <name>: <alias reference>
+\endcode
+
+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.
 
-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
 */