--- /dev/null
+project = QtQuick
+description = Qt Quick Reference Documentation
+url = http://qt-project.org/doc/qt-5.0/qtquick
+version = 5.0.0
+
+depends += qtqcore qtxmlpatterns qtjsbackend qtqml
+
+sourceencoding = UTF-8
+outputencoding = UTF-8
+naturallanguage = en_US
+qhp.projects = QtCore
+
+qhp.QtQuick.file = qtquick.qhp
+qhp.QtQuick.namespace = org.qt-project.qtquick.500
+qhp.QtQuick.virtualFolder = qdoc
+qhp.QtQuick.indexTitle = Qt Quick Reference Documentation
+qhp.QtQuick.indexRoot =
+
+qhp.QtQuick.filterAttributes = qtquick 5.0.0 qtrefdoc
+qhp.QtQuick.customFilters.Qt.name = QtQuick 5.0.0
+qhp.QtQuick.customFilters.Qt.filterAttributes = qtquick 5.0.0
+qhp.QtQuick.subprojects = classes overviews examples
+qhp.QtQuick.subprojects.classes.title = Classes
+qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick's Classes
+qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
+qhp.QtQuick.subprojects.classes.sortPages = true
+qhp.QtQuick.subprojects.overviews.title = Overviews
+qhp.QtQuick.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+qhp.QtQuick.subprojects.overviews.selectors = fake:page,group,module
+qhp.QtQuick.subprojects.examples.title = Qt Quick Examples
+qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples
+qhp.QtQuick.subprojects.examples.selectors = fake:example
+
+dita.metadata.default.author = Qt Project
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher = Qt Project
+dita.metadata.default.copyryear = 2012
+dita.metadata.default.copyrholder = Nokia
+dita.metadata.default.audience = programmer
+
+sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
+headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css"
+examples.imageextensions = "*.png"
+
+outputdir = ../../../doc/qtquick
+tagfile = ../../../doc/qtquick/qtcore.tags
+
+HTML.generatemacrefs = "true"
+HTML.nobreadcrumbs = "true"
+
+HTML.templatedir = .
+
+HTML.stylesheets = ../../../doc/global/style/offline.css
+
+HTML.headerstyles = \
+ " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+ "</head>\n" \
+
+defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT_KEYPAD_NAVIGATION \
+ QT_NO_EGL \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ QT_DEPRECATED \
+ QT_DEPRECATED_* \
+ Q_NO_USING_KEYWORD \
+ __cplusplus \
+ Q_COMPILER_INITIALIZER_LISTS
+
+versionsym = QT_VERSION_STR
+
+codeindent = 1
+
+headerdirs += ..
+
+sourcedirs += ..
+
+exampledirs += ../../../examples \
+ ../ \
+ snippets
+
+imagedirs += images
**
****************************************************************************/
-//! [dragfilter]
import QtQuick 2.0
-Rectangle {
- width: 480
- height: 320
- Rectangle {
- x: 30; y: 30
- width: 300; height: 240
+//! [0]
+ListView {
+ width: 240; height: 320
+ model: ListModel {}
+
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
+ }
+ }
- MouseArea {
- anchors.fill: parent
- drag.target: parent;
- drag.axis: "XAxis"
- drag.minimumX: 30
- drag.maximumX: 150
- drag.filterChildren: true
+ add: Transition {
+ NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
+ NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
+ }
- Rectangle {
- color: "yellow"
- x: 50; y : 50
- width: 100; height: 100
- MouseArea {
- anchors.fill: parent
- onClicked: console.log("Clicked")
- }
- }
- }
+ displaced: Transition {
+ NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
}
+
+ focus: true
+ Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
}
-//! [dragfilter]
+//! [0]
**
****************************************************************************/
-//! [0]
import QtQuick 2.0
-Rectangle {
- width: 240; height: 200
+ListView {
+ width: 240; height: 320
+ model: ListModel {}
-//! [1]
- Component {
- id: delegate
- Column {
- id: wrapper
- Image {
- anchors.horizontalCenter: nameText.horizontalCenter
- width: 64; height: 64
- source: icon
- }
- Text {
- id: nameText
- text: name
- font.pointSize: 16
- color: wrapper.PathView.isCurrentItem ? "red" : "black"
- }
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
+ color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
}
}
-//! [1]
-//! [2]
- PathView {
- anchors.fill: parent
- model: ContactModel {}
- delegate: delegate
- path: Path {
- startX: 120; startY: 100
- PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
- PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
+ add: Transition {
+ NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
+ NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
+ }
+
+//! [0]
+ displaced: Transition {
+ id: dispTrans
+ SequentialAnimation {
+ PauseAnimation {
+ duration: (dispTrans.ViewTransition.index -
+ dispTrans.ViewTransition.targetIndexes[0]) * 100
+ }
+ NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
}
}
-//! [2]
-}
//! [0]
+
+ focus: true
+ Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
+}
+
** $QT_END_LICENSE$
**
****************************************************************************/
-import QtQuick 2.0
-Row {
+import QtQuick 2.0
- //![transition]
- Item {
- width: 400; height: 400
+ListView {
+ width: 240; height: 320
+ model: ListModel {}
- Rectangle {
- id: rect
- width: 200; height: 100
- color: "red"
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
+ color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
+ }
+ }
- states: State {
- name: "rotated"
- PropertyChanges { target: rect; rotation: 180; transformOrigin: Item.BottomRight }
- }
+ add: Transition {
+ NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
+ NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
+ }
- transitions: Transition {
- RotationAnimation { duration: 1000; direction: RotationAnimation.Counterclockwise }
+//! [0]
+ displaced: Transition {
+ id: dispTrans
+ SequentialAnimation {
+ PauseAnimation {
+ duration: (dispTrans.ViewTransition.index -
+ dispTrans.ViewTransition.targetIndexes[0]) * 100
}
-
- MouseArea {
- anchors.fill: parent
- onClicked: rect.state = "rotated"
+ ParallelAnimation {
+ NumberAnimation {
+ property: "x"; to: dispTrans.ViewTransition.item.x + 20
+ easing.type: Easing.OutQuad
+ }
+ NumberAnimation {
+ property: "y"; to: dispTrans.ViewTransition.item.y + 50
+ easing.type: Easing.OutQuad
+ }
}
+ NumberAnimation { properties: "x,y"; duration: 500; easing.type: Easing.OutBounce }
}
}
- //![transition]
-
- Item {
- width: 300; height: 300
- Image { id: img; source: "pics/qt.png" }
+//! [0]
- //![standalone]
- SequentialAnimation {
- PropertyAction { target: img; property: "smooth"; value: "true" }
- NumberAnimation { target: img; property: "width"; to: 300; duration: 1000 }
- PropertyAction { target: img; property: "smooth"; value: "false" }
- }
- //![standalone]
- }
+ focus: true
+ Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
}
+
+
**
****************************************************************************/
-//! [dragfilter]
import QtQuick 2.0
-Rectangle {
- width: 480
- height: 320
- Rectangle {
- x: 30; y: 30
- width: 300; height: 240
+ListView {
+ width: 240; height: 320
+ model: ListModel {}
+
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
+ }
+ }
- MouseArea {
- anchors.fill: parent
- drag.target: parent;
- drag.axis: "XAxis"
- drag.minimumX: 30
- drag.maximumX: 150
- drag.filterChildren: true
+ add: Transition {
+ NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
+ NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
+ }
- Rectangle {
- color: "yellow"
- x: 50; y : 50
- width: 100; height: 100
- MouseArea {
- anchors.fill: parent
- onClicked: console.log("Clicked")
- }
- }
- }
+//! [0]
+ displaced: Transition {
+ NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
+
+ // ensure opacity and scale values return to 1.0
+ NumberAnimation { property: "opacity"; to: 1.0 }
+ NumberAnimation { property: "scale"; to: 1.0 }
}
+//! [0]
+
+ focus: true
+ Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
}
-//! [dragfilter]
**
****************************************************************************/
-//! [import]
import QtQuick 2.0
-//! [import]
-Rectangle {
- width: childrenRect.width
- height: childrenRect.height
+ListView {
+ width: 240; height: 320
+ model: ListModel {}
- Row {
- //! [intro]
- Rectangle {
- width: 100; height: 100
- color: "green"
-
- MouseArea {
- anchors.fill: parent
- onClicked: { parent.color = 'red' }
- }
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
+ color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
}
- //! [intro]
+ }
- //! [intro-extended]
- Rectangle {
- width: 100; height: 100
- color: "green"
+//! [0]
+ add: Transition {
+ id: addTrans
+ NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
+ NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
- MouseArea {
- anchors.fill: parent
- acceptedButtons: Qt.LeftButton | Qt.RightButton
- onClicked: {
- if (mouse.button == Qt.RightButton)
- parent.color = 'blue';
- else
- parent.color = 'red';
+ PathAnimation {
+ duration: 1000
+ path: Path {
+ startX: addTrans.ViewTransition.destination.x + 200
+ startY: addTrans.ViewTransition.destination.y + 200
+ PathCurve { relativeX: -100; relativeY: -50 }
+ PathCurve { relativeX: 50; relativeY: -150 }
+ PathCurve {
+ x: addTrans.ViewTransition.destination.x
+ y: addTrans.ViewTransition.destination.y
}
}
}
- //! [intro-extended]
-
- //! [drag]
- Rectangle {
- id: container
- width: 600; height: 200
-
- Rectangle {
- id: rect
- width: 50; height: 50
- color: "red"
- opacity: (600.0 - rect.x) / 600
+ }
+//! [0]
- MouseArea {
- anchors.fill: parent
- drag.target: rect
- drag.axis: Drag.XAxis
- drag.minimumX: 0
- drag.maximumX: container.width - rect.width
+ displaced: Transition {
+ id: dispTrans
+ SequentialAnimation {
+ PauseAnimation {
+ duration: (dispTrans.ViewTransition.index -
+ dispTrans.ViewTransition.targetIndexes[0]) * 100
+ }
+ ParallelAnimation {
+ NumberAnimation {
+ property: "x"; to: dispTrans.ViewTransition.item.x + 20
+ easing.type: Easing.OutQuad
+ }
+ NumberAnimation {
+ property: "y"; to: dispTrans.ViewTransition.item.y + 50
+ easing.type: Easing.OutQuad
}
}
+ NumberAnimation { properties: "x,y"; duration: 500; easing.type: Easing.OutBounce }
}
- //! [drag]
+ }
+
+ focus: true
+ Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
+}
- //! [mousebuttons]
- Text {
- text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
- horizontalAlignment: Text.AlignHCenter
- verticalAlignment: Text.AlignVCenter
- MouseArea {
- id: mouseArea
- anchors.fill: parent
- acceptedButtons: Qt.LeftButton | Qt.RightButton
- }
- }
- //! [mousebuttons]
- }
-}
** $QT_END_LICENSE$
**
****************************************************************************/
-import QtQuick 2.0
-//![0]
-Rectangle {
- id: rect
- width: 100; height: 100
- color: "red"
+import QtQuick 2.0
- MouseArea { id: mouseArea; anchors.fill: parent }
+//! [0]
+ListView {
+ width: 240; height: 320
+ model: ListModel {
+ Component.onCompleted: {
+ for (var i=0; i<8; i++)
+ append({"name": i})
+ }
+ }
- states: State {
- name: "brighter"
- when: mouseArea.pressed
- PropertyChanges { target: rect; color: "yellow"; x: 50 }
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
+ color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
+ }
+ objectName: name
}
- //! [sequential animations]
- transitions: Transition {
+ move: Transition {
+ id: moveTrans
SequentialAnimation {
- PropertyAnimation { property: "x"; duration: 1000 }
- ColorAnimation { duration: 1000 }
+ ColorAnimation { property: "color"; to: "yellow"; duration: 400 }
+ NumberAnimation { properties: "x,y"; duration: 800; easing.type: Easing.OutBack }
+ ScriptAction { script: moveTrans.ViewTransition.item.color = "lightsteelblue" }
}
}
- //! [sequential animations]
+
+ displaced: Transition {
+ NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
+ }
+
+ focus: true
+ Keys.onSpacePressed: model.move(5, 1, 3)
}
-//![0]
+//! [0]
** $QT_END_LICENSE$
**
****************************************************************************/
-import QtQuick 2.0
-//![0]
-Rectangle {
- id: rect
- width: 100; height: 100
- color: "red"
+import QtQuick 2.0
- MouseArea { id: mouseArea; anchors.fill: parent }
+ListView {
+ width: 240; height: 320
+ model: ListModel {
+ Component.onCompleted: {
+ for (var i=0; i<8; i++)
+ append({"name": i})
+ }
+ }
- states: State {
- name: "brighter"
- when: mouseArea.pressed
- PropertyChanges { target: rect; color: "yellow"; x: 50 }
+ delegate: Rectangle {
+ width: 100; height: 30
+ border.width: 1
+ color: "lightsteelblue"
+ Text {
+ anchors.centerIn: parent
+ text: name
+ }
+ objectName: name
}
- //! [sequential animations]
- transitions: Transition {
+//! [0]
+ move: Transition {
+ id: moveTrans
SequentialAnimation {
- PropertyAnimation { property: "x"; duration: 1000 }
- ColorAnimation { duration: 1000 }
+ ColorAnimation { property: "color"; to: "yellow"; duration: 400 }
+ NumberAnimation { properties: "x,y"; duration: 800; easing.type: Easing.OutBack }
+ //ScriptAction { script: moveTrans.ViewTransition.item.color = "lightsteelblue" } BAD!
+
+ PropertyAction { property: "color"; value: "lightsteelblue" }
}
}
- //! [sequential animations]
+//! [0]
+
+ displaced: Transition {
+ NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
+ }
+
+ focus: true
+ Keys.onSpacePressed: model.move(5, 1, 3)
}
-//![0]
+
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-anchorlayout.html
+\contentspage QML Features
+\title Layouts with Anchors
+\brief placing items with anchor properties
+
+\target anchor-layout
+In addition to the more traditional \l Grid, \l Row, and \l Column,
+QML also provides a way to layout items using the concept of \e anchors.
+Each item can be thought of as having a set of 7 invisible "anchor lines":
+\l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter},
+\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top},
+\l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline},
+and \l {Item::anchors.bottom}{bottom}.
+
+\image edges_qml.png
+
+The baseline (not pictured above) corresponds to the imaginary line on which
+text would sit. For items with no text it is the same as \e top.
+
+The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write:
+
+\code
+Rectangle { id: rect1; ... }
+Rectangle { id: rect2; anchors.left: rect1.right; ... }
+\endcode
+
+In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following:
+
+\image edge1.png
+
+
+You can specify multiple anchors. For example:
+
+\code
+Rectangle { id: rect1; ... }
+Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... }
+\endcode
+
+\image edge3.png
+
+By specifying multiple horizontal or vertical anchors you can control the size of an item. Below,
+\e rect2 is anchored to the right of \e rect1 and the left of \e rect3. If either of the blue
+rectangles are moved, \e rect2 will stretch and shrink as necessary:
+
+\code
+Rectangle { id: rect1; x: 0; ... }
+Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: rect3.left; ... }
+Rectangle { id: rect3; x: 150; ... }
+\endcode
+
+\image edge4.png
+
+There are also some convenience anchors. anchors.fill is a convenience that is the same as setting the left,right,top and bottom anchors
+to the left,right,top and bottom of the target item. anchors.centerIn is another convenience anchor, and is the same as setting the verticalCenter
+and horizontalCenter anchors to the verticalCenter and horizontalCenter of the target item.
+
+\section1 Anchor Margins and Offsets
+
+The anchoring system also allows \e margins and \e offsets to be specified for an item's anchors.
+Margins specify the amount of empty space to leave to the outside of an item's anchor, while
+offsets allow positioning to be manipulated using the center anchor lines. An item can
+specify its anchor margins individually through \l {Item::anchors.leftMargin}{leftMargin},
+\l {Item::anchors.rightMargin}{rightMargin}, \l {Item::anchors.topMargin}{topMargin} and
+\l {Item::anchors.bottomMargin}{bottomMargin}, or use \l {Item::}{anchors.margins} to
+specify the same margin value for all four edges. Anchor offsets are specified using
+\l {Item::anchors.horizontalCenterOffset}{horizontalCenterOffset},
+\l {Item::anchors.verticalCenterOffset}{verticalCenterOffset} and
+\l {Item::anchors.baselineOffset}{baselineOffset}.
+
+\image margins_qml.png
+
+The following example specifies a left margin:
+
+\code
+Rectangle { id: rect1; ... }
+Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }
+\endcode
+
+In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following:
+
+\image edge2.png
+
+\note Anchor margins only apply to anchors; they are \e not a generic means of applying margins to an \l Item.
+If an anchor margin is specified for an edge but the item is not anchored to any item on that
+edge, the margin is not applied.
+
+
+\section1 Restrictions
+
+For performance reasons, you can only anchor an item to its siblings and direct parent. For example,
+the following anchor is invalid and would produce a warning:
+
+\badcode
+Item {
+ id: group1
+ Rectangle { id: rect1; ... }
+}
+Item {
+ id: group2
+ Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor!
+}
+\endcode
+
+Also, anchor-based layouts cannot be mixed with absolute positioning. If an item specifies its
+\l {Item::}{x} position and also sets \l {Item::}{anchors.left},
+or anchors its left and right edges but additionally sets a \l {Item::}{width}, the
+result is undefined, as it would not be clear whether the item should use anchoring or absolute
+positioning. The same can be said for setting an item's \l {Item::}{y} and \l {Item::}{height}
+with \l {Item::}{anchors.top} and \l {Item::}{anchors.bottom}, or setting \l {Item::}{anchors.fill}
+as well as \l {Item::}{width} or \l {Item::}{height}. The same applies when using positioners
+such as Row and Grid, which may set the item's \l {Item::}{x} and \l {Item::}{y} properties.
+If you wish to change from using
+anchor-based to absolute positioning, you can clear an anchor value by setting it to \c undefined.
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-animation.html
+\title Animation and Transitions
+\brief the animation system in Qt Quick
+
+\section1 Animation and Transitions Elements
+\list
+\li \l {Transition} - Animates transitions during state changes
+\li \l {SequentialAnimation} - Runs animations sequentially
+\li \l {ParallelAnimation} - Runs animations in parallel
+\li \l {Behavior} - Specifies a default animation for property changes
+\li \l {PropertyAction} - Sets immediate property changes during animation
+\li \l {PauseAnimation} - Introduces a pause in an animation
+\li \l {SmoothedAnimation} - Allows a property to smoothly track a value
+\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
+\li \l {ScriptAction} - Runs scripts during an animation
+\endlist
+
+Elements that animate properties based on data types
+\list
+\li \l {PropertyAnimation} - Animates property changes
+\li \l {NumberAnimation} - Animates properties of type qreal
+\li \l {Vector3dAnimation} - Animates properties of type QVector3d
+\li \l {ColorAnimation} - Animates color changes
+\li \l {RotationAnimation} - Animates rotations
+\li \l {ParentAnimation} - Animates parent changes
+\li \l {AnchorAnimation} - Animates anchor changes
+\endlist
+
+Animations are created by applying animation elements to property
+values. Animation elements will interpolate property values to create smooth
+transitions. As well, state transitions may assign animations to state changes.
+
+To create an animation, use an appropriate animation element for the type of
+the property that is to be animated, and apply the animation depending on the
+type of behavior that is required.
+
+\section1 Triggering Animations
+
+There are several ways of setting animation to an object.
+
+\section2 Direct Property Animation
+
+To create an immediate movement or animated movement, set the property value
+directly. This may be done in signal handlers or attached properties.
+
+\snippet doc/snippets/qml/animation.qml direct property change
+
+However, to create more control, \e {property animations} apply smooth movements
+by interpolating values between property value changes. Property animations
+provide timing controls and allows different interpolations through
+\l{qml-easing-animation}{easing curves}.
+
+\snippet doc/snippets/qml/animation.qml property animation
+
+Specialized \l{qml-property-animation-elements}{property animation elements}
+have more efficient implementations than the \l{PropertyAnimation} element. They
+are for setting animations to different QML types such as \c int, \c color, and
+rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
+
+See the \l {qml-controlling-animations}{Controlling Animations} section for more
+information about the different animation properties.
+
+\keyword qml-transition-animations
+\section2 Transitions during State Changes
+
+\l{States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
+abrupt property changes; animations smooth transitions to produce visually
+appealing state changes.
+
+The \l{Transition} element can contain
+\l{qml-animation-elements}{animation elements} to interpolate property changes
+caused by state changes. To assign the transition to an object, bind it to the
+\c transitions property.
+
+A button might have two states, the \c pressed state when the user clicks on the
+button and a \c released state when the user releases the button. We can assign
+different property configurations for each state. A transition would animate the
+change from the \c pressed state to the \c released state. Likewise, there would
+be an animation during the change from the \c released state to the \c pressed
+state.
+
+\snippet doc/snippets/qml/animation.qml transition animation
+
+Binding the \c to and \c from properties to the state's name will assign that
+particular transition to the state change. For simple or symmetric transitions,
+setting the to \c to property to the wild card symbol, "\c{*}", denotes
+that the transition applies to any state change.
+
+\snippet doc/snippets/qml/animation.qml wildcard animation
+
+\section2 Default Animation as Behaviors
+
+Default property animations are set using \e {behavior animations}. Animations
+declared in \l {Behavior} elements apply to the property and animates any
+property value changes. However, Behavior elements have an
+\c enabled property to purposely enable or disable the behavior animations.
+
+A ball component might have a behavior animation assigned to its \c x, \c y, and
+\c color properties. The behavior animation could be set up to simulate an
+elastic effect. In effect, this behavior animation would apply the elastic
+effect to the properties whenever the ball moves.
+
+\snippet doc/snippets/qml/animation.qml behavior animation
+
+There are several methods of assigning behavior animations to properties. The
+\c{Behavior on <property>} declaration is a convenient way of assigning a
+behavior animation onto a property.
+
+See the \l {declarative/animation/behaviors}{Behaviors example} for a
+demonstration of behavioral animations.
+
+\section1 Playing Animations in Parallel or in Sequence
+
+Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
+will play a group of animations at the same time while sequential animations
+play a group of animations in order: one after the other. Grouping animations in
+\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
+sequence or in parallel.
+
+A banner component may have several icons or slogans to display, one after the
+other. The \c opacity property could transform to \c 1.0 denoting an opaque
+object. Using the \l{SequentialAnimation} element, the opacity animations will
+play after the preceding animation finishes. The \l{ParallelAnimation} element
+will play the animations at the same time.
+
+\snippet doc/snippets/qml/animation.qml sequential animation
+
+Once individual animations are placed into a SequentialAnimation or
+ParallelAnimation, they can no longer be started and stopped independently. The
+sequential or parallel animation must be started and stopped as a group.
+
+The \l SequentialAnimation element is also useful for playing
+\l{qml-transition-animations}{transition animations} because animations are
+played in parallel inside transitions.
+
+See the \l {declarative/animation/basics}{Animation basics example} for a
+demonstration of creating and combining multiple animations in QML.
+
+\keyword qml-controlling-animations
+\section1 Controlling Animations
+
+There are different methods to control animations.
+
+\section2 Animation Playback
+All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not
+possible to create \l Animation objects; instead, this element provides the
+essential properties and methods for animation elements. Animation elements have
+\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
+\c{complete()} -- all of these methods control the execution of animations.
+
+\keyword qml-easing-animation
+\section2 Easing
+
+Easing curves define how the animation will interpolate between the start value
+and the end value. Different easing curves might go beyond the defined range of
+interpolation. The easing curves simplify the creation of animation effects such
+as bounce effects, acceleration, deceleration, and cyclical animations.
+
+A QML object may have different easing curve for each property animation. There
+are also different parameters to control the curve, some of which are exclusive
+to a particular curve. For more information about the easing curves, visit the
+\l {PropertyAnimation::easing.type}{easing} documentation.
+
+The \l{declarative/animation/easing}{easing example} visually demonstrates each
+of the different easing types.
+
+\section2 Other Animation Elements
+
+In addition, QML provides several other elements useful for animation:
+
+\list
+\li PauseAnimation: enables pauses during animations
+\li ScriptAction: allows JavaScript to be executed during an animation, and can
+be used together with StateChangeScript to reused existing scripts
+\li PropertyAction: changes a property \e immediately during an animation,
+without animating the property change
+\endlist
+
+These are specialized animation elements that animate different property types
+\list
+\li SmoothedAnimation: a specialized NumberAnimation that provides smooth
+changes in animation when the target value changes
+\li SpringAnimation: provides a spring-like animation with specialized
+attributes such as \l {SpringAnimation::}{mass},
+\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
+\li ParentAnimation: used for animating a parent change (see ParentChange)
+\li AnchorAnimation: used for animating an anchor change (see AnchorChanges)
+\endlist
+
+\section1 Sharing Animation Instances
+
+Sharing animation instances between Transitions or Behaviors is not
+supported, and may lead to undefined behavior. In the following example,
+changes to the Rectangle's position will most likely not be correctly animated.
+
+\qml
+Rectangle {
+ // NOT SUPPORTED: this will not work correctly as both Behaviors
+ // try to control a single animation instance
+ NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
+ Behavior on x { animation: anim }
+ Behavior on y { animation: anim }
+}
+\endqml
+
+The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated
+animation is rather complex, you might also consider creating a custom animation
+component and assigning an instance to each Behavior, for example:
+
+\qml
+// MyNumberAnimation.qml
+NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
+\endqml
+
+\qml
+// main.qml
+Rectangle {
+ Behavior on x { MyNumberAnimation {} }
+ Behavior on y { MyNumberAnimation {} }
+}
+\endqml
+
+*/
+
+
+
+\snippet doc/snippets/qml/animation-elements.qml color
+\snippet doc/snippets/qml/animation-propertyvaluesource.qml 0
+\snippet doc/snippets/qml/animation-signalhandler.qml 0
+\snippet doc/snippets/qml/animation-standalone.qml 0
+
+\snippet doc/snippets/qml/animation-transitions.qml 0
+\snippet doc/snippets/qml/animation-groups.qml 0
+
+\snippet doc/snippets/qml/animation-groups.qml 1
+\snippet doc/snippets/qml/animation-groups.qml 0
+\image propanim.gif
+
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-basicelements.html
+\ingroup qml-features
+\title Basic Elements
+\brief introduction to the Qt Quick Elements
+
+Qt Quick includes \e elements for placing components. These can be combined
+to form other components.
+
+\code
+import QtQuick 2.0
+\endcode
+\section1 Basic Elements
+This is a list of some of the elements readily available for users.
+\list
+\li \l {Item}
+\li \l {Rectangle}
+\li \l {Image}
+\li \l {Text}
+\li \l {TextInput}
+\li \l {TextEdit}
+\li \l {FocusScope}
+\li \l {Component}
+\li \l {MouseArea}
+\endlist
+
+For a complete list of QML elements, please visit the \l {QML Elements} page.
+
+\section1 Item Element
+
+Many QML elements inherit \l Item properties. \c Item possesses important properties
+such as \c focus, \c children, and dimension properties such as \c width and
+\c height. Although \c Item has physical properties, it is not a visual element.
+Using \c Item as the top-level QML element (as the screen) will not produce a
+visual result, use the \l {Rectangle} element instead. Use the \c Item to create
+opacity effects, such as when creating an invisible container to hold other
+components.
+
+\section1 Rectangle Element
+
+The \l Rectangle element is the basic visual element, for displaying different
+types of items onto the screen. The \c Rectangle is customizable and utilizes
+other elements such as \l Gradient and \l BorderImage for displaying advanced
+customized graphics.
+
+\section1 Image Element
+
+To insert an image into a QML scene, merely declare an \l Image element. The
+\c Image element can load images in formats supported by Qt.
+
+\section1 Text Elements
+
+The \l Text and \l TextEdit elements display formatted text onto the screen.
+\c TextEdit features multi-line editing while the \l TextInput element is for
+single line text input.
+
+\keyword qml-top-level-component
+\section1 Using Elements as the Top-Level Component
+
+For creating components, there are different
+elements that could be used as the top-level component. To display a simple scene,
+a \l Rectangle as the top-level component may suffice. \l Rectangle,
+\l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of
+the commonly used elements as the top-level component.
+
+When importing components, the top-level component is important because the
+top-level component's properties are the only properties exposed to the parent.
+
+For example, a \c Button component may be implemented using different elements as
+its top-level component. When this component is loaded into another QML scene,
+the component will retain the top-level component's properties. If a non-visual
+component is the top-level component, the visual properties should be aliased to
+the top-level to display the component properly.
+
+For more information on how to build upon QML elements, see the
+\l{QML Components} document.
+
+\section1 Additional Elements
+
+The \l{Local Storage}{SQL Local Storage API} provides a JavaScript interface to an SQL relational
+database. The import statement needs a namespace
+
+\code
+import QtQuick.LocalStorage 2.0 as SQL
+\endcode
+
+The \l{QML Module QtQuick.Particles 2}{QtQuick.Particles} module provides a
+particle system for additional graphics. The
+\l{qml-particlesystem.html}{Using the Qt Quick Particle System} article outlines
+the system features.
+\code
+import QtQuick.Particles 2.0
+\endcode
+
+\section1 Extending and Importing Elements
+
+Components may use the basic elements to create new components or to add
+functionality to existing components. In addition, external component sets
+may exist to perform logic or provide plugins.
+
+To extend existing elements or to create a custom component, the articles
+\l{Creating QML Types} and \l{The QML Engine} contain information about
+registering new types into the QML engine.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-behaviors-states.html tutorial
+\title Using QML Behaviors with States
+\brief animating property changes with behaviors
+
+\section1 Using Behaviors with States
+
+In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior.
+
+Here's an example that shows the problem:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: "red"
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ }
+ }
+}
+\endqml
+
+Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The
+problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted.
+
+To state the problem more formally, using States and Behaviors together can cause unexpected behavior when:
+\list
+\li a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and
+\li this Behavior can be interrupted to (re-)enter an explicitly defined state.
+\endlist
+
+The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back
+to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form.
+
+While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem.
+
+1. Use a transition to animate the change, rather than a Behavior.
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: "red"
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ }
+
+ transitions: Transition {
+ ColorAnimation {}
+ }
+ }
+}
+\endqml
+
+2. Use a conditional binding to change the property value, rather than a state
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ color: mouser.containsMouse ? "green" : "red"
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+ }
+}
+\endqml
+
+3. Use only explicitly defined states, rather than an implicit base state
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 400
+ height: 400
+
+ Rectangle {
+ id: coloredRect
+ width: 100
+ height: 100
+ anchors.centerIn: parent
+
+ Behavior on color {
+ ColorAnimation {}
+ }
+
+ MouseArea {
+ id: mouser
+ anchors.fill: parent
+ hoverEnabled: true
+ }
+
+ states: [
+ State {
+ name: "GreenState"
+ when: mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "green"
+ }
+ },
+ State {
+ name: "RedState"
+ when: !mouser.containsMouse
+
+ PropertyChanges {
+ target: coloredRect
+ color: "red"
+ }
+ }]
+ }
+}
+\endqml
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-canvaspainting.html
+\ingroup qml-features
+\title Painting with Canvas API
+\brief custom graphics with the Canvas API
+
+\section1 Canvas Element
+
+\list
+ \li \l{Canvas}
+ \li \l{Context2D}
+\endlist
+
+The Canvas and Context2D elements implement the \l{HTML Canvas API 2D Context}
+and allows applications to have custom painting routines.
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-elements.html
+\title Qt Quick Elements
+\brief a listing of standard elements in Qt Quick
+
+
+\target elements
+
+These are the functionally grouped lists of Qt Quick elements as part of
+\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 2} and \l{QtQuick.Particles 2}
+
+Elements are declared with the their name and two curly braces. Elements may
+be nested in elements, thereby creating a parent-child relationship between the
+two elements.
+
+\section1 Basic Elements
+\list
+\li \l {Item} - Basic item element inherited by visual elements
+\endlist
+
+\section1 Graphics
+\list
+\li \l {Rectangle} - A rectangle element
+\li \l {Image} - For incorporating bitmaps into a scene
+\li \l {BorderImage} - Allows the use of images as borders
+\li \l {AnimatedImage} - For playing animations stored in a series of frames
+\li \l {Gradient} - For defining a color gradient
+\li \l {GradientStop} - Used to define a color within a \l {Gradient}
+\li \l {SystemPalette} - Provides access to the Qt palettes
+\li \l {Canvas} - Provides a 2D canvas element
+\endlist
+
+\section1 Text Handling
+\list
+\li \l {Text} - For inserting formatted text into a scene
+\li \l {TextInput} - Captures user key input
+\li \l {TextEdit} - Displays multiple lines of editable formatted text
+\li \l {IntValidator} - Validates values as integers
+\li \l {DoubleValidator} - Validates real values
+\li \l {RegExpValidator} - Validator for string regular expressions
+\li \l {FontLoader} - Loads fonts by name or URL
+\endlist
+
+\section1 Mouse and Interaction Area
+\list
+\li \l {MouseArea} - Sets up an area for mouse interaction
+\li \l {Keys} - Provides components with attached properties to handle key input.
+\li \l {FocusScope} - Element that mediate keyboard focus changes
+\li \l {Flickable} - Provides a surface that can be "flicked"
+\li \l {Flipable} - Provides a surface that produces "flipping" effects
+\li \l {PinchArea} - Enables simple pinch gesture handling
+\li \l {MultiPointTouchArea} - Enables handling of multiple touch points
+\endlist
+
+\section1 Positioners and Repeater
+\list
+\li \l {Column} - Arranges its children vertically
+\li \l {Row} - Arranges its children horizontally
+\li \l {Grid} - Positions its children in a grid
+\li \l {Flow} - Positions its children with wrapping support
+\li \l {Repeater} - Uses a model to create multiple components
+\endlist
+
+\section1 Transformations
+\list
+\li \l {Scale} - Assigns item scaling behaviors
+\li \l {Rotation} - Assigns item rotation behaviors
+\li \l {Translate} - Assigns item translation behaviors
+\endlist
+
+\section1 States
+\list
+\li \l {State} - Defines sets of configurations of objects and properties
+\li \l {PropertyChanges} - Describes property changes within a state
+\li \l {StateGroup} - Contains a set of states and state transitions
+\li \l {StateChangeScript} - Allows script binding in a state
+\li \l {ParentChange} - Re-parent an Item in a state change
+\li \l {AnchorChanges} - Change the anchors of an item in a state
+\endlist
+
+\section1 Animation and Transitions
+\list
+\li \l {Transition} - Animates transitions during state changes
+\li \l {SequentialAnimation} - Runs animations sequentially
+\li \l {ParallelAnimation} - Runs animations in parallel
+\li \l {Behavior} - Specifies a default animation for property changes
+\li \l {PropertyAction} - Sets immediate property changes during animation
+\li \l {PauseAnimation} - Introduces a pause in an animation
+\li \l {SmoothedAnimation} - Allows a property to smoothly track a value
+\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
+\li \l {ScriptAction} - Runs scripts during an animation
+\endlist
+
+Elements that animate properties based on data types
+\list
+\li \l {PropertyAnimation} - Animates property changes
+\li \l {NumberAnimation} - Animates properties of type qreal
+\li \l {Vector3dAnimation} - Animates properties of type QVector3d
+\li \l {ColorAnimation} - Animates color changes
+\li \l {RotationAnimation} - Animates rotations
+\li \l {ParentAnimation} - Animates parent changes
+\li \l {AnchorAnimation} - Animates anchor changes
+\li \l {PathAnimation} - Animates position along a path
+\endlist
+
+Elements that provide lower-level animation control
+\list
+\li \l {PathInterpolator} - Allows manual animation along a path
+\li \l {AnimationController} - Allows manual control of animation progress
+\endlist
+
+\section1 Models and Data Handling
+\list
+\li \l {QtQuick2::ListModel}{ListModel} - Defines a list of data
+\li \l {QtQuick2::ListElement}{ListElement} - Defines a data item in a \l {QtQuick2::ListModel}{ListModel}
+\li \l {VisualItemModel} - Contains items that already defines its own visual delegate
+\li \l {VisualDataModel} - Encapsulates a model and a delegate
+\li \l {XmlListModel} - Specifies a model using XPath expressions
+\li \l {XmlRole} - Specifies a role for an \l {XmlListModel}
+\li \l {Binding} - Binds any value to any property
+\li \l {Package} - Collection that enables sharing of items within different views
+\endlist
+
+\section1 Views
+\list
+\li \l {ListView} - Provides a list visualization of a model
+\li \l {GridView} - Provides a grid visualization of a model
+\li \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information.
+\endlist
+
+\section1 Path Definition
+\list
+\li \l {Path} - Defines a path used by \l {PathView}
+\li \l {PathLine} - Defines a line in \l {Path}
+\li \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path}
+\li \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path}
+\li \l {PathArc} - Defines an arc in a \l {Path}
+\li \l {PathCurve} - Defines a point on a Catmull-Rom curve in a \l {Path}
+\li \l {PathSvg} - Defines a sub-path specified as a SVG path data string in a \l {Path}
+\li \l {PathAttribute} - Allows the setting of attributes along a \l {Path}
+\li \l {PathPercent} - Modifies the item distribution along a \l {Path}
+\endlist
+
+\section1 Utility
+\list
+\li \l {Connections} - Explicitly connects signals and signal handlers
+\li \l {Timer} - Provides timed triggers
+\li \l {Loader} - Controls the loading of items or components
+\endlist
+
+\section1 Graphical Effects
+\list
+\li \l {ShaderEffect} - Allows GLSL shaders to be used as graphical effects
+\li \l {ShaderEffectSource} - Usable as a texture in ShaderEffect
+\li \l {GridMesh} - Generates a gird mesh of vertices for use by ShaderEffect
+\li The \l{QtQuick.Particles 2} module provides a set of Particle System elements for QtQuick 2
+\endlist
+
+\section1 Accessibility
+\list
+\li \l {Accessible} - Attached property to make components accessible
+\endlist
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-keyboardfocus.html
+\ingroup qml-features
+\title Keyboard Focus in QML
+\brief handling keyboard focus
+
+When a key is pressed or released, a key event is generated and delivered to the
+focused QML \l Item. To facilitate the construction of reusable components
+and to address some of the cases unique to fluid user interfaces, the QML items add aged
+\e scope based extension to Qt's traditional keyboard focus model.
+
+\tableofcontents
+
+\section1 Key Handling Overview
+
+When the user presses or releases a key, the following occurs:
+\list 1
+\li Qt receives the key action and generates a key event.
+\li If the Qt widget containing the \l QQuickView has focus, the key event
+is delivered to it. Otherwise, regular Qt key handling continues.
+\li The key event is delivered by the scene to the QML \l Item with
+\e {active focus}. If no Item has active focus, the key event is
+\l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
+\li If the QML Item with active focus accepts the key event, propagation
+stops. Otherwise the event is "bubbled up", by recursively passing it to each
+Item's parent until either the event is accepted, or the root Item is reached.
+
+If the \c {Rectangle} element in the following example has active focus and the \c A key is pressed,
+it will bubble up to its parent. However, pressing the \c B key will bubble up to the root
+item and thus subsequently be ignored.
+
+\snippet doc/snippets/qml/focus/rectangle.qml simple key event
+\snippet doc/snippets/qml/focus/rectangle.qml simple key event end
+
+\li If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
+
+\endlist
+
+See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigation attached property}.
+
+\section1 Querying the Active Focus Item
+
+Whether or not an \l Item has active focus can be queried through the
+property \c {Item::activeFocus} property. For example, here we have a \l Text
+element whose text is determined by whether or not it has active focus.
+
+\snippet doc/snippets/qml/focus/rectangle.qml active focus
+
+\section1 Acquiring Focus and Focus Scopes
+
+An \l Item requests focus by setting the \c focus property to \c true.
+
+For very simple cases simply setting the \c focus property is sometimes
+sufficient. If we run the following example with the \l {QML Viewer}, we see that
+the \c {keyHandler} element has active focus and pressing the \c A, \c B,
+or \c C keys modifies the text appropriately.
+
+\snippet doc/snippets/qml/focus/basicwidget.qml focus true
+
+\image declarative-qmlfocus1.png
+
+However, were the above example to be used as a reusable or imported component,
+this simple use of the \c focus property is no longer sufficient.
+
+To demonstrate, we create two instances of our previously defined component and
+set the first one to have focus. The intention is that when the \c A, \c B, or
+\c C keys are pressed, the first of the two components receives the event and
+responds accordingly.
+
+The code that imports and creates two MyWidget instances:
+\snippet doc/snippets/qml/focus/widget.qml window
+
+The MyWidget code:
+\snippet doc/snippets/qml/focus/MyWidget.qml mywidget
+
+We would like to have the first MyWidget object to have the focus by setting its
+\c focus property to \c true. However, by running the code, we can confirm that
+the second widget receives the focus.
+
+\image declarative-qmlfocus2.png
+
+Looking at both \c MyWidget and \c window code, the problem is evident - there
+are three elements that set the \c focus property set to \c true. The two
+MyWidget sets the \c focus to \c true and the \c window component also sets the
+focus. Ultimately, only one element can have keyboard focus, and the system has
+to decide which element receives the focus. When the second MyWidget is created,
+it receives the focus because it is the last element to set its \c focus
+property to \c true.
+
+This problem is due to visibility. The \c MyWidget component would like to have
+the focus, but it cannot control the focus when it is imported or reused.
+Likewise, the \c window component does not have the ability to know if its
+imported components are requesting the focus.
+
+To solve this problem, the QML introduces a concept known as a \e {focus scope}.
+For existing Qt users, a focus scope is like an automatic focus proxy.
+A focus scope is created by declaring the \l FocusScope element.
+
+In the next example, a \l FocusScope element is added to the component, and the
+visual result shown.
+
+\snippet doc/snippets/qml/focus/myfocusscopewidget.qml widget in focusscope
+
+\image declarative-qmlfocus3.png
+
+
+Conceptually \e {focus scopes} are quite simple.
+\list
+\li Within each focus scope one element may have \c {Item::focus} set to
+\c true. If more than one \l Item has the \c focus property set, the
+last element to set the \c focus will have the focus and the others are unset,
+similar to when there are no focus scopes.
+\li When a focus scope receives active focus, the contained element with
+\c focus set (if any) also gets the active focus. If this element is
+also a \l FocusScope, the proxying behavior continues. Both the
+focus scope and the sub-focused item will have \c activeFocus property set.
+\endlist
+
+Note that, since the FocusScope element is not a visual element, the properties
+of its children need to be exposed to the parent item of the FocusScope. Layouts
+and positioning elements will use these visual and styling properties to create
+the layout. In our example, the \c Column element cannot display the two widgets
+properly because the FocusScope lacks visual properties of its own. The MyWidget
+component directly binds to the \c rectangle properties to allow the \c Column
+element to create the layout containing the children of the FocusScope.
+
+So far, the example has the second component statically selected. It is trivial
+now to extend this component to make it clickable, and add it to the original
+application. We still set one of the widgets as focused by default.
+Now, clicking either MyClickableWidget gives it focus and the other widget
+loses the focus.
+
+The code that imports and creates two MyClickableWidget instances:
+\snippet doc/snippets/qml/focus/clickablewidget.qml clickable window
+
+The MyClickableWidget code:
+\snippet doc/snippets/qml/focus/MyClickableWidget.qml clickable in focusscope
+
+\image declarative-qmlfocus4.png
+
+When a QML \l Item explicitly relinquishes focus (by setting its
+\c focus property to \c false while it has active focus), the
+system does not automatically select another element to receive focus. That is,
+it is possible for there to be no currently active focus.
+
+See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a
+demonstration of moving keyboard focus between multiple areas using FocusScope
+elements.
+
+\section1 Advanced uses of Focus Scopes
+
+Focus scopes allow focus to allocation to be easily partitioned. Several
+QML items use it to this effect.
+
+\l ListView, for example, is itself a focus scope. Generally this isn't
+noticeable as \l ListView doesn't usually have manually added visual children.
+By being a focus scope, \l ListView can focus the current list item without
+worrying about how that will effect the rest of the application. This allows the
+current item delegate to react to key presses.
+
+This contrived example shows how this works. Pressing the \c Return key will
+print the name of the current list item.
+
+\snippet doc/snippets/qml/focus/advancedFocus.qml FocusScope delegate
+
+\image declarative-qmlfocus5.png
+
+While the example is simple, there are a lot going on behind the scenes. Whenever
+the current item changes, the \l ListView sets the delegate's \c {Item::focus}
+property. As the \l ListView is a focus scope, this doesn't affect the
+rest of the application. However, if the \l ListView itself has
+active focus this causes the delegate itself to receive active focus.
+In this example, the root element of the delegate is also a focus scope,
+which in turn gives active focus to the \c {Text} element that actually performs
+the work of handling the \c {Return} key.
+
+All of the QML view classes, such as \l PathView and \l GridView, behave
+in a similar manner to allow key handling in their respective delegates.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-modelview.html
+\title Models and Views
+\brief how to display and form data in QML
+
+Simply put, applications need to form data and display the data. QML has the
+notion of \e models, \e views, and \e delegates to display data. They modularize
+the visualization of data in order to give the developer or designer control
+over the different aspects of the data. A developer can swap a list view with a
+grid view with little changes to the data. Similarly, encapsulating an instance
+of the data in a delegate allows the developer to dictate how to present or
+handle the data.
+
+\image modelview-overview.png
+\list
+\li \b Model - contains the data and its structure. There are several QML
+elements for creating models.
+\li \b View - a container that displays the data. The view might
+display the data in a list or a grid.
+\li \b Delegate - dictates how the data should appear in the view.
+The delegate takes each data in the model and encapsulates it. The data is
+accessible through the delegate.
+\endlist
+
+To visualize data, bind the view's \c model property to a model and the
+\c delegate property to a component or an element.
+
+\section1 Displaying Data with Views
+
+ Views are containers for collections of items. They are feature-rich and can be
+ customizable to meet style or behavior requirements.
+
+ \keyword qml-view-elements
+ A set of standard views are provided in the basic set of Qt Quick
+ graphical elements:
+
+ \list
+ \li \l{ListView} - arranges items in a horizontal or vertical list
+ \li \l{GridView} - arranges items in a grid within the available space
+ \li \l{PathView} - arranges items on a path
+ \endlist
+
+ These elements have properties and behaviors exclusive to each element.
+ Visit their respective documentation for more information.
+
+ \section2 Decorating Views
+
+ Views allow visual customization through \e decoration properties such as
+ the \c header, \c footer, and \c section properties. By binding an object,
+ usually another visual object, to these properties, the views are
+ decoratable. A footer may include a \l Rectangle element showcasing borders
+ or a header that displays a logo on top of the list.
+
+ Suppose that a specific club wants to decorate its members list with its brand
+ colors. A member list is in a \c model and the \c delegate will display the
+ model's content.
+ \snippet doc/snippets/qml/listview-decorations.qml model
+ \snippet doc/snippets/qml/listview-decorations.qml delegate
+
+ The club may decorate the members list by binding visual objects to the \c
+ header and \c footer properties. The visual object may be defined inline, in
+ another file, or in a \l {Component} element.
+ \snippet doc/snippets/qml/listview-decorations.qml decorations
+ \image listview-decorations.png
+
+ \section2 Mouse and Touch Handling
+
+ The views handle dragging and flicking of their content, however they do
+ not handle touch interaction with the individual delegates. In order for the
+ delegates to react to touch input, e.g. to set the \c currentIndex, a MouseArea
+ with the appropriate touch handling logic must be provided by the delegate.
+
+ Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the
+ currentIndex will be affected by dragging/flicking the view, since the view
+ will always ensure that the \c currentIndex is within the highlight range
+ specified.
+
+
+ \section2 ListView Sections
+
+ \l {ListView} contents may be grouped into \e sections, where related list
+ items are labeled according to their sections. Further, the sections may be
+ decorated with \l{qml-view-delegate}{delegates}.
+
+ A list may contain a list indicating people's names and the team on which
+ team the person belongs.
+ \snippet doc/snippets/qml/listview-sections.qml model
+ \snippet doc/snippets/qml/listview-sections.qml delegate
+
+ The ListView element has the \c section \l{Property Binding in QML#Attached
+ Properties}{attached property} that can combine adjacent and related
+ elements into a section. The section's \c property property is for selecting
+ which list element property to use as sections. The \c criteria can dictate
+ how the section names are displayed and the \c delegate is similar to the
+ views' \l {qml-view-delegate}{delegate} property.
+ \snippet doc/snippets/qml/listview-sections.qml section
+ \image listview-section.png
+
+\keyword qml-view-delegate
+\section1 View Delegates
+
+ Views need a \e delegate to visually represent an item in a list. A view will
+ visualize each item list according to the template defined by the delegate.
+ Items in a model are accessible through the \c index property as well as the
+ item's properties.
+ \snippet doc/snippets/qml/listview.qml delegate
+ \image listview-setup.png
+
+ \section2 Accessing Views and Models from Delegates
+
+ The list view to which the delegate is bound is accessible from the delegate
+ through the \c{ListView.view} property. Likewise, the GridView
+ \c{GridView.view} is available to delegates. The corresponding model and its
+ properties, therefore, are available through \c{ListView.view.model}. In
+ addition, any defined signals or methods in the model are also accessible.
+
+ This mechanism is useful when you want to use the same delegate for a number
+ of views, for example, but you want decorations or other features to be
+ different for each view, and you would like these different settings to be
+ properties of each of the views. Similarly, it might be of interest to
+ access or show some properties of the model.
+
+ In the following example, the delegate shows the property \e{language} of
+ the model, and the color of one of the fields depends on the property
+ \e{fruit_color} of the view.
+
+ \snippet doc/snippets/qml/models/views-models-delegates.qml rectangle
+
+\keyword qml-data-models
+\section1 Models
+
+ Data is provided to the delegate via named data roles which the delegate may
+ bind to. Here is a ListModel with two roles, \e type and \e age, and a
+ ListView with a delegate that binds to these roles to display their values:
+
+ \snippet doc/snippets/qml/qml-data-models/listmodel-listview.qml document
+
+ If there is a naming clash between the model's properties and the delegate's
+ properties, the roles can be accessed with the qualified \e model name
+ instead. For example, if a \l Text element had \e type or \e age properties,
+ the text in the above example would display those property values instead of
+ the \e type and \e age values from the model item. In this case, the
+ properties could have been referenced as \c model.type and \c model.age
+ instead to ensure the delegate displays the property values from the model
+ item.
+
+ A special \e index role containing the index of the item in the model is
+ also available to the delegate. Note this index is set to -1 if the item is
+ removed from the model. If you bind to the index role, be sure that the
+ logic accounts for the possibility of index being -1, i.e. that the item is
+ no longer valid. (Usually the item will shortly be destroyed, but it is
+ possible to delay delegate destruction in some views via a \c delayRemove
+ attached property.)
+
+ Models that do not have named roles (such as the ListModel shown
+ below) will have the data provided via the \e modelData role. The \e
+ modelData role is also provided for models that have only one role. In this
+ case the \e modelData role contains the same data as the named role.
+
+ QML provides several types of data models among the built-in set of QML
+ elements. In addition, models can be created with Qt C++ and then made
+ available to the \l{The QML Engine}{QML engine} for use by
+ QML components. For information about creating these models, visit the
+ \l{Exposing C++ Models} and \l{Creating QML Types} articles.
+
+ The use of positioner items to arrange items from a model is covered in
+ \l{Generating Items with Repeaters}.
+
+ \section2 ListModel
+
+ ListModel is a simple hierarchy of elements specified in QML. The
+ available roles are specified by the \l ListElement properties.
+
+ \snippet doc/snippets/qml/qml-data-models/listelements.qml model
+
+ The above model has two roles, \e name and \e cost. These can be bound
+ to by a ListView delegate, for example:
+
+ \snippet doc/snippets/qml/qml-data-models/listelements.qml view
+
+ ListModel provides methods to manipulate the ListModel directly via JavaScript.
+ In this case, the first item inserted determines the roles available
+ to any views that are using the model. For example, if an empty ListModel is
+ created and populated via JavaScript, the roles provided by the first
+ insertion are the only roles that will be shown in the view:
+
+ \snippet doc/snippets/qml/qml-data-models/dynamic-listmodel.qml model
+ \dots
+ \snippet doc/snippets/qml/qml-data-models/dynamic-listmodel.qml mouse area
+
+ When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name.
+ Even if subsequent roles are added, only the first two will be handled by views
+ using the model. To reset the roles available in the model, call ListModel::clear().
+
+
+ \section2 XmlListModel
+
+ XmlListModel allows construction of a model from an XML data source. The roles
+ are specified via the \l XmlRole element. The element needs to be imported.
+
+ \code
+ import QtQuick.XmlListModel 2.0
+ \endcode
+
+
+ The following model has three roles, \e title, \e link and \e description:
+ \qml
+ XmlListModel {
+ id: feedModel
+ source: "http://rss.news.yahoo.com/rss/oceania"
+ query: "/rss/channel/item"
+ XmlRole { name: "title"; query: "title/string()" }
+ XmlRole { name: "link"; query: "link/string()" }
+ XmlRole { name: "description"; query: "description/string()" }
+ }
+ \endqml
+
+ The \l{declarative/rssnews}{RSS News demo} shows how XmlListModel can
+ be used to display an RSS feed.
+
+
+ \section2 VisualItemModel
+
+ VisualItemModel allows QML items to be provided as a model.
+
+ This model contains both the data and delegate; the child items of a
+ VisualItemModel provide the contents of the delegate. The model
+ does not provide any roles.
+
+ \snippet doc/snippets/qml/models/visual-model-and-view.qml visual model and view
+
+ Note that in the above example there is no delegate required.
+ The items of the model itself provide the visual elements that
+ will be positioned by the view.
+
+ \section2 Integers as Models
+
+ An integer can be used as a model that contains a certain number
+ of elements. In this case, the model does not have any data roles.
+
+ The following example creates a ListView with five elements:
+ \qml
+ Item {
+ width: 200; height: 250
+
+ Component {
+ id: itemDelegate
+ Text { text: "I am item number: " + index }
+ }
+
+ ListView {
+ anchors.fill: parent
+ model: 5
+ delegate: itemDelegate
+ }
+
+ }
+ \endqml
+
+
+ \section2 Object Instances as Models
+
+ An object instance can be used to specify a model with a single object
+ element. The properties of the object are provided as roles.
+
+ The example below creates a list with one item, showing the color of the \e
+ myText text. Note the use of the fully qualified \e model.color property to
+ avoid clashing with \e color property of the Text element in the delegate.
+
+ \qml
+ Rectangle {
+ width: 200; height: 250
+
+ Text {
+ id: myText
+ text: "Hello"
+ color: "#dd44ee"
+ }
+
+ Component {
+ id: myDelegate
+ Text { text: model.color }
+ }
+
+ ListView {
+ anchors.fill: parent
+ anchors.topMargin: 30
+ model: myText
+ delegate: myDelegate
+ }
+ }
+ \endqml
+
+ \keyword qml-c++-models
+ \section2 C++ Data Models
+
+ Models can be defined in C++ and then made available to QML. This mechanism
+ is useful for exposing existing C++ data models or otherwise complex
+ datasets to QML.
+
+ For information, visit the \l{Exposing C++ Models} article.
+
+
+\section1 Repeaters
+
+\div {class="float-right"}
+\inlineimage repeater-index.png
+\enddiv
+
+Repeaters create items from a template for use with positioners, using data
+from a model. Combining repeaters and positioners is an easy way to lay out
+lots of items. A \l Repeater item is placed inside a positioner, and generates
+items that the enclosing positioner arranges.
+
+Each Repeater creates a number of items by combining each element of data
+from a model, specified using the \l{Repeater::model}{model} property, with
+the template item, defined as a child item within the Repeater.
+The total number of items is determined by the amount of data in the model.
+
+The following example shows a repeater used with a \l{#Grid}{Grid} item to
+arrange a set of Rectangle items. The Repeater item creates a series of 24
+rectangles for the Grid item to position in a 5 by 5 arrangement.
+
+\snippet doc/snippets/qml/repeaters/repeater-grid-index.qml document
+
+The number of items created by a Repeater is held by its \l{Repeater::}{count}
+property. It is not possible to set this property to determine the number of
+items to be created. Instead, as in the above example, we use an integer as
+the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models}
+document.
+
+It is also possible to use a delegate as the template for the items created
+by a Repeater. This is specified using the \l{Repeater::}{delegate} property.
+
+\section1 Using Transitions
+
+Transitions can be used to animate items that are added to, moved within,
+or removed from a positioner.
+
+Transitions for adding items apply to items that are created as part of a
+positioner, as well as those that are reparented to become children of a
+positioner.
+Transitions for removing items apply to items within a positioner that are
+deleted, as well as those that are removed from a positioner and given new
+parents in a document.
+
+Additionally, changing the opacity of items to zero will cause them to
+disappear using the remove transition, and making the opacity non-zero will
+cause them to appear using the add transition.
+
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-mouseevents.html
+\ingroup QML Features
+\title Mouse Events
+\brief handling mouse events in QML
+
+\tableofcontents
+
+\section1 Mouse Elements
+
+\list
+\li \l{MouseArea} Element
+\li \l{MouseEvent} Object
+\endlist
+
+\section1 Mouse Event Handling
+
+QML uses \l{QML Signal and Handler Event System}{signals and handlers} to
+deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent
+elements provide QML components with signal handlers to accept mouse events
+within a defined area.
+
+\section1 Defining a Mouse Area
+
+The \l MouseArea element receives events within a defined area. One quick way
+to define this area is to anchor the \c MouseArea to its parent's area using the
+\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
+component), then the MouseArea will fill the area defined by the parent's
+dimensions. Alternatively, an area smaller or larger than the parent is
+definable.
+\snippet doc/snippets/qml/mousearea/mousearea-snippet.qml anchor fill
+
+\section1 Receiving Events
+
+The MouseArea element provides
+\l{QML Signal and Handler Event System}{signals and handlers} to detect different
+mouse events. The \l MouseArea element documentation describes these
+gestures in greater detail:
+
+\list
+\li canceled
+\li clicked
+\li doubleClicked
+\li entered
+\li exited
+\li positionChanged
+\li pressAndHold
+\li pressed
+\li released
+\endlist
+
+These signals have signal handlers that are invoked when the signals are emitted.
+\snippet doc/snippets/qml/mousearea/mousearea-snippet.qml mouse handlers
+
+\section1 Enabling Gestures
+Some mouse gestures and button clicks need to be enabled before they send or
+receive events. Certain \l MouseArea and \l MouseEvent properties enable these
+gestures.
+
+To listen to (or explicitly ignore) a certain mouse button, set the appropriate
+mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
+
+Naturally, the mouse events, such as button presses and mouse positions, are
+sent during a mouse click. For example, the \c containsMouse property will only
+retrieve its correct value during a mouse press. The
+\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
+positioning even when there are no mouse button presses. Setting the
+\c hoverEnabled property to \c true, in turn will enable the \c entered,
+\c exited, and \c positionChanged signal and their respective signal handlers.
+
+\snippet doc/snippets/qml/mousearea/mousearea-snippet.qml enable handlers
+Additionally, to disable the whole mouse area, set the \c MouseArea
+element's \c enabled property to \c false.
+
+\section1 MouseEvent Object
+
+Signals and their handlers receive a \l MouseEvent object as a parameter. The
+\c mouse object contain information about the mouse event. For example, the
+mouse button that started the event is queried through the
+\l {MouseEvent::button}{mouse.button} property.
+
+The \c MouseEvent object can also ignore a mouse event using its \c accepted
+property.
+
+\section2 Accepting Further Signals
+Many of the signals are sent multiple times to reflect various mouse events
+such as double clicking. To facilitate the classification of mouse clicks, the
+MouseEvent object has an \c accepted property to disable the event propagation.
+
+To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-positioners.html
+\ingroup qml-features
+\title Item Layouts
+
+Positioner items are container items that manage the positions and sizes of
+items in a declarative user interface. Positioners behave in a similar way to
+the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets,
+except that they are also containers in their own right.
+
+Positioners make it easier to work with many items when they need
+to be arranged in a regular layout.
+
+\section1 Positioners
+
+A set of standard positioners are provided in the basic set of Qt Quick
+graphical elements:
+
+\list
+\li \l{#Column}{Column} arranges its children in a column
+\li \l{#Row}{Row} arranges its children in a row
+\li \l{#Grid}{Grid} arranges its children in a grid
+\li \l{#Flow}{Flow} arranges its children like words on a page
+\endlist
+
+\section2 Column
+
+\div {class="float-right"}
+\inlineimage qml-column.png
+\enddiv
+
+\l Column items are used to vertically arrange items. The following example
+uses a Column item to arrange three \l Rectangle items in an area defined
+by an outer \l Item. The \l{Column::spacing}{spacing} property is set to
+include a small amount of space between the rectangles.
+
+\snippet doc/snippets/qml/column/column.qml document
+
+Note that, since Column inherits directly from Item, any background color
+must be added to a parent Rectangle, if desired.
+
+\section2 Row
+
+\div {class="float-right"}
+\inlineimage qml-row.png
+\enddiv
+
+\l Row items are used to horizontally arrange items. The following example
+uses a Row item to arrange three rounded \l Rectangle items in an area defined
+by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to
+include a small amount of space between the rectangles.
+
+We ensure that the parent Rectangle is large enough so that there is some space
+left around the edges of the horizontally centered Row item.
+
+\snippet doc/snippets/qml/row.qml document
+
+\section2 Grid
+
+\div {class="float-right"}
+\inlineimage qml-grid-spacing.png
+\enddiv
+
+\l Grid items are used to place items in a grid or table arrangement.
+The following example uses a Grid item to place four \l Rectangle items
+in a 2-by-2 grid. As with the other positioners, the spacing between items
+can be specified using the \l{Grid::spacing}{spacing} property.
+
+\snippet doc/snippets/qml/grid-spacing.qml document
+
+There is no difference between horizontal and vertical spacing inserted
+between items, so any additional space must be added within the items
+themselves.
+
+Any empty cells in the grid must be created by defining placeholder items
+at the appropriate places in the Grid definition.
+
+\section2 Flow
+
+\div {class="float-right"}
+\inlineimage qml-flow-text1.png
+\inlineimage qml-flow-text2.png
+\enddiv
+
+\l Flow items are used to place items like words on a page, with rows or
+columns of non-overlapping items.
+
+Flow items arrange items in a similar way to \l Grid items, with items
+arranged in lines along one axis (the minor axis), and lines of items
+placed next to each other along another axis (the major axis). The
+direction of flow, as well as the spacing between items, are controlled
+by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties.
+
+The following example shows a Flow item containing a number of \l Text
+child items. These are arranged in a similar way to those shown in the
+screenshots.
+
+\snippet doc/snippets/qml/flow.qml document
+
+The main differences between the Grid and Flow positioners are that items
+inside a Flow will wrap when they run out of space on the minor axis, and
+items on one line may not be aligned with items on another line if the
+items do not have uniform sizes. As with Grid items, there is no independent
+control of spacing between items and between lines of items.
+
+\section1 Other Ways to Position Items
+
+There are several other ways to position items in a user interface. In addition
+to the basic technique of specifying their coordinates directly, they can be
+positioned relative to other items with \l{anchor-layout}{anchors}, or used
+with \l{QML Data Models} such as
+\l{QML Data Models#VisualItemModel}{VisualItemModel}.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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-intro.html tutorial
+\title Introduction to the QML Language
+\brief Introduction to the concepts and features behind QML.
+
+QML is a declarative language designed to describe the user interface of a
+program: both what it looks like, and how it behaves. In QML, a user
+interface is specified as a tree of objects with properties.
+
+This introduction is meant for those with little or no programming
+experience. JavaScript is used as a scripting language in QML, so you may want
+to learn a bit more about it (see the online \l{Javascript Guide}) before
+diving deeper into QML. It is also helpful to have a basic understanding of
+other Web technologies like HTML and JSON, but it is not required.
+
+The examples shown in this guide are located in the
+\c{examples/declarative/tutorials/qmlintro} directory within the Qt source
+package. You can run then with the \l{QML Viewer} tool.
+
+\section1 \l{QML Concepts and Syntax}
+\tableofcontents{1 QML Concepts and Syntax}{section4}
+
+\section1 \l{Composing User Interfaces with QML}
+\tableofcontents{1 Composing User Interfaces with QML}{section4}
+
+\section1 \l{User Interaction with QML}
+\tableofcontents{1 User Interaction with QML}{section4}
+*/
+
+/*!
+\page qml-basic-syntax.html
+\brief The basic syntax and concepts of the QML language.
+\contentspage Introduction to the QML Language
+\previouspage Introduction to the QML Language
+\nextpage Composing User Interfaces with QML
+\title QML Concepts and Syntax
+
+\tableofcontents
+
+This chapter covers the basic syntax of the QML language through the
+use of examples, introducing the concepts behind the language and
+the terminology used in the reference documentation.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-basic-syntax.png
+\enddiv
+The following example shows the basic syntax of QML. When opened in
+the \l{QML Viewer}{\QQV tool}, the output displayed should match the
+image shown on the right: a light blue rectangle.
+
+\snippet examples/declarative/tutorials/qmlintro/basic-syntax.qml document
+
+In this example, we import the features defined by Qt Quick 1.0, and
+we declare and create a single rectangle with width, height and color.
+Let's take a look at the main points of the language introduced by
+this simple example.
+
+\section1 Importing Modules
+
+The \c import statement imports the \c QtQuick \l{QML Modules}{module},
+which contains all of the standard \l{QML Elements}. Without this import
+statement, the \l Rectangle and other elements would not be available.
+
+A specific version of a module is imported. This guarantees that the
+elements imported when the application is run by the user match those
+used by the developer when the application was written, ensuring that
+they have the expected behavior.
+
+\section1 Elements
+
+The rectangle in the above example is specified by the \l Rectangle
+element. When we declare objects like this, we write the element's type
+followed by a pair of braces in between which additional data can be
+defined for the object, such as its property values and any child objects.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-elements1.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/elements1.qml document
+
+Here, we create two elements: a rectangle with an image inside it. We say that
+the rectangle is the parent element and the image is its child. Since the
+rectangle does not have a parent element, it is a top level element.
+
+The position of each element in the user interface is defined relative
+to the position of its parent, except for the top level element whose
+position is always the top-left corner of the screen.
+
+QML files can contain multiple elements, but \e{only one} can be a top level
+element.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-elements2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/elements2.qml document
+
+In this example, we can define as many elements inside the rectangle
+as we like, but we cannot define other top level elements. All the
+additional elements are defined inside the light blue rectangle.
+
+\note In the QML documentation, we refer to \e elements, \e items and
+\e components, often interchangeably.
+
+\list
+\li When we talk about an \e element, we usually mean the syntactic structure,
+ including the name, the opening and closing braces, and its contents.
+\li An \e item is an element that has a visual appearance. All items are
+ elements that inherit \l Item either directly or indirectly. For example,
+ a \l Rectangle is an item, but a \l State is an element because it does
+ not have an intrinsic appearance.
+\li A \e component is an element that is defined to be reused. In many cases,
+ components are often items, too.
+\endlist
+
+For now, we will refer to elements and items. Components are discussed in
+detail later in this guide.
+
+A list of the most common elements is described on the \l{QML Basic Elements}
+page. A full list can be found on the \l{QML Elements} page.
+
+\section1 Properties
+
+A QML element usually has various \e properties that help define the element.
+For example, all items have the \l{Item::}{x} and \l{Item::}{y} properties
+that define the position of the item relative to its parent item (or the
+screen's origin) and \l{Item::}{width} and \l{Item::}{height} properties
+that define its dimensions. All simple properties have names that begin
+with a lower case letter.
+
+\section2 Setting Properties
+
+Properties are specified with a \c{property: value} syntax. In the above
+example, we can see the \l Image object has a property named \c source,
+which has been assigned the value \c{"pics/logo.png"}. The property and its
+value are separated by a colon.
+
+Properties can be specified one-per-line:
+
+\qml
+Rectangle {
+ width: 100
+ height: 100
+}
+\endqml
+
+or you can put multiple properties on a single line:
+
+\qml
+Rectangle { width: 100; height: 100 }
+\endqml
+
+When multiple property-value pairs are specified on a single line, they
+must be separated by a semicolon.
+
+\section2 Basic Property Types
+
+QML supports properties of many types (see \l{QML Basic Types}). The basic types
+include \c int, \c real, \c bool, \c string and \c color.
+
+\qml
+Item {
+ x: 10.5 // a 'real' property
+ state: "details" // a 'string' property
+ focus: true // a 'bool' property
+ // ...
+}
+\endqml
+
+QML properties are what is known as \e type-safe. That is, they 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 {
+ x: "hello" // illegal!
+}
+\endcode
+
+Property values are dynamic, responding to changes in the user interface.
+See the \l{#Property Change Notifications}{Property Change Notifications}
+section for information on the different ways to define properties, bind
+them together and react to changes.
+
+\section2 Grouped Properties
+\target dot properties
+
+Some elements contain a set of related properties that form a logical group;
+these use a "dot" or grouped notation to show this. The \l Text item is one
+such item that uses groups of properties to describe the font used to
+display text.
+
+Grouped properties can be written like this:
+
+\snippet examples/declarative/tutorials/qmlintro/grouped-properties1.qml text with grouped properties
+
+or like this:
+
+\snippet examples/declarative/tutorials/qmlintro/grouped-properties2.qml text with grouped properties
+
+In the element documentation, grouped properties are shown using the "dot" notation.
+
+\section2 List Properties
+
+Some properties contain lists of elements, such as \l State, \l Item or
+\l Transition. For example, the \l{Item::}{states} property is used like
+this:
+
+\qml
+Item {
+ states: [
+ State { name: "stop" },
+ State { name: "go" }
+ ]
+}
+\endqml
+
+The list is enclosed in square brackets, with a comma separating the list
+elements. In cases where you are only assigning a single element to a list,
+you can omit the square brackets:
+
+\qml
+Item {
+ states: State { name: "stop" }
+}
+\endqml
+
+Elements in the list can be accessed by index. See the \l{list}{list type}
+documentation for more details about list properties and their available
+operations.
+
+\section1 Expressions
+
+JavaScript expressions can be used to assign property values. For example:
+
+\qml
+Item {
+ width: 100 * 3
+ height: 50 + 22
+}
+\endqml
+
+These expressions can include references to other objects and properties, in
+which case a \l{Property Binding in QML}{binding} is established: when the value of
+the expression changes, the property to which the expression is assigned is
+automatically updated to the new value. For example:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-property-binding1.png
+\br
+\inlineimage declarative-qmlintro-property-binding2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/property-binding.qml elements
+
+Here, the child \l Rectangle item's \c width property is set relative to
+the width of its parent. Whenever the parent's width changes, the width of
+the \l Rectangle is automatically updated. This uses the special \c parent
+property to refer to a parent item, which we explore in the
+\l{Object Identifiers}{next section}.
+
+This is useful for relating the size of one element to another, so that
+changes to the sizes of elements in the design, or at run-time, will be
+taken into account.
+
+Property binding works with all types of properties, not just those related
+to the size of an element.
+
+\section1 Object Identifiers
+
+Each object can be given a special \e id value that allows the object to
+be identified and referred to by other objects. An \c id must begin with
+a lower-case letter or an underscore, and cannot contain characters other
+than letters, numbers and underscores.
+
+For example, below we define a \l Text element and a \l Rectangle element
+as children of a \l Column element. The \l Text object has an \c id value
+of \c{textElement}. The Rectangle object defines its \c width property
+to be the same as that of the Text object by referring to
+\c{textElement.width}:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-object-identifiers.png
+\enddiv
+
+\snippet examples/declarative/tutorials/qmlintro/object-identifiers.qml document
+
+An object can be referred to by its \c id from anywhere within the
+\l{QML Documents}{component} in which it is declared. Therefore, an
+\c id value must always be unique within a single component.
+This means that a single QML file should only contain one place where
+a particular \c id value is defined.
+
+The \c id value is a special value for a QML object and should not be
+thought of as an ordinary object property; for example, it is not possible
+to access \c{textElement.id} in the above example. Once an object is
+created, its \c id cannot be changed.
+
+\note The \c parent value is a special identity that each element can use
+to refer to its parent item. For most simple user interfaces containing
+a few display items, the parent of an item will be the enclosing element
+in the QML file that contains it. However, when we look at more complex
+ways to arrange and display items, we will find that this is not always
+the case.
+
+\section1 Comments
+
+Commenting in QML is similar to JavaScript.
+\list
+\li Single line comments start with // and finish at the end of the line.
+\li Multi-line comments start with /* and finish with *\/
+\endlist
+
+Comments are ignored by the QML engine. They are useful for explaining what
+you are doing; for referring back to at a later date, or for others reading
+your QML files.
+
+\snippet examples/declarative/tutorials/qmlintro/comments.qml commenting
+
+Comments can also be used to prevent the execution of code, which is
+sometimes useful for tracking down problems. In the above example, the
+\l Text element will have normal opacity, since the line containing the
+opacity property has been turned into a comment.
+
+\section1 Responding to Changes
+
+User interfaces created using QML contain items such as \l Rectangle,
+\l Image and \l Text to display content, but they can also contain items
+that accept user input, such as \l TextInput and \l MouseArea. When the
+user interacts with these items, they emit signals to inform other
+components of any change. These signals can be received by the items
+themselves; this is the main way to create items that respond to the user.
+
+\section2 Signal Handlers
+
+Signal handlers allow JavaScript code to be executed in response to a signal.
+For example, the \l MouseArea element has an \l{MouseArea::}{onClicked} handler
+that can be used to respond to a mouse click. Below, we use this handler to
+print a message whenever the mouse is clicked:
+
+\snippet examples/declarative/tutorials/qmlintro/signal-handlers.qml document
+
+All signal handlers begin with \e "on".
+
+Some signal handlers include an optional parameter. For example
+the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter
+that contains information about the mouse press. This parameter can be
+referred to in the JavaScript code, as below:
+
+\snippet examples/declarative/tutorials/qmlintro/signal-handlers-parameters.qml mouse area
+
+\section2 Property Change Notifications
+
+When a property changes value, it can send a signal to notify others of this change.
+
+To receive these signals, simply create a \e{signal handler} named with an
+\e on<Property>Changed syntax. For example, the \l TextInput element has a
+\l{TextInput::}{text} property. When this property changes, the \c textChanged
+signal is emitted. We can monitor this property for changes with the
+\c onTextChanged handler.
+
+\table
+\header \li Property \li Signal \li Signal Handler
+\row \li \l{TextInput::}{text} \li \c textChanged \li \c onTextChanged
+\endtable
+
+The following code shows this in practice:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-property-change1.png
+\br
+\inlineimage declarative-qmlintro-property-change2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/property-change.qml property change
+
+When the user modifies the text, the expression assigned to the \c textChanged
+handler will be evaluated. In this example, the text changes color when this
+happens.
+
+Similarly, the \l Rectangle element has \l{Item::}{width} and
+\l{Rectangle::}{color} properties. Below, we have a \l Rectangle element
+that has defined two signal handlers, \c onWidthChanged and \c onColorChanged,
+which will automatically be called whenever these properties are modified:
+
+\qml
+Rectangle {
+ width: 100; height: 100
+
+ onWidthChanged: console.log("Width has changed to:", width)
+ onColorChanged: console.log("Color has changed to:", color)
+}
+\endqml
+
+These cause the new values of these properties to be written to the console,
+which can be useful for debugging purposes.
+
+\section2 Attached Properties
+\target attached-properties
+
+Some elements attach properties to other elements. This is used in cases
+where one element needs to access features of another, but does not
+inherit properties to access those features.
+
+Attached Properties are of the form \e {<Type>.<property>} where \e <Type>
+is the type of the element that attaches \e <property>.
+
+An example of attached properties in use involves the \l Keys element which
+attaches properties for handling key presses to any item. For example:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-attached-properties.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/attached-properties.qml attached properties
+
+The \l Keys properties are not defined by the \l Item element. They are
+defined separately and attached to the item.
+
+Attached properties are also used by delegates to reference information about
+the view they are used in. For example, the \l ListView element attaches
+the \e ListView.isCurrentItem property to each delegate it creates:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-attached-properties-view.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/attached-properties-view.qml delegate with attached property
+
+In effect, by attaching this property, \l ListView provides an interface
+that lets the delegate access information about the current item in the
+view it appears in.
+
+The use of attached properties will be covered in more depth later in this
+guide.
+
+\omit
+\section2 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:
+\qml
+State {
+ changes: [
+ PropertyChanges {},
+ PropertyChanges {}
+ ]
+}
+\endqml
+
+can be simplified to:
+
+\qml
+State {
+ PropertyChanges {}
+ PropertyChanges {}
+}
+\endqml
+
+because \c changes is the default property of the \c State type.
+\endomit
+*/
+
+/*!
+\page qml-composing-uis.html
+\contentspage Introduction to the QML Language
+\previouspage QML Concepts and Syntax
+\nextpage User Interaction with QML
+\title Composing User Interfaces with QML
+\brief How to arrange items with anchors.
+
+\tableofcontents
+
+In the \l{Introduction to the QML Language}{previous chapter}, we looked at
+the syntax of QML and the basic building blocks that are used to create
+user interfaces. For example, at a low level, we have seen that an item's
+\c x and \c y properties are used to position it within its parent item.
+However, when defining more complex user interfaces, especially those with
+items that will move or change size, we need a way to arrange items in a
+more systematic way.
+
+\section1 Anchors and Anchor Lines
+
+In the previous examples, all the items have been given either absolute
+positions in the user interface or positions relative to their parents.
+For more flexibility, both at design-time and in the case where the user
+interface changes at run-time, we prefer to use anchors to arrange items.
+
+Anchors connect items together visually, creating relationships between
+their geometries. As a result, mixing absolute positioning and anchors
+is only recommended in cases where the constraints imposed by each
+approach do not conflict. Anchors can only be used to relate items
+with their parents, children or siblings.
+
+\section2 Anchoring within Items
+
+Anchors can be used to generally describe how items are positioned
+within the space occupied by their parents. Two of the anchors are used
+to place items in this way.
+
+The following example uses anchors to position a \l Text item in the
+center of a \l Rectangle.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-centerin.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors.qml centered text
+
+In this case, the center of the text item is anchored to the center of
+its parent item by using the \c{anchors.centerIn} grouped property.
+This defines a high level description of the relationship between the two
+items. Similarly, the \c{anchors.fill} grouped property is used to describe
+the case where an item needs to fill the space provided by its parent.
+
+\note When using \c{anchors.centerIn} and \c{anchors.fill}, the value of
+the anchor property is an item.
+
+\section2 Anchor Lines
+
+At a lower level, anchors can be used to line up the edges of two items.
+In the following example, the \l Text item is centered within its parent,
+the \l Item that defines the user interface. The \l Rectangle uses anchors
+to define its position relative to the text item.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-edges.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors2.qml anchored items
+
+By giving the text item the \c textItem identifier, we can refer to it when
+defining the anchors for the rectangle. We line up the right edge of the
+rectangle with the left edge of the text item, and line up their top edges.
+
+This example shows the use of anchor lines. Grouped properties are defined
+for key parts of each item, including its top, left, right and bottom edges,
+plus the lines running through the horizontal center and vertical center of
+the item. A baseline anchor line is also used for items that display text.
+
+\note We connect anchor lines to other anchor lines, not to items.
+
+\section2 Anchors and Property Bindings
+
+Since the anchor definitions are property bindings, any changes to the
+position of an anchor will cause any connected anchors to move as well.
+This is illustrated by the following example, which places a red rectangle
+beneath a \l TextInput item and uses anchors to ensure that it is always
+the same width.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-expanding1.png
+\br
+\inlineimage declarative-qmlintro-anchors-expanding2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors-expanding.qml anchored items
+
+The anchor lines on the left and right edges of the rectangle are connected
+to those of the text input item. Since the text can be modified by the user,
+the width of the item can change. The use of anchors causes the width of the
+rectangle to change as well.
+
+The \l{Anchor-Based Layout in QML} document covers the use of anchors in
+more detail.
+
+\section2 Margins
+
+Although anchors are useful for lining up items, it is often useful to leave
+small gaps between the edges of adjacent items. The following example lines
+up an \l Image item with a \l Text item, but uses a margin to leave a gap
+between them.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-margins.png
+\br
+\inlineimage declarative-qmlintro-anchors-baseline-margins.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors-margins.qml anchored items
+
+Note that the image also uses a margin to leave a gap between its left edge
+and the left edge of the user interface.
+
+Adding \l Rectangle items to the scene description, we can see the effects of
+the anchors and margins, with the image displaced from the left edge of its
+parent item and the text label displaced from the right edge of the image.
+
+\section2 Limitations and Strategies
+
+Anchors allow the relationships between items to be described using simple
+declarations, maintaining a user interface layout when items move or change
+size. They are useful in most situations, but have limitations which need
+to be considered, and therefore it is a good idea to adopt strategies for
+using them.
+
+\section3 Limitations of Anchors
+
+Since anchors can only be used to relate an item with its parent, children or
+siblings, care must be taken when referencing items in complex or deeply-nested
+user interfaces. Where there are lots of items to be arranged, it can be more
+productive to use \l{#Positioners}{positioners} and
+\l{Generating Items with Repeaters}{repeaters}, or
+\l{Models and Views}{models and views}.
+
+Connections between anchors cannot be deleted and will override explicit
+declarations of positions and sizes using the \l{Item::}{x}, \l{Item::}{y},
+\l{Item::}{width} and \l{Item::}{height} properties of items.
+
+Since anchors rely on property binding to ensure that items are dynamically
+updated if one of them changes, each anchor definition creates a new dependency
+on another item. Use of anchors therefore causes a dependency graph defining an
+order in which items will be updated. Problems can occur if circular dependencies
+are created between items. The following example shows this occurring with a
+parent item and its child.
+
+\snippet examples/declarative/tutorials/qmlintro/circular.qml circular
+
+\section3 Strategies for Use
+
+In order to reference an item with an anchor, it needs a way to be identified.
+Children of the item can refer to it as \c parent, but otherwise it needs to
+define an \l{Introduction to the QML Language#Object Identifiers}{identifier}.
+It is good practice to define identifiers for all the items that need to be
+positioned or referenced in some way unless those items can be referenced
+using the \c parent identifier.
+
+It is usually helpful to identify the fixed or dominant parts of the user
+interface and give those items identifiers so that dependent items can refer
+to them. This avoids potential issues with circular dependencies.
+In the example shown, the \c launchBox and \c cancelBox items are anchored
+within the top level item that contains the user interface. Each of these
+items contain an image and a text item that are anchored to their parent.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-strategy-annotated.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors-strategy.qml anchor strategy
+
+The above example shows how each item is anchored to its parent. This ensures
+that the dependencies introduced by the anchors all consistently point to each
+item's parent or a sibling. It is not always possible to ensure such simple
+dependencies between items. As a result, it is often necessary to consider
+other factors that determine how the use of anchors will affect the geometries
+of items.
+
+When positioning items using the \c horizontalCenter anchor, do not use the
+\c left or \c right anchors; define the width of the item instead, either as
+a fixed value or as a proportion of the parent item. Similarly, avoid using
+the \c top or \c bottom anchors with the \c verticalCenter anchor; set the
+height of the item instead.
+
+Items that define their own width and height based on their contents, like
+\l Image or \l TextInput, can be used with all kinds of anchors. Care must
+be taken to avoid imposing conflicting constraints on their dimensions.
+For example, using \c left and \c right anchors to position a text input
+item may be problematic because the item determines its own width and it
+may change.
+
+When defining an item that you want to stretch to fill the available space
+between other items, make sure that you anchor the stretchable item to items
+with well-defined or implicitly-defined sizes and not the other way round.
+The following example shows this with a \l Text item with an implicit size
+and a \l Rectangle that stretches to fill the remaining space in its parent
+item.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-anchors-stretch.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/anchors-stretch.qml items
+
+The rectangle uses anchors to define its top, left and right edges in terms
+of its parent item, and the bottom edge is aligned with the top of the text
+item. If, instead, the text item is anchored to the rectangle, which has no
+implicit size, the layout of the user interface will be broken because the
+rectangle will be assigned a zero height.
+
+\section1 Positioners
+
+Positioner items are container items that manage the positions and sizes of
+items in a declarative user interface. Positioners behave in a similar way to
+the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets,
+except that they are also containers in their own right.
+
+Positioners make it easier to work with many items when they need to be
+arranged in a regular layout. As we will see when we encounter
+\l{Generating Items with Repeaters}{Repeaters}, it is easier to describe
+how items should be arranged when there are many of them than it is to
+try and individually position them.
+
+\section2 Standard Positioners
+
+A set of standard positioners are provided in the basic set of Qt Quick items.
+Since these are all based on the \l Item element, they contain properties that
+define their positions and sizes, but they do not have any visual appearance
+of their own; they simply arrange their child items in the space allocated to
+them. Any background color, if desired, must be added to a parent Rectangle.
+
+\list
+\li \l{#Row}{Row} arranges its children in a row.
+\li \l{#Column}{Column} arranges its children in a column.
+\li \l{#Grid}{Grid} arranges its children in a grid.
+\li \l{#Flow}{Flow} arranges its children like words on a page.
+\endlist
+
+Each of these items provides many of the same properties as the others,
+making it easy to exchange one with another at a later point in the design
+of an application or component. The common properties are \c spacing,
+\c add and \c move. As expected, the \l{Row::spacing}, \l{Column::spacing}
+and \l{Grid::spacing} properties have slightly different meanings because
+they describe how space is added to different kinds of layout.
+
+The \c add and \c move properties describe what should happen when items
+are added to a positioner item or moved within it. These actions are
+described with \l{QML Animation and Transitions}{transitions}, and will
+be covered later.
+
+\section3 Row
+
+\l Row items are used to horizontally arrange items. The following example
+uses a Row item to arrange three rounded \l Rectangle items in an area defined
+by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to
+include a small amount of space between the rectangles.
+
+\div {class="float-right"}
+\inlineimage qml-row.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/row.qml document
+
+We ensure that the parent \l Rectangle is large enough so that there is some space
+left around the edges of the horizontally centered Row item. The equally-sized
+rectangles in this example automatically line up because they each have the
+same height. Items with different heights will not be positioned vertically
+by the \l Row; these need to be lined up using anchors.
+
+Since the \l Row item is responsible for positioning its child items
+horizontally, those child items cannot use anchors to position themselves
+within the row. However, they can use anchors to align themselves vertically
+relative to one another or to the row itself. The following example uses
+\c verticalCenter anchors to vertically align three rectangles with
+different sizes.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-row-anchors.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/row-anchors.qml row
+
+Note that the \l Row item itself uses \c horizontalCenter and \c verticalCenter
+anchors to place itself in the center of its parent. It is free to do this
+because it is not being positioned by its parent, a \l Rectangle. However,
+when we place positioners inside other positioner, such as a \l Row inside
+a \l Column, we will need to be aware of what constraints are being imposed
+by the positioner's parent item. This is
+\l{#Nesting Positioner Items}{discussed later} in this chapter.
+
+The height of the row is dependent on the heights of the individual child
+items and, unless specified using the \c height property or with anchors,
+it will only be as high as the tallest child item.
+
+\section3 Column
+
+\l Column items are used to vertically arrange items. The following example
+uses a Column item to arrange three \l Rectangle items in an area defined
+by an outer \l Item. The \l{Column::spacing}{spacing} property is set to
+include a small amount of space between the rectangles.
+
+\div {class="float-right"}
+\inlineimage qml-column.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/column.qml document
+
+In the above example, each of the rounded rectangles are positioned by the
+\l Column item. The column only changes the vertical positions of its
+child items and does not restrict their horizontal positions. However,
+the restrictions on the use of anchors do not apply to the children of
+these child items, so each \l Text item uses its \c centerIn anchor to
+horizontally and vertically align itself within its parent rectangle.
+
+The width of the column is dependent on the widths of the individual child
+items and, unless specified using the \c width property or with anchors,
+it will only be as wide as the widest child item.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-column-anchors.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/column-anchors.qml document
+
+The example above stretches the column horizontally to fill the entire
+user interface, and stretches each rectangle inside to fill the column.
+The text items behave as they did in the previous example.
+
+\section3 Grid
+
+\l Grid items are used to place items in a grid or table arrangement.
+The following example uses a Grid item to place four \l Rectangle items
+in a 2-by-2 grid. As with the other positioners, the spacing between items
+can be specified using the \l{Grid::spacing}{spacing} property.
+
+\div {class="float-right"}
+\inlineimage qml-grid-spacing.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/grid-spacing.qml document
+
+There is no difference between horizontal and vertical spacing inserted
+between items, so any additional space must be added within the items
+themselves. Any empty cells in the grid must be created by defining
+placeholder items at the appropriate places in the grid definition.
+
+As with the \l Row and \l Column items, \l Grid items restrict the anchors
+used by their child items. Since they position items both horizontally
+and vertically, it is not possible to use any of the anchors to align
+items within the grid. However, we can use placeholder items as the grid's
+child items and put visible items inside those, using anchors to align
+them.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-grid-positioning.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/grid-positioning.qml document start
+\snippet examples/declarative/tutorials/qmlintro/grid-positioning.qml document end
+
+We only show the first item, but the principle is the same for the others.
+
+\section3 Flow
+
+\l Flow items are used to place items like words on a page, with rows or
+columns of non-overlapping items.
+
+Flow items arrange items in a similar way to \l Grid items, with items
+arranged in lines along one axis (the minor axis), and lines of items
+placed next to each other along another axis (the major axis). The
+direction of flow, as well as the spacing between items, are controlled
+by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties.
+
+The following example shows a Flow item containing a number of \l Text
+child items. These are arranged in a similar way to those shown in the
+screenshots.
+
+\div {class="float-right"}
+\inlineimage qml-flow-text1.png
+\br
+\inlineimage qml-flow-text2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/flow.qml document
+
+The main differences between the \l Grid and \l Flow positioners are that
+items inside a \l Flow will wrap when they run out of space on the minor
+axis, and items on one line may not be aligned with items on another line
+if the items do not have uniform sizes. As with grid items, there is no
+independent control of spacing between items and between lines of items.
+
+\section2 Nesting Positioner Items
+
+Since each positioner is based on \l Item, we can nest them like other
+items, placing one positioner inside another. The following example shows a
+\l Column that contains two \l Row positioners.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-nested-positioners.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/nested-positioners.qml column
+
+The example works around the restrictions on the use of anchors mentioned
+earlier by using appropriate anchors for each item. The innermost items,
+\l Text and \l Rectangle, use anchors for vertical positioning within
+\l Row items, which each perform horizontal positioning of their child
+items.
+
+The rows use anchors to position themselves within the \l Column item, which
+arranges them vertically. The column is centered horizontally and vertically
+within its parent, a non-positioning item.
+
+\section2 Strategies for Use
+
+Positioners are intended to be used in situations where it would be
+tedious to apply anchors to a number of items. For this reason, they are
+also used to position dynamically created items, such as those generated
+by \l Repeater items.
+
+The items used with positioners must have a well-defined size, otherwise
+positioners will not be able to determine where they should be placed,
+leaving their positions undefined. When using a \l Column, it is sufficient
+to give each child item a fixed height; the width can be defined using
+anchors. Similarly, with a \l Row, the width of each item should be
+fixed, but the height can be defined using anchors. Items used with \l Grid
+and \l Flow positioners should have fixed widths and heights.
+*/
+
+/*!
+\page qml-user-interaction.html
+\contentspage Introduction to the QML Language
+\previouspage Composing User Interfaces with QML
+\nextpage Generating Items with Repeaters
+\title User Interaction with QML
+\brief Making items respond to user input.
+
+\tableofcontents
+
+So far, we have shown how to declare items and arrange them to create a user
+interface. If we play a QML file using the \l{QML Viewer}, we can resize the
+display window and see the items adapt to the change, but the items
+themselves do not respond to user input from the keyboard or mouse.
+
+Unlike standard Qt widgets, items do not include intrinsic support for user
+interaction. The features required for interactivity are added or applied to
+items.
+
+QML provides the \l MouseArea item to handle mouse input and \l Keys and
+\l KeyNavigation attached properties to handle keyboard input. These are
+used with other items to make them responsive to user input.
+
+\section1 Mouse Areas
+
+To make items responsive to mouse clicks, we add \l MouseArea items to the
+user interface, typically as children of the items we want to make
+interactive. Since \l MouseArea is based on \l Item, it has a geometry, but
+no visual appearance. The following example defines a mouse area with an
+explicit position and size; the image shown indicates where the mouse area
+is in the user interface, but it will not be visible in the running example.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mousearea-annotated.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mousearea.qml mouse area
+
+The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased} definitions
+are \l{QML Concepts and Syntax#Signal Handlers}{signal handlers} that
+contain JavaScript code that will be executed in response to a signal. In
+this case, when the mouse button is pressed or released, the code will
+change the color of the background. Other signal handlers can be defined
+to handle other user input, such as \l{MouseArea::}{onClicked} and
+\l{MouseArea::}{onDoubleClicked}. Some require additional configuration
+of the item before they will work as expected, as we shall see later.
+
+\note It is more common to define mouse areas within items and position them
+with anchors, as shown by the rest of the examples in this chapter.
+
+\section2 Handling Mouse Buttons
+
+The following example uses an anchor to fill a \l Text item with a mouse
+area, and defines two signal handlers to response to mouse button input.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-pressed1.png
+\br
+\inlineimage declarative-qmlintro-mouse-pressed2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-signals.qml text item
+
+The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased}
+signal handlers are defined for the mouse area. As a result, when the user
+presses a mouse button when the cursor is over the text, the color changes
+to green; when the button is released, the color changes to black.
+
+Note that the mouse area only responds to the left mouse button by default.
+This is because the default value of the \l{MouseArea::}{acceptedButtons}
+is \l{Qt::LeftButton}{Qt.LeftButton}. To test for other buttons, set this
+property to be the combination of the buttons required (using the OR
+operator), as in the following example.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-pressed-buttons.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-buttons.qml items
+
+The mouse area covers the entire area of the user interface and accepts
+input from both left and right buttons. Each of the rectangles defines its
+color as an expression that depends on the mouse area's
+\l{MouseArea::}{pressedButtons} property, testing whether the relevant
+button is found in the value of this property. When a button is released,
+the value is \c{Qt.NoButton}.
+
+\note The \l{MouseArea::}{pressed} property provides information about
+whether or not a button was pressed in the mouse area, but does not
+provide any more than a boolean value. This can be sufficient in many
+situations.
+
+\section2 Finding the Cursor Position
+
+The \l MouseArea item contains a number of properties and signal handlers
+that provide information about the mouse cursor. For example, the
+\l{MouseArea::}{mouseX} and \l{MouseArea::}{mouseY} properties contain the
+position of the cursor, as shown in the following example.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-pressed-position.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-position.qml text item
+
+When the user presses the mouse button over the text item, the text changes
+to show the coordinates within the mouse area where the press occurred. If
+we need to find the mouse position outside the text item, we should make
+the mouse area a child of the text item's parent and use anchors to fill
+that item instead.
+
+\section2 Mouse Hover
+
+In the previous examples, the text item and rectangles were updated only
+when the mouse button was pressed. Consider a situation where we would like
+to continuously update the text item with the mouse's position. In such a
+case, we could try the following:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-pressed-position2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-position2.qml text item
+
+When we run this example, the text item shows the initial, default value of
+the mouse area's \c mouseX and \c mouseY properties. Moving the cursor over
+the text has no effect. It is only when the text item is clicked that the
+text is updated.
+
+The reason for this is that, by default, the mouse area only updates various
+properties when a button is pressed. To receive continuous updates about the
+mouse cursor, we need to enable \e{mouse hover} by setting its
+\l{MouseArea::}{hoverEnabled} property, as shown in the following example:
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-hover-enabled.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-hover-enabled.qml text item
+
+With mouse hover enabled, other properties of the \l MouseArea can be
+monitored. For example, the \l{MouseArea::}{containsMouse} property can be
+used to determine whether the mouse cursor is over the mouse area.
+Previously, we only knew when this was the case because the user had to
+press a mouse button over the area.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-hover-containsmouse1.png
+\br
+\inlineimage declarative-qmlintro-mouse-hover-containsmouse2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-hover-containsmouse.qml items
+
+The above example uses \l{QML Concepts and Syntax#Expressions}{an expression}
+to show the coordinates of the mouse cursor when it is in the mouse area,
+\c area. When \c{area.containsMouse} evaluates to \c false, the \c{-}
+character is shown instead.
+
+Certain signal handlers only become useful when mouse hover is enabled.
+For example, the \l{MouseArea::}{onEntered}, \l{MouseArea::}{onExited}
+and \l{MouseArea::}{onPositionChanged} signal handlers will be called
+when the cursor enters, exits or changes position in the area.
+
+\section2 Dragging Items
+
+As well as handling the low level interaction details, the \l MouseArea item
+also handles drag operations if the relevant properties are set. The
+following example shows how dragging is enabled for an item.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-mouse-drag.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/mouse-drag.qml draggable item
+
+The item to be dragged is the \l Rectangle containing a \l MouseArea and
+\l Text items. All that is required is to set the value of the
+\l{MouseArea::}{drag.target} grouped property to the item we wish to enable
+dragging for; in this case, the \c parent of the mouse area. When run, the
+rectangle containing the text can be dragged around its parent's area.
+
+The other \c drag grouped properties allow the dragging behavior of the
+item to be restricted and fine-tuned. \l{MouseArea::}{drag.axis} can be
+set to only allow dragging to occur along the x or y axes, and the range
+of positions to which the target item can be dragged can be limited to
+a range specified by the \l{MouseArea::}{drag.minimumX},
+\l{MouseArea::}{drag.minimumY}, \l{MouseArea::}{drag.maximumX} and
+\l{MouseArea::}{drag.maximumY} properties.
+
+\section2 Strategies for Use
+
+Mouse areas are applied to a user interface by using anchors to fill the
+items that need to respond to user input. This makes them responsive to
+button presses by default, and to mouse movement when the
+\l{MouseArea::}{hoverEnabled} property is set to \c true. When a mouse
+area is not needed to provide input, its \l{MouseArea::}{enabled}
+property can be set to \c false, so that it ignores user input.
+
+When mouse buttons are pressed and released, the
+\l{MouseArea::}{pressedButtons} property is updated as expected. However,
+when multiple buttons are used, as in the
+\l{#Handling Mouse Buttons}{example above}, the most up-to-date values
+reported by this property are not necessarily propagated to the items
+that use it. For this reason, it can be better to consider using signal
+handlers to respond to mouse button presses and releases.
+
+
+\section1 Key Handling
+
+Another important method of user input is via the keyboard. In addition to
+the \l TextInput and \l TextEdit items, which accept keyboard input for
+display purposes, QML provides facilities to allow items to capture key
+presses, as well as higher level features for navigation using keys.
+
+Unlike mouse input, which uses the \l MouseArea item, key input uses two
+attached properties to handle keyboard input: \l Keys and \l KeyNavigation.
+These look like ordinary elements, but can be applied to any item in order
+to enable keyboard input support.
+
+\section2 Key Navigation
+
+In desktop user interfaces, it is usually helpful to provide a way for the
+user to navigate between input fields or other interactive items by pressing
+navigation keys, typically the cursor keys or the \key Tab key. The
+\l KeyNavigation attached property is used to define the relationships
+between items to allow this kind of navigation.
+
+The following example shows two \l Rectangle items placed in a \l Row
+positioner. These are defined with identifiers, \c{leftRect} and
+\c{rightRect}.
+
+\div {class="float-right"}
+\inlineimage declarative-qmlintro-key-navigation1.png
+\br
+\inlineimage declarative-qmlintro-key-navigation2.png
+\enddiv
+\snippet examples/declarative/tutorials/qmlintro/key-navigation.qml items
+
+The \c{leftRect} rectangle attaches the
+\l{KeyNavigation::right}{KeyNavigation.right} property, setting it to refer
+to the \c{rightRect} rectangle. The \c{rightRect} rectangle attaches the
+\l{KeyNavigation::left}{KeyNavigation.left} property, referring to the
+\c{leftRect} rectangle.
+
+Initially, the \c{leftRect} rectangle has the keyboard focus, since its
+\l{Item::}{focus} property is set to \c true. When the user presses the
+right cursor key, the focus is passed to the \c{rightRect} rectangle instead,
+as defined by the \l KeyNavigation attached property for that item. Pressing
+the left cursor key causes the focus to be passed back to \c{leftRect}
+because as defined by the \l KeyNavigation attached property for
+\c{rightRect}.
+
+*/
+
+/*!
+\page qml-positioning-items.html
+\contentspage Introduction to the QML Language
+\previouspage Composing User Interfaces with QML
+\nextpage QML Tutorial
+\title Generating Items with Repeaters
+\brief How to generate and position items dynamically.
+
+\tableofcontents
+
+\section1 Repeaters
+
+\div {class="float-right"}
+\inlineimage qml-repeater-grid-index.png
+\enddiv
+
+Repeaters create items from a template for use with positioners, using data
+from a model. Combining repeaters and positioners is an easy way to lay out
+lots of items. A \l Repeater item is placed inside a positioner, and generates
+items that the enclosing positioner arranges.
+
+Each Repeater creates a number of items by combining each element of data
+from a model, specified using the \l{Repeater::model}{model} property, with
+the template item, defined as a child item within the Repeater.
+The total number of items is determined by the amount of data in the model.
+
+The following example shows a repeater used with a \l{#Grid}{Grid} item to
+arrange a set of Rectangle items. The Repeater item creates a series of 24
+rectangles for the Grid item to position in a 5 by 5 arrangement.
+
+\snippet doc/snippets/qml/repeaters/repeater-grid-index.qml document
+
+The number of items created by a Repeater is held by its \l{Repeater::}{count}
+property. It is not possible to set this property to determine the number of
+items to be created. Instead, as in the above example, we use an integer as
+the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models}
+document.
+
+It is also possible to use a delegate as the template for the items created
+by a Repeater. This is specified using the \l{Repeater::}{delegate} property.
+
+\section1 Using Transitions
+
+Transitions can be used to animate items that are added to, moved within,
+or removed from a positioner.
+
+Transitions for adding items apply to items that are created as part of a
+positioner, as well as those that are reparented to become children of a
+positioner.
+Transitions for removing items apply to items within a positioner that are
+deleted, as well as those that are removed from a positioner and given new
+parents in a document.
+
+Additionally, changing the opacity of items to zero will cause them to
+disappear using the remove transition, and making the opacity non-zero will
+cause them to appear using the add transition.
+
+\section1 Other Ways to Position Items
+
+There are several other ways to position items in a user interface. In addition
+to the basic technique of specifying their coordinates directly, they can be
+positioned relative to other items with \l{anchor-layout}{anchors}, or used
+with \l{QML Data Models} such as
+\l{QML Data Models#VisualItemModel}{VisualItemModel}.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-texthandling.html
+\title Text Handling and Validators
+\brief elements that accept and handle text input
+
+\tableofcontents
+
+\section1 Text Elements
+
+\list
+\li \l{Text}
+\li \l{TextInput}
+\li \l{TextEdit}
+\endlist
+
+\section1 Validators
+\list
+\li \l{IntValidator}
+\li \l{DoubleValidator}
+\li \l{RegExpValidator}
+\endlist
+
+\section1 Displaying Text in QML
+QML provides several elements to display text onto the screen. The \l Text
+element will display formatted text onto the screen, the \l TextEdit element
+will place a multiline line edit onto the screen, and the \l TextInput will
+place a single editable line field onto the screen.
+
+To learn more about their specific features and properties, visit their
+respective element documentation.
+
+\section1 Validating Input Text
+The \l {Validators}{validator} elements enforce the type and format of
+\l TextInput objects.
+
+\snippet doc/snippets/qml/texthandling.qml int validator
+The validator elements bind to \c {TextInput}'s \c validator property.
+
+\snippet doc/snippets/qml/texthandling.qml regexp validator
+The regular expression in the snippet will only allow the inputted text to be
+\c {fruit basket}.
+
+Note that QML parses JavaScript regular expressions, while Qt's
+\l {QRegExp} class' regular expressions are based on Perl regular expressions.
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\title Qt Quick
+\page qtquick-reference.html
+\inqmlmodule QtQuick 2
+\ingroup qt-gui-concepts
+\ingroup overviews
+
+\brief Qt Quick provides a declarative framework for building highly
+dynamic applications.
+
+For App Developers and Designers, who want to deliver apps with amazing user
+experience, Qt provides the QML language, the Qt Quick Elements, and tools in Qt
+Creator that make it faster than ever to transform your brilliant idea into a
+winning App across mobile, embedded, and desktop platforms.
+
+\target qtquick-overviews
+\div {class="threecolumn_area"}
+ \div {class="heading"}
+ QML Topics
+ \enddiv
+ QML is a declarative language for creating flexible and reusable
+ components. The QML runtime powers QML based applications. The runtime
+ includes a QML engine, JavaScript engine, and mechanism to bind to the Qt
+ Framework.
+
+ \div {class=" threecolumn_piece"}
+ \div {class="heading"}
+ QML Essentials
+ \enddiv
+ \list
+ \li \l{QML Components}{Components}
+ \li \l{Properties and Property Binding in QML}{Properties and Property Binding}
+ \li \l{JavaScript Expressions in QML}{JavaScript Code}
+ \li \l{QML Signal and Handler Event System}{Signal and Handler Event System}
+ \li \l{QML Modules}{Modules}
+ \endlist
+ \list
+ \li \l{What's New in Qt Quick 2}{What's New in Qt Quick}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ QML Engine
+ \enddiv
+ \list
+ \li \l{The QML Engine}
+ \li \l{QML Global Object}
+ \li \l{Dynamic Object Management in QML}{Dynamic Object Management}
+ \li \l{QML Performance}{Performance}
+ \endlist
+ \enddiv
+ \div {class=" threecolumn_piece"}
+ \div {class="heading"}
+ Reference
+ \enddiv
+ \list
+ \li \l{QML Syntax}
+ \li \l{QML Basic Types}{Data Types}
+ \li \l{QML Coding Conventions}{Coding Conventions}
+ \li \l{QML Security}{Security Model}
+ \li \l{QML Scope}{Scope Model}
+ \li \l{QML Documents}{Documents}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ QML Bindings with Qt C++
+ \enddiv
+ \list
+ \li \l{Creating QML Types}
+ \li \l{QML Plugins}
+ \li \l{Exposing C++ Models}
+ \li \l{Integrating QML Code with Existing Qt UI Code}{Qt Gui Porting Information}
+ \endlist
+ \enddiv
+ \div {class=" threecolumn_piece"}
+ \div {class="heading"}
+ Tools
+ \enddiv
+ \list
+ \li \l{QML Internationalization}{Internationalization}
+ \li \l{QtQuickTest Reference Documentation}
+ \li \l{Debugging QML}
+ \endlist
+ \enddiv
+\enddiv
+\div {class="threecolumn_area"}
+ \div {class="heading"}
+ Qt Quick Elements
+ \enddiv
+ Qt Quick Elements features graphical elements, user input system,
+ animation system, and data visualization through models and delegates.
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ Graphics and Special Effects
+ \enddiv
+ \list
+ \li \l{Basic Elements}{Basic Elements}
+ \li \l{Painting with Canvas API}
+ \li \l{Using the Qt Quick Particle System}{Particle Effects}
+ \li \l{Shader Effects in QML}{Shader Effects}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ Anchoring and Layouts
+ \enddiv
+ \list
+ \li \l{Item Layouts}
+ \li \l{Layouts with Anchors}
+ \li \l{Right-to-left User Interfaces}{Right-to-left User Interfaces}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ Mouse and Keyboard Input
+ \enddiv
+ \list
+ \li \l{Mouse Events}{Mouse Events}
+ \li \l{Text Handling and Validators}{Text Handling and Validators}
+ \li \l{Keyboard Focus in QML}{Keyboard Focus}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ States and Transitions
+ \enddiv
+ \list
+ \li \l{States}
+ \li \l{Animation and Transitions}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ Data with Models and Views
+ \enddiv
+ \list
+ \li \l{Models and Views}
+ \endlist
+ \enddiv
+ \div {class="threecolumn_piece"}
+ \div {class="heading"}
+ Data Storage and Resources
+ \enddiv
+ \list
+ \li \l{Local Storage}{SQL Local Storage}
+ \endlist
+ \enddiv
+\enddiv
+
+*/
+
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-intro.html
+\title Introduction to Qt Quick
+
+Qt Quick is a collection of technologies that are designed to help developers
+create the kind of intuitive, modern, and fluid user interfaces that are
+increasingly used on mobile phones, media players, set-top boxes, and other
+portable devices. Qt Quick consists of a rich set of user interface
+\l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for
+describing user interfaces, and a language \l{QtQml Module}{runtime}. A
+collection of C++ APIs is used to integrate these high level features with
+classic Qt applications. Version 2.1 of the Qt Creator integrated development
+environment (IDE) introduces tools for developing Qt Quick applications.
+
+\image qml-clocks-example.png
+
+\section1 The QML Language
+
+QML is a high level language that uses a declarative syntax to define how the
+user interface should appear and behave. QML is used to build interfaces using
+a collection of standard elements for fundamental user interface features.
+These elements expose properties that can be changed at run-time, allowing
+visual elements to be animated and used in transitions between states of the
+user interfaces.
+
+\div{class="float-left"}
+\inlineimage qml-dialcontrol-example.png
+\enddiv
+A Dial element might define a \e value property that can be used to control
+the position of the needle on the dial. The element could be declared to
+use a slider that adjusts the value of this property.
+
+\snippet examples/declarative/ui-components/dialcontrol/qml/dialcontrol.qml the dial in use
+
+Building user interfaces by importing these elements and linking their properties
+together is one of the fundamental features of QML and Qt Quick.
+
+\clearfloat
+Behind the scenes, QML leverages the power and efficiency of the Qt libraries
+to provide rendering facilities, perform processor-intensive operations, and
+to access components written in C++.
+
+The QML language also gives the developer more flexibility to create parts
+of their user interface by allowing \l{About JavaScript}{JavaScript} to be
+used to implement high level user interface logic.
+
+\l{How to Learn QML} introduces the reader to the language and declarative
+concepts.
+
+\section1 QtQml Module
+
+To make Qt Quick possible, Qt introduces the \l{QtQml} module. The
+module creates a JavaScript runtime that QML runs under with a Qt based backend.
+Because QtQml and QML are built upon Qt, they inherit many of Qt's
+technology, namely the \l{Signals and Slots}{signals and slots} mechanism and
+the \l{The Meta-Object System}{meta-object} system. Data created using C++ are
+directly accessible from QML, and QML objects are also accessible from C++ code.
+
+The QtQml module separates the interface logic in QML from the
+application logic in C++. It also allows the range of standard QML elements
+to be \l{Extending QML with C++}{extended with new ones written in C++}.
+
+\section1 Qt Creator Tools
+
+Qt Creator is a complete integrated development environment (IDE) for creating
+applications with Qt Quick and the Qt application framework.
+
+\image qmldesigner-visual-editor.png
+
+The main goal for Qt Creator is meeting the development needs of Qt Quick
+developers who are looking for simplicity, usability, productivity,
+extendibility and openness, while aiming to lower the barrier of entry for
+newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers
+and developers to accomplish the following tasks:
+\list
+\li Get started with Qt Quick application development quickly and easily with
+examples, tutorials, and project wizards.
+\li Design application user interface with the integrated editor, Qt Quick
+Designer, or use graphics software to design the user interface and use scripts
+to export the design to Qt Quick Designer.
+\li Develop applications with the advanced code editor that provides new powerful
+features for completing code snippets, refactoring code, and viewing the element
+hierarchy of QML files.
+\li Build and deploy Qt Quick applications that target multiple desktop and
+mobile platforms, such as Microsoft Windows, Mac OS X, Linux, and Maemo.
+\li Debug JavaScript functions and execute JavaScript expressions in the current
+context, and inspect QML at runtime to explore the object structure, debug
+animations, and inspect colors.
+\li Deploy applications to mobile devices and create application installation
+packages for Maemo devices that can be published in the Ovi Store
+and other channels.
+\li Easily access information with the integrated context-sensitive Qt Help
+system.
+\endlist
+
+\image qtcreator-target-selector.png
+
+\section1 Where to Go from Here
+
+\l{external: Developing Qt Quick Applications with Creator}
+{Developing Qt Quick Applications with Creator} provides an overview
+of user interface development using the visual \e{Qt Quick Designer} tool.
+
+\l{How to Learn QML} introduces the reader to the language and declarative
+concepts.
+
+The \l{QML Reference} page has links to various Qt Quick topics such as QML
+features, addons, and tools.
+
+The \l {Qt Quick Code Samples} page has a gallery of QML applications.
+
+\section1 License Information
+\list
+\li \l{Qt Quick Licensing Information}
+\endlist
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+ \module QtQuick
+ \title Qt Quick Module
+ \ingroup modules
+
+ \brief The Qt Quick module provides classes for embedding Qt Quick
+ in Qt/C++ applications.
+
+ To include the definitions of the module's classes, use the
+ following directive:
+
+ \code
+ #include <QtQuick>
+ \endcode
+
+ To link against the module, add this line to your \l qmake \c
+ .pro file:
+
+ \code
+ QT += quick
+ \endcode
+
+ For more information on the Qt Quick module, see the
+ \l{Qt Quick} documentation.
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+ \qmlmodule QtQuick 2
+ \title QML Module QtQuick 2
+
+ \brief The QML Elements
+
+ This QML module contains all the QML elements that are
+ instantiated as objects of C++ classes in the QtQml
+ module. These elements work with the Scenegraph renderer and
+ their own canvas.
+ */
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-righttoleft.html
+\ingroup qml-features
+\title Right-to-left User Interfaces
+\brief switching text flow and layout
+\section1 Overview
+
+This chapter discusses different approaches and options available for implementing right-to-left
+language support for Qt Quick applications. Some common right-to-left languages include Arabic, Hebrew,
+Persian and Urdu. Most changes include making sure that text translated to right-to-left languages
+is properly aligned to the right, and horizontally ordered content in views, lists and grids flows
+correctly from the right to left.
+
+In right-to-left language speaking cultures, people naturally scan and read graphic elements and text
+from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not
+mirrored, but positioning of the content (like application layouts and the flow of visual elements) is
+mirrored. For example, photos shown in chronological order should flow from right to left, the
+low end range of the horizontal sliders should be located at the right side of the slider, and
+text lines should should be aligned to the right side of the available text area. The location of visual
+elements should not be mirrored when the position is related to a content; for example, when a
+position marker is shown to indicate a location on a map. Also, there are some special cases you may
+need to take into account where right-to-left language speakers are used to left-to-right
+positioning, for example when using number dialers in phones and media play, pause, rewind and
+forward buttons in music players.
+
+\section1 Text Alignment
+
+(This applies to the \l Text, \l TextInput and \l TextEdit elements.)
+
+When the horizontal alignment of a text item is not explicitly set, the text element is
+automatically aligned to the natural reading direction of the text. By default left-to-right text
+like English is aligned to the left side of the text area, and right-to-left text like Arabic is
+aligned to the right side of the text area. The alignment of a text element with empty text takes
+its alignment cue from \l QInputMethod::inputDirection(), which is based on the active
+system locale.
+
+This default locale-based alignment can be overridden by setting the \c horizontalAlignment
+property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached
+property, which causes any explicit left and right horizontal alignments to be mirrored.
+Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged;
+the effective alignment of the text element that takes the mirroring into account can be read from the
+\c effectiveHorizontalAlignment property.
+
+\snippet doc/snippets/qml/righttoleft.qml 0
+
+\section1 Layout direction of positioners and views
+
+(This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView elements.)
+
+From Qt Quick 1.1 onwards, elements used for horizontal positioning and model views have gained a \c layoutDirection
+property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to
+\c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows
+the left-to-right layout direction.
+
+The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property.
+This causes the effective \c layoutDirection of positioners and views to be mirrored. Note the actual value
+of the \c layoutDirection property will remain unchanged; the effective layout direction of positioners and
+views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property.
+
+\snippet doc/snippets/qml/righttoleft.qml 1
+
+\section1 Layout mirroring
+
+The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
+support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout}
+{Item anchors}, the layout direction of \l{Composing User Interfaces with QML#Positioners}{positioners} and
+\l{Models and Views}{model views}, and the explicit text alignment of QML text elements.
+
+You can enable layout mirroring for a particular \l Item:
+
+\snippet doc/snippets/qml/righttoleft.qml 2
+
+Or set all child elements to also inherit the layout direction:
+
+\snippet doc/snippets/qml/righttoleft.qml 3
+
+Applying mirroring in this manner does not change the actual value of the relevant anchor,
+\c layoutDirection or \c horizontalAlignment properties. The separate read-only property
+\c effectiveLayoutDirection can be used to query the effective layout
+direction of positioners and model views that takes the mirroring into account. Similarly the \l Text,
+\l TextInput and \l TextEdit elements have gained the read-only property \c effectiveHorizontalAlignment
+for querying the effective visual alignment of text. For anchors, the read only
+\l {Item::anchors.top}{anchors.mirrored} property reflects whether anchors have been mirrored.
+
+Note that application layouts and animations that are defined using \l {Item::}{x} property values (as
+opposed to anchors or positioner elements) are not affected by the \l LayoutMirroring attached property.
+Therefore, adding right-to-left support to these types of layouts may require some code changes to your application,
+especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use
+the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x}
+coordinates:
+
+\snippet doc/snippets/qml/righttoleft.qml 4
+
+Not all layouts should necessarily be mirrored. There are cases where a visual element is positioned to
+the right side of the screen for improved one-handed use, because most people are right-handed, and not
+because of the reading direction. In the case that a child element should not be affected by mirroring,
+set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that element to false.
+
+Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that
+the animations and transitions continue to work as expected. If you do not have the resources to add
+right-to-left support for your application, it may be better to just keep the application layouts left
+aligned and just make sure that text is translated and aligned properly.
+
+\section1 Mirroring icons
+
+(This applies to \l Image, \l BorderImage and \l AnimatedImage elements.)
+
+Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored.
+The painting of these icons can be mirrored with a dedicated \c mirror property introduced in Qt Quick 1.1:
+
+\snippet doc/snippets/qml/righttoleft.qml 5
+
+\section1 Default layout direction
+
+The \l {QML:Qt::application}{Qt.application.layoutDirection} property can be used to query the active layout direction of the
+application. It is based on QApplication::layoutDirection(), which most commonly determines the layout
+direction from the active language translation file.
+
+To define the layout direction for a particular locale, declare the dedicated string literal
+\c QT_LAYOUT_DIRECTION in context \c QApplication as either "LTR" or "RTL".
+
+You can do this by first introducing this line
+
+\code
+QT_TRANSLATE_NOOP("QApplication", "QT_LAYOUT_DIRECTION");
+\endcode
+
+somewhere in your QML source code and calling \c lupdate to generate the translation source file.
+
+\code
+lupdate myapp.qml -ts myapp.ts
+\endcode
+
+This will append the following declaration to the translation file, where you can fill in either "LTR" or
+"RTL" as the translation for the locale.
+
+\code
+<context>
+ <name>QApplication</name>
+ <message>
+ <location filename="myapp.qml" line="33"/>
+ <source>QT_LAYOUT_DIRECTION</source>
+ <translation type="unfinished">RTL</translation>
+ </message>
+</context>
+\endcode
+
+You can test that the layout direction works as expected by running your Qt Quick application with
+the compiled translation file:
+
+\code
+qmlviewer myapp.qml -translation myapp.qm
+\endcode
+
+You can test your application in right-to-left layout direction simply by executing qmlviewer with a
+command-line parameter "-reverse":
+
+\code
+qmlviewer myapp.qml -reverse
+\endcode
+
+The layout direction can also be set from C++ by calling the static function \l QApplication::setLayoutDirection():
+
+\code
+QApplication app(argc, argv);
+app.setLayoutDirection(Qt::RightToLeft);
+\endcode
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-shaders.html
+\title Shader Effects in QML
+\brief applying OpenGL vertex and fragment shaders to QML Rectangles
+
+\code
+NOTE: This article is a work in progress.
+\endcode
+
+\section1 Shaders
+Describe Shaders and where it could be used in UIs or applications
+Mention OpenGL shader language (GLSL)
+
+\section1 ShaderEffect Element
+Introduce the \l{QtQuick2::ShaderEffect} Element.
+Say what is possible and how to load shaders
+
+\section1 Shader Overview
+Go over shaders in more detail and what shaders actually do.
+
+\section2 Vertex Shader
+Go over vertex shaders
+
+\section2 Fragment Shader
+Go over fragment shaders
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-states.html
+\title States
+\brief Creating and setting states
+
+\target qmlstates
+\section1 States Elements
+\list
+\li \l State
+\li \l PropertyChanges
+\li \l StateGroup
+\li \l StateChangeScript
+\li \l ParentChange
+\li \l AnchorChanges
+\endlist
+
+Many user interface designs are \e state driven; interfaces have configurations
+that differ depending on the current state. For example, a traffic signal will
+configure its flags or lights depending on its state. While in the signal's
+\c stop state, a red light will turn on while the yellow and the green lights
+will turn off. In the \c caution state, the yellow light is on while the other
+lights are turned off.
+
+In QML, \e states are a set of property configurations defined in a \l State
+element. Different configurations could, for example:
+
+\list
+\li Show some UI elements and hide others
+\li Present different available actions to the user
+\li Start, stop, or pause animations
+\li Execute some script required in the new state
+\li Change a property value for a particular item
+\li Show a different view or screen
+\endlist
+
+All \l {Item}-based objects have a \c state property, and can specify additional
+states by adding new \c State objects to the item's \l {Item::}{states}
+property. Each state within a component has a unique \c name, an empty string
+being the default. To change the current state
+of an item, set the \l {Item::}{state} property to the name of the state.
+
+Non-Item objects may use states through the \l StateGroup element.
+
+\section1 Creating States
+
+To create a state, add a \l State object to the item's \l {Item::}{states} property,
+which holds a list of states for that item.
+
+A warning \c signal component may have two states, the \c NORMAL and the
+\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the
+signal should be \c green and the warning \c flag is down. Meanwhile, in the
+\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may
+model the states using the \c State element and the color and flag
+configurations with the \c PropertyChanges element.
+\snippet doc/snippets/qml/states.qml signal states
+The \l PropertyChanges element will change the values of object properties.
+Objects are referenced through their \l {qml-id}{id}. Objects outside
+the component are also referenced using the \c id property, exemplified by the
+property change to the external \c flag object.
+
+Further, the state may change by assigning the \c state property with the
+appropriate signal state. A state switch could be in a \l MouseArea element,
+assigning a different state whenever the signal receives a mouse click.
+\snippet doc/snippets/qml/states.qml switch states
+
+The State element is not limited to performing modifications on property values.
+It can also:
+\list
+\li Run some script using \l StateChangeScript
+\li Override an existing signal handler for an object using \l PropertyChanges
+\li Re-parent an \l Item using \l ParentChange
+\li Modify anchor values using \l AnchorChanges
+\endlist
+
+\section1 The Default State
+
+Every \l Item based component has a \c state property and a \e{default state}.
+The default state is the empty string (\c{""}) and contains all of an item's
+initial property values. The default state is useful for managing property
+values before state changes. Setting the \c state property to an empty string
+will load the default state.
+
+\section1 The \c when Property
+
+For convenience, the \l State element has a \c when property that can bind to
+expressions to change the state whenever the bound expression evaluates to
+\c true. The \c when property will revert the state back to the
+\l {The Default State}{default state} when the expression evaluates to false.
+
+\snippet doc/snippets/qml/states.qml when property
+The \c bell component will change to the \c RINGING state whenever the
+\c signal.state is \c CRITICAL.
+
+\section1 Animating State Changes
+
+State changes induce abrupt value changes. The \l Transition element allow
+smoother changes during state changes. In transitions, animations and
+interpolation behaviors are definable. The
+\l {QML Animation and Transitions}{Animation and Transitions} article has more
+information about creating state animations.
+
+The \l {declarative/animation/states}{States and Transitions example}
+demonstrates how to declare a basic set of states and apply animated
+transitions between them.
+
+\l{Using QML Behaviors with States} explains a common problem when using Behaviors
+to animate state changes.
+
+\section1 State Fast Forwarding
+
+In order for Transition to correctly animate state changes, it is sometimes necessary
+for the engine to fast forward and rewind a state (that is, internally set and unset the state)
+before it is finally applied. The process is as follows:
+
+\list 1
+\li The state is fast forwarded to determine the complete set of end values.
+\li The state is rewound.
+\li The state is fully applied, with transitions.
+\endlist
+
+In some cases this may cause unintended behavior. For example, a state that changes
+a view's \e model or a Loader's \e sourceComponent will set these properties
+multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
+
+State fast forwarding should be considered an implementation detail,
+and may change in later versions.
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\title What's New in Qt Quick 2
+\page qtquick2-whatsnew.html
+\inqmlmodule QtQuick 2
+
+\section1 Qt 5.0.0 includes QtQuick 2.0
+
+QtQuick 2.0 is a major update.
+
+\section2 SceneGraph renderer
+
+QtQuick 2 is based on an OpenGL scenegraph. The following
+classes replace their equivalents in QtQuick 1:
+
+\list
+\li QQuickView
+\li QQuickCanvas
+\li QQuickItem
+\li QQuickPaintedItem
+\endlist
+
+\section2 QML Engine/Language Improvements
+
+JS engine changed to V8. For most QML users this should not make a visible difference beyond performance improvements, however a lot of undefined behavior semantics may have changed as well. As always, it is recommended not to rely on undefined behavior.
+
+Parser and compiler optimizations.
+
+New binding optimizer.
+
+ValueType improvements:
+ - QColor is now a value type. The red, green, blue and alpha channels can be accessed via "r", "g", "b" and "a" properties
+ - Improved support for QVector4D, now constructible in QML via Qt.vector4d()
+
+Arbitrary functionality may be provided in a namespace through a Module API. See \l{qmlRegisterModuleApi()} for more information.
+
+JavaScript (.js) files may now import QML modules and other JavaScript files. See \l{Importing One JavaScript File From Another} for more information.
+
+A new property type "var" has been added which obsoletes the old "variant" property type.
+Properties of the "var" type may hold JavaScript references. See \l{QML Basic Types} for more information.
+
+QML properties of type \c var and \c variant can now hold pixmaps. See \l{Scarce Resources in JavaScript} for more information
+
+QQmlExpression can now be directly (and more efficiently) constructed from a
+QQmlScriptString.
+
+Support for certain sequence types (QList<int>, QList<qreal>, QList<bool>, QList<QUrl>, QList<QString> and QStringList) has been improved.
+QObjects can define Q_PROPERTYs of these types which can be accessed transparently from JavaScript. See the section on
+sequences in \l{Extending QML Functionalities using C++} for more information.
+
+\section2 Canvas Item
+
+The new \l Canvas item provides a HTML5 canvas like API, with some enhancements:
+1) Supports 2 render targets: Canvas.Image and Canvas.FramebufferObject
+2) Supports background thread rendering
+3) Supports tiled canvas rendering
+
+The Canvas item supports most of the HTML5 context2d APIs, the API details please look at the canvas item documentation.
+
+
+\section2 Particle System
+
+The \l{QtQuick.Particles 2}{QtQuick.Particles} module contains elements that can be composed to form 2D particle system.
+
+
+\section2 Element API/Behavior Changes
+
+New \l SpriteImage element renders animated sprites and can transition between animations.
+It uses the \l Sprite element to represent each animation.
+
+MouseArea now propagates clicked, doubleClicked and pressAndHold differently to pressed.
+These will now be propagated to the highest-stacking-order enabled MouseArea which has a handler for them.
+You can still ignore these events in the handler to let them pass through.
+This behavior is triggered with the new property propagateComposedEvents.
+
+The Binding element can now be used as a value source, and will also restore any previously
+set binding when its \e when clause becomes false.
+
+Flickable: added dragging, draggingHorizontally and draggingVerically properties.
+Added topMargin, bottomMargin, leftMargin, rightMargin, xOrigin, yOrigin properties.
+
+Image has two new properties: horizontalAlignment and verticalAlignment. It also has a new value for
+fillMode (Image.Pad) that does not transform the image.
+Setting Image sourceSize.width and sourceSize.height will now fit the image to the size, maintaining aspect.
+
+Grid now has rowSpacing and columnSpacing properties. Spacing properties on positioners are now real numbers instead
+of integers.
+
+Positioner (Row, Column, Grid, Flow) improvements:
+\list
+\li Transitions used for \c add and \c move now have improved features: they can access a ViewTransition attached property (see the ViewTransition documentation for examples) and can now animate arbitrary item properties (instead of being restricted to animating an item's position).
+\li Items in a positioner now have attached properties that can be used to determine a subitem's location: Positioner.index, Positioner.isFirstItem, Positioner.isLastItem.
+\endlist
+
+Loader improvements:
+ - "active" property added to Loader, to allow delaying instantiation of a Loader element's item property
+ - "setSource(JSObject)" method added to Loader to allow initial property values to be specified (similar to Component.createObject())
+ - now only emits the \c sourceChanged signal when the source is changed and the
+\c sourceComponentChanged signal when the sourceComponent is changed. It used to emit both signals when one of the properties was changed.
+
+Text improvements:
+ - a \c onLineLaidOut handler is called for every line during the layout process. This gives the opportunity to position and resize a line as it is being laid out.
+ - a \c doLayout method was added to trigger the layout from Javascript.
+ - now automatically switch to StyledText instead of RichText if textFormat is set to AutoText.
+
+TextEdit:
+ - the default value of the textFormat property is now PlainText instead of AutoText.
+
+TextInput has new wrapMode and verticalAlignment properties, and the positionAt function now takes
+a y parameter.
+
+PathView now has a \c currentItem property
+
+ListView and GridView:
+ - Can now apply specified transitions whenever items are added, removed or moved in a view.
+ See the documentation for ViewTransition and ListView.add, ListView.addDisplaced,
+ GridView.add, GridView.addDisplaced etc. for details.
+ - These now have headerItem and footerItem properties (the instantiated header and footer items).
+ - In RightToLeft layout the preferredHighlightBegin/End are now also reversed.
+
+ListView section.labelPositioning property added to allow keeping the current section label
+at the start and/or next section label at the end of the view.
+
+A new property type ("var") has been introduced which obsoletes "variant" properties in QML.
+Properties of this type are equivalent to regular JavaScript variables. See the documentation
+on \l{QML Basic Types} for more information about "var" properties.
+
+New elements have been added for contructing paths: PathArc, PathCurve, PathSvg.
+
+\section2 QtQuick 1 is now a separate library and module
+
+Writing C++ applications using QtQuick 1 specific API, i.e. QDeclarativeView or QDeclarativeItem
+requires adding the "quick1" module to the .pro file, e.g. QT += quick1
+
+QDeclarativeView and QDeclarativeItem headers are now in the QtQuick 1 module, i.e.
+#include <QtQuick1/QDeclarativeView>
+#include <QtQuick1/QDeclarativeItem>
+
+\sa {What's New in Qt Quick 1}{What's New in Qt Quick 1}
+
+*/
--- /dev/null
+/****************************************************************************
+**
+** 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 qtquick-writecomponents.html
+\title Writing QML Components
+\brief creating and initializing QML components
+
+\code
+NOTE: This article is a work in progress.
+\endcode
+
+One of the key concepts in QML is the ability to define your own QML components that suit
+the purposes of your application. The standard \l {QML Elements} provide the essential components
+for creating a QML application; beyond these, you can write your own custom components that can
+be created and reused, without the use of C++.
+
+Components are the building blocks of a QML project. When writing a QML application, whether
+large or small, it is best to separate QML code into smaller components that perform specific
+sets of operations, instead of creating mammoth QML files with large, combined functionality
+that is more difficult to manage and may contain duplicated code.
+
+
+\section1 Defining New Components
+
+A component is a reusable type with a well-defined interface, built entirely in QML.
+Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where
+<Name> is the new component name, beginning with an uppercase letter. These QML files automatically
+become available as new QML element types to other QML components and applications in the same directory.
+
+For example, one of the simplest and most common components you can build in QML is a
+button-type component. Below, we implement this component as a \l Rectangle with a clickable
+\l MouseArea, in a file named \c Button.qml:
+
+\snippet doc/snippets/qml/qml-extending-types/components/Button.qml 0
+
+Now this component can be reused by another file within the same directory. Since the file is
+named \c Button.qml, the component is referred to as \c Button:
+
+\table
+\row
+\li \snippet doc/snippets/qml/qml-extending-types/components/application.qml 0
+\li \image qml-extending-types.png
+\endtable
+
+The root object in \c Button.qml defines the attributes that are available to users of the
+\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods
+and signals of \l Rectangle are made available, allowing \c application.qml to
+customize the \c width, \c height, \c radius and \c color properties of \c Button objects.
+
+
+If \c Button.qml was not in the same directory, \c application.qml would need to load it as a
+\l {Modules}{module} from a specific filesystem path or \l{QQmlExtensionPlugin}{plugin}.
+Also, note the letter case of the component file name is significant on some (notably UNIX)
+filesystems. It is recommended the file name case matches the case of the QML component name
+exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the
+QML component will be deployed.
+
+To write a useful component, it is generally necessary to provide it with custom attributes that store and
+communicate specific data. This is achieved by adding the following attributes to your components:
+
+\list
+\li \b Properties that can be accessed externally to modify an object (for example, \l Item has
+ \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding}
+\li \b Methods of JavaScript code can be invoked internally or externally (for example,
+ \l Animation has a \l {Animation::}{start()} method)
+\li \b Signals to notify other objects when an event has occurred (for example, MouseArea has a
+ \c clicked signal)
+\endlist
+
+The following sections show how these attributes can be added to QML components.
+
+
+\section1 Adding Properties
+
+A property is a value of a QML component that can be read and modified by other objects. For
+example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l
+{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where
+a property value is automatically updated using the value of another property.
+
+The syntax for defining a new property is:
+
+\code
+[default] property <type> <name>[: defaultValue]
+\endcode
+
+A \c property declaration can appear anywhere within a QML component definition, but it is customary
+to place it at the top. A component cannot declare more than one property with the same name. (It is
+possible to have a property name that is the same as an existing property in a type, but this is not
+recommended as the existing property becomes hidden and inaccessible.)
+
+Below is an example. The \c ImageViewer component has defined a \c string type property named
+\c currentImage, and its initial value is "default-image.png". This property is used to set the image
+displayed in the child \l Image object. Another file, \c application.qml, can create
+an \c ImageViewer object and read or modify the \c currentImage value:
+
+\table
+\row
+\li \snippet doc/snippets/qml/qml-extending-types/properties/ImageViewer.qml 0
+\li \snippet doc/snippets/qml/qml-extending-types/properties/application.qml 0
+\endtable
+
+It is optional for a property to have a default value. The default value is a convenient shortcut, and is
+behaviorally identical to doing it in two steps, like this:
+
+\qml
+// Use default value
+property int myProperty: 10
+
+// Longer, but behaviorally identical
+property int myProperty
+myProperty: 10
+\endqml
+
+
+\section2 Supported property types
+
+All QML properties are typed. The examples above show properties with \c int and \c string types;
+notice that the type of the property must be declared. The type is used to determine the property
+behavior, and how the property is defined in C++.
+
+A number of property types are supported by default. These are listed in the table below,
+with their default values and the corresponding C++ type:
+
+\table
+\header \li QML Type Name \li Default value \li C++ Type Name
+\row \li \l int \li 0 \li int
+\row \li \l bool \li \c false \li bool
+\row \li \l double \li 0.0 \li double
+\row \li \l real \li 0.0 \li double
+\row \li \l string \li "" (empty string) \li QString
+\row \li \l url \li "" (empty url) \li QUrl
+\row \li \l color \li #000000 (black) \li QColor
+\row \li \l date \li \c undefined \li QDateTime
+\row \li \l variant \li \c undefined \li QVariant
+\endtable
+
+QML object types can also be used as property types. This includes
+\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are
+defined like this:
+
+\qml
+property Item itemProperty
+property QtObject objectProperty
+property MyCustomType customProperty
+\endqml
+
+Such object-type properties default to an \c undefined value.
+
+It is also possible to store a copy of a JavaScript object using the \c variant
+property type. This creates some restrictions on how the property should be used;
+see the \l {variant}{variant type documentation} for details.
+
+\l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty
+list:
+
+\qml
+property list<Item> listOfItems
+\endqml
+
+Note that list properties cannot be modified like ordinary JavaScript
+arrays. See the \l {list}{list type documentation} for details.
+
+
+\section2 Property change signals
+
+Adding a \c property to an item automatically adds a \e {value changed}
+signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler}
+named with the \c on<Property>Changed syntax, using upper case for the first letter of the
+property name.
+
+For example, the following \c onMyNumberChanged signal handler is automatically called whenever the
+\c myNumber property changes:
+
+\snippet doc/snippets/qml/qml-extending-types/properties/property-signals.qml 0
+
+
+\section2 Default properties
+
+The optional \c default attribute for a property marks it as the \e {default property}
+for a type. This allows other items to specify the default property's value
+as child elements. For example, the \l Item element's default property is its
+\l{Item::children}{children} property. This allows the children of an \l Item
+to be set like this:
+
+\qml
+Item {
+ Rectangle {}
+ Rectangle {}
+}
+\endqml
+
+If the \l{Item::children}{children} property was not the default property for
+\l Item, its value would have to be set like this instead:
+
+\qml
+Item {
+ children: [
+ Rectangle {}
+ Rectangle {}
+ ]
+}
+\endqml
+
+See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a
+demonstration of using default properties.
+
+Specifying a default property overrides any existing default property (for
+example, any default property inherited from a parent item). Using the
+\c default attribute twice in the same type block is an error.
+
+
+\section2 Property aliases
+
+Property aliases are a more advanced form of property declaration. Unlike a
+property definition, which allocates a new, unique storage space for the
+property, a property alias connects the newly declared property (called the
+aliasing property) as a direct reference to an existing property (the aliased property). Read
+operations on the aliasing property act as read operations on the aliased
+property, and write operations on the aliasing property as write operations on
+the aliased property.
+
+A property alias declaration looks a lot like 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 "alias" keyword is used. Instead of a default
+value, a property alias includes a compulsory alias reference. The alias
+reference is used to locate the aliased property. While similar to a property
+binding, the alias reference syntax is highly restricted.
+
+An alias reference takes one of the following forms:
+\code
+ <id>.<property>
+ <id>
+\endcode
+
+where <id> must refer to an object id within the same component as the type
+declaring the alias, and, optionally, <property> refers to a property on that object.
+
+For example, below is a \c Button.qml component with a \c buttonText aliased property which is
+connected to the child Text object's \c text property:
+
+\snippet doc/snippets/qml/qml-extending-types/properties/alias.qml 0
+
+The following code would create a \c Button with a defined text string for the
+child \l Text object:
+
+\qml
+Button { buttonText: "This is a button" }
+\endqml
+
+Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not
+change some other value that then updates \c textItem.text.
+
+In this case, the use of aliased properties is essential. If \c buttonText was not an alias,
+changing its value would not actually change the displayed text at all, as
+\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would
+change when \c textItem.text changes, but not the other way around.
+
+Aliased properties are also useful for allowing external objects to directly modify and
+access child objects in a component. For example, here is a modified version of the \c ImageViewer
+component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has
+been changed to an alias to the child \l Image object:
+
+\table
+\row
+\li \snippet doc/snippets/qml/qml-extending-types/properties/alias/ImageViewer.qml 0
+\li \snippet doc/snippets/qml/qml-extending-types/properties/alias/application.qml 0
+\endtable
+
+Instead of being limited to setting the \l Image source, \c application.qml can now directly
+access and modify the child \l Image object and its properties.
+
+Obviously, exposing child objects in this manner should be done with care, as it allows external
+objects to modify them freely. However, this use of aliased properties can be quite useful in
+particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget}
+example, where new tab items are actually parented to a child object that displays the current tab.
+
+
+\section3 Considerations for property aliases
+
+Aliases are only activated once the component specifying them is completed. The
+most obvious consequence of this is that the component itself cannot generally
+use the aliased property directly during creation. For example, this will not work:
+
+\code
+ // Does NOT work
+ property alias buttonText: textItem.text
+ buttonText: "Some text" // buttonText is not yet defined when this value is set
+\endcode
+
+A second, much less significant, consequence of the delayed activation of
+aliases is that an alias reference cannot refer to another aliasing property
+declared within the same component. This will not work:
+
+\code
+ // Does NOT work
+ id: root
+ property alias buttonText: textItem.text
+ property alias buttonText2: root.buttonText
+\endcode
+
+At the time the component is created, the \c buttonText value has not yet been assigned,
+so \c root.buttonText would refer to an undefined value. (From outside the component,
+however, aliasing properties appear as regular Qt properties and consequently can be
+used in alias references.)
+
+It is possible for an aliased property to have the same name as an 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/snippets/qml/qml-extending-types/properties/alias-override.qml 0
+
+Any objects 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 rectangle can correctly set this property to "red" and refer to the actual defined
+property rather than the alias.
+
+
+\section1 Adding Methods
+
+A QML component can define methods of JavaScript code. These methods can be invoked
+either internally or by other objects.
+
+The syntax for defining a method is:
+
+\code
+function <name>([<parameter name>[, ...]]) { <body> }
+\endcode
+
+This declaration may appear anywhere within a type body, but it is customary to
+include it at the top. Attempting to declare two methods or signals with the
+same name in the same type block is an error. However, a new method may reuse
+the name of an existing method on the type. (This should be done with caution,
+as the existing method may be hidden and become inaccessible.)
+
+Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they
+default to the \c variant type. The body of the method is written in JavaScript and may access
+the parameters by name.
+
+Here is an example of a component with a \c say() method that accepts a single \c text argument:
+
+\snippet doc/snippets/qml/qml-extending-types/methods/app.qml 0
+
+A method can be connected to a signal so that it is automatically invoked whenever the signal
+is emitted. See \l {Connecting signals to methods and other signals} below.
+
+Also see \l {Integrating JavaScript} for more information on using JavaScript with QML.
+
+
+\section1 Adding Signals
+
+Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea
+\c clicked signal notifies other objects that the mouse has been clicked within the area.
+
+The syntax for defining a new signal is:
+
+\code
+signal <name>[([<type> <parameter name>[, ...]])]
+\endcode
+
+This declaration may appear anywhere within a type body, but it is customary to
+include it at the top. Attempting to declare two signals or methods with the
+same name in the same type block is an error. However, a new signal may reuse
+the name of an existing signal on the type. (This should be done with caution,
+as the existing signal may be hidden and become inaccessible.)
+
+Here are three examples of signal declarations:
+
+\code
+Item {
+ signal clicked
+ signal hovered()
+ signal performAction(string action, variant actionArgument)
+}
+\endcode
+
+If the signal has no parameters, the "()" brackets are optional. If parameters are used, the
+parameter types must be declared, as for the \c string and \c variant arguments for the \c
+performAction signal above; the allowed parameter types are the same as those listed in the \l
+{Adding Properties} section on this page.
+
+Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well.
+The signal hander is named \c on<SignalName>, with the first letter of the signal being upper
+cased. The above example item would now have the following signal handlers:
+
+\list
+\li onClicked
+\li onHovered
+\li onPerformAction
+\endlist
+
+To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is
+clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The
+signal is received by \c application.qml through an \c onButtonClicked signal handler:
+
+\table
+\row
+\li \snippet doc/snippets/qml/qml-extending-types/signals/basic.qml 0
+\li \snippet doc/snippets/qml/qml-extending-types/signals/no-parameters.qml 0
+\endtable
+
+If the signal has parameters, they are accessible by parameter name in the signal handler.
+In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead:
+
+\table
+\row
+\li \snippet doc/snippets/qml/qml-extending-types/signals/Button.qml 0
+\li \snippet doc/snippets/qml/qml-extending-types/signals/parameters.qml 0
+\endtable
+
+
+\section2 Connecting signals to methods and other signals
+
+Signal objects have a \c connect() method that can be used to a connect a signal to a method or
+another signal. When a signal is connected to a method, the method is automatically invoked
+whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected
+to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal
+to be received by a method instead of a \l {Signal Handlers}{signal handler}.
+
+For example, the \c application.qml above could be rewritten as:
+
+\snippet doc/snippets/qml/qml-extending-types/signals/connectslots.qml 0
+
+The \c myMethod() method will be called whenever the \c buttonClicked signal is received.
+
+In many cases it is sufficient to receive signals through signal handlers rather than using
+the \c connect() function; the above example does not provide any improvements over using a
+simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically},
+or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the
+\c connect() method useful. For example, the component below creates three \c Button
+objects dynamically, and connects the \c buttonClicked signal of each object to the
+\c myMethod() function:
+
+\snippet doc/snippets/qml/qml-extending-types/signals/connectdynamic.qml 0
+
+In the same way, you could connect a signal to methods defined in a dynamically
+created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}.
+
+There is also a corresponding \c disconnect() method for removing connected signals. The following
+code removes the connection created in \c application.qml above:
+
+\qml
+// application.qml
+Item {
+ ...
+
+ function removeSignal() {
+ button.clicked.disconnect(item.myMethod)
+ }
+}
+\endqml
+
+
+\section3 Forwarding signals
+
+The \c connect() method can also connect a signal to other signals. This has the effect
+of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For
+example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with
+a call to \c connect():
+
+\qml
+MouseArea {
+ anchors.fill: parent
+ Component.onCompleted: clicked.connect(item.buttonClicked)
+}
+\endqml
+
+Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will
+automatically be emitted as well.
+
+*/
\b Note: Unlike images, animated images are not cached or shared internally.
\clearfloat
- \snippet doc/src/snippets/qml/animatedimage.qml document
+ \snippet doc/snippets/qml/animatedimage.qml document
\sa BorderImage, Image
*/
used to determine the parts of the image that will lie inside the unscaled corner
areas and the parts that will be stretched horizontally and vertically.
- \snippet doc/src/snippets/qml/borderimage/normal-image.qml normal image
+ \snippet doc/snippets/qml/borderimage/normal-image.qml normal image
\clearfloat
\beginfloatleft
is set to \l{BorderImage::verticalTileMode}{BorderImage.Stretch}, the parts of image
in regions 4 and 6 are stretched vertically.
- \snippet doc/src/snippets/qml/borderimage/borderimage-scaled.qml scaled border image
+ \snippet doc/snippets/qml/borderimage/borderimage-scaled.qml scaled border image
\clearfloat
\beginfloatleft
\l{BorderImage::verticalTileMode}{BorderImage.Repeat}, the parts of image in regions
4 and 6 are tiled so that they fill the space at the left and right of the element.
- \snippet doc/src/snippets/qml/borderimage/borderimage-tiled.qml tiled border image
+ \snippet doc/snippets/qml/borderimage/borderimage-tiled.qml tiled border image
\clearfloat
In some situations, the width of regions 2 and 8 may not be an exact multiple of the width
However, dragging is not limited to mouse drags, anything that can move an item
can generate drag events, this can include touch events, animations and bindings.
- \snippet doc/src/snippets/qml/drag.qml 0
+ \snippet doc/snippets/qml/drag.qml 0
A drag can be terminated either by canceling it with Drag.cancel() or setting
Drag.active to false, or it can be terminated with a drop event by calling
The following example shows a small view onto a large image in which the
user can drag or flick the image in order to view different parts of it.
- \snippet doc/src/snippets/qml/flickable.qml document
+ \snippet doc/snippets/qml/flickable.qml document
\clearfloat
These properties are typically used to draw a scrollbar. For example:
- \snippet doc/src/snippets/qml/flickableScrollbar.qml 0
+ \snippet doc/snippets/qml/flickableScrollbar.qml 0
\dots 8
- \snippet doc/src/snippets/qml/flickableScrollbar.qml 1
+ \snippet doc/snippets/qml/flickableScrollbar.qml 1
\sa {declarative/ui-components/scrollbar}{scrollbar example}
*/
The following snippet shows how these properties are used to display
an image that is larger than the Flickable item itself:
- \snippet doc/src/snippets/qml/flickable.qml document
+ \snippet doc/snippets/qml/flickable.qml document
In some cases, the the content dimensions can be automatically set
using the \l {Item::childrenRect.width}{childrenRect.width}
degrees to produce the flipping effect. When \c flipped is false, the
item reverts to the default state, in which the \c angle value is 0.
- \snippet doc/src/snippets/qml/flipable/flipable.qml 0
+ \snippet doc/snippets/qml/flipable/flipable.qml 0
\image flipable.gif
The following example shows the definition of a simple list model defined
in a file called \c ContactModel.qml:
- \snippet doc/src/snippets/qml/gridview/ContactModel.qml 0
+ \snippet doc/snippets/qml/gridview/ContactModel.qml 0
\div {class="float-right"}
\inlineimage gridview-simple.png
(containing \l Image and \l Text elements) for its delegate.
\clearfloat
- \snippet doc/src/snippets/qml/gridview/gridview.qml import
+ \snippet doc/snippets/qml/gridview/gridview.qml import
\codeline
- \snippet doc/src/snippets/qml/gridview/gridview.qml classdocs simple
+ \snippet doc/snippets/qml/gridview/gridview.qml classdocs simple
\div {class="float-right"}
\inlineimage gridview-highlight.png
into a separate \c contactDelegate component.
\clearfloat
- \snippet doc/src/snippets/qml/gridview/gridview.qml classdocs advanced
+ \snippet doc/snippets/qml/gridview/gridview.qml classdocs advanced
The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property,
and \c focus is set to \c true to enable keyboard navigation for the grid view.
this attached property directly as \c GridView.isCurrentItem, while the child
\c contactInfo object must refer to this property as \c wrapper.GridView.isCurrentItem.
- \snippet doc/src/snippets/qml/gridview/gridview.qml isCurrentItem
+ \snippet doc/snippets/qml/gridview/gridview.qml isCurrentItem
\note Views do not set the \l{Item::}{clip} property automatically.
If the view is not clipped by another item or the screen, it will be necessary
It is attached to each instance of the delegate.
- \snippet doc/src/snippets/qml/gridview/gridview.qml isCurrentItem
+ \snippet doc/snippets/qml/gridview/gridview.qml isCurrentItem
*/
/*!
until an animation completes. The example delegate below ensures that the
animation completes before the item is removed from the list.
- \snippet doc/src/snippets/qml/gridview/gridview.qml delayRemove
+ \snippet doc/snippets/qml/gridview/gridview.qml delayRemove
If a \l remove transition has been specified, it will not be applied until
delayRemove is returned to \c false.
Here is a highlight with its motion defined by a \l {SpringAnimation} item:
- \snippet doc/src/snippets/qml/gridview/gridview.qml highlightFollowsCurrentItem
+ \snippet doc/snippets/qml/gridview/gridview.qml highlightFollowsCurrentItem
*/
The following example shows the simplest usage of the Image element.
- \snippet doc/src/snippets/qml/image.qml document
+ \snippet doc/snippets/qml/image.qml document
\beginfloatleft
\image declarative-qtlogo.png
rotations you must specify the axis to rotate around in addition to the origin point.
The following example shows various 3D-like rotations applied to an \l Image.
- \snippet doc/src/snippets/qml/rotation.qml 0
+ \snippet doc/snippets/qml/rotation.qml 0
\image axisrotation.png
The following example provides key navigation for a 2x2 grid of items:
- \snippet doc/src/snippets/qml/keynavigation.qml 0
+ \snippet doc/snippets/qml/keynavigation.qml 0
The top-left item initially receives focus by setting \l {Item::}{focus} to
\c true. When an arrow key is pressed, the focus will move to the
be used to test for a certain key; in this case, the left cursor
key:
- \snippet doc/src/snippets/qml/keys/keys-pressed.qml key item
+ \snippet doc/snippets/qml/keys/keys-pressed.qml key item
Some keys may alternatively be handled via specific signal properties,
for example \e onSelectPressed. These handlers automatically set
\e event.accepted to true.
- \snippet doc/src/snippets/qml/keys/keys-handler.qml key item
+ \snippet doc/snippets/qml/keys/keys-handler.qml key item
See \l{Qt::Key}{Qt.Key} for the list of keyboard codes.
from left to right by default, they are now positioned from right to left instead, as demonstrated
by the numbering and opacity of the items:
- \snippet doc/src/snippets/qml/layoutmirroring.qml 0
+ \snippet doc/snippets/qml/layoutmirroring.qml 0
\image layoutmirroring.png
the transition, ensures the item animates smoothly as it moves to
its new parent:
- \snippet doc/src/snippets/qml/parentanimation.qml 0
+ \snippet doc/snippets/qml/parentanimation.qml 0
A ParentAnimation can contain any number of animations. These animations will
be run in parallel; to run them sequentially, define them within a
In the following snippet we animate the addition of a right anchor to a \l Rectangle:
- \snippet doc/src/snippets/qml/anchoranimation.qml 0
+ \snippet doc/snippets/qml/anchoranimation.qml 0
For convenience, when an AnchorAnimation is used in a \l Transition, it will
animate any AnchorChanges that have occurred during the state change.
Here is a basic example of the use of view transitions. The view below specifies transitions for
the \c add and \c displaced properties, which will be run when items are added to the view:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-basic.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-basic.qml 0
When the space key is pressed, adding an item to the model, the new item will fade in and
increase in scale over 400 milliseconds as it is added to the view. Also, any item that is
each displaced item based on the difference between its index (provided by ViewTransition.index)
and the first removed index (provided by ViewTransition.targetIndexes):
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-delayedbyindex.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-delayedbyindex.qml 0
Each displaced item delays its animation by an additional 100 milliseconds, producing a subtle
ripple-type effect when items are displaced by the add, like this:
animate to an intermediate position relative to its starting point for the transition, before
animating to its final position in the view:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-intermediatemove.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-intermediatemove.qml 0
Now, a displaced item will first move to a position of (20, 50) relative to its starting
position, and then to its final, correct position in the view:
a curved path. For example, the \c add transition in the previous example could be augmented with
a PathAnimation as follows: to animate newly added items along a path:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-pathanim.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-pathanim.qml 0
This animates newly added items along a path. Notice that each path is specified relative to
each item's final destination point, so that items inserted at different indexes start their
properties, this interruption may cause unwanted side effects. Consider the first example on this
page, repeated below for convenience:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-basic.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-basic.qml 0
If multiple items are added in rapid succession, without waiting for a previous transition
to finish, this is the result:
set to the end values specified in the \c add transition, effectively resetting these values
whenever an item is displaced. In this case, it means setting the item opacity and scale to 1.0:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-interruptedgood.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-interruptedgood.qml 0
Now, when an item's \c add transition is interrupted, its opacity and scale are animated to 1.0
upon displacement, avoiding the erroneous visual effects from before:
attached property, as it may not refer to the expected values at the time that the ScriptAction
is actually invoked. Consider the following example:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-scriptactionbad.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-scriptactionbad.qml 0
When the space key is pressed, three items are moved from index 5 to index 1. For each moved
item, the \c moveTransition sequence presumably animates the item's color to "yellow", then
In this instance, to avoid this issue, the view could set the property using a PropertyAction
instead:
- \snippet doc/src/snippets/declarative/viewtransitions/viewtransitions-scriptactiongood.qml 0
+ \snippet doc/snippets/qml/viewtransitions/viewtransitions-scriptactiongood.qml 0
When the transition is initialized, the PropertyAction \c target will be set to the respective
ViewTransition.item for the transition and will later run with the correct item target as
The following example shows the definition of a simple list model defined
in a file called \c ContactModel.qml:
- \snippet doc/src/snippets/qml/listview/ContactModel.qml 0
+ \snippet doc/snippets/qml/listview/ContactModel.qml 0
Another component can display this model data in a ListView, like this:
- \snippet doc/src/snippets/qml/listview/listview.qml import
+ \snippet doc/snippets/qml/listview/listview.qml import
\codeline
- \snippet doc/src/snippets/qml/listview/listview.qml classdocs simple
+ \snippet doc/snippets/qml/listview/listview.qml classdocs simple
\image listview-simple.png
An improved list view is shown below. The delegate is visually improved and is moved
into a separate \c contactDelegate component.
- \snippet doc/src/snippets/qml/listview/listview.qml classdocs advanced
+ \snippet doc/snippets/qml/listview/listview.qml classdocs advanced
\image listview-highlight.png
The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property,
this attached property directly as \c ListView.isCurrentItem, while the child
\c contactInfo object must refer to this property as \c wrapper.ListView.isCurrentItem.
- \snippet doc/src/snippets/qml/listview/listview.qml isCurrentItem
+ \snippet doc/snippets/qml/listview/listview.qml isCurrentItem
\note Views do not enable \e clip automatically. If the view
is not clipped by another item or the screen, it will be necessary
This property may be used to adjust the appearance of the current item, for example:
- \snippet doc/src/snippets/qml/listview/listview.qml isCurrentItem
+ \snippet doc/snippets/qml/listview/listview.qml isCurrentItem
*/
/*!
until an animation completes. The example delegate below ensures that the
animation completes before the item is removed from the list.
- \snippet doc/src/snippets/qml/listview/listview.qml delayRemove
+ \snippet doc/snippets/qml/listview/listview.qml delayRemove
If a \l remove transition has been specified, it will not be applied until
delayRemove is returned to \c false.
Here is a highlight with its motion defined by a \l {SpringAnimation} item:
- \snippet doc/src/snippets/qml/listview/listview.qml highlightFollowsCurrentItem
+ \snippet doc/snippets/qml/listview/listview.qml highlightFollowsCurrentItem
Note that the highlight animation also affects the way that the view
is scrolled. This is because the view moves to maintain the
Here is a Loader that loads "Page1.qml" as a component when the
\l MouseArea is clicked:
- \snippet doc/src/snippets/qml/loader/simple.qml 0
+ \snippet doc/snippets/qml/loader/simple.qml 0
The loaded item can be accessed using the \l item property.
\li sizeloader.qml
\li sizeitem.qml
\row
- \li \snippet doc/src/snippets/qml/loader/sizeloader.qml 0
- \li \snippet doc/src/snippets/qml/loader/sizeitem.qml 0
+ \li \snippet doc/snippets/qml/loader/sizeloader.qml 0
+ \li \snippet doc/snippets/qml/loader/sizeitem.qml 0
\row
\li The red rectangle will be sized to the size of the root item.
\li The red rectangle will be 50x50, centered in the root item.
\li application.qml
\li MyItem.qml
\row
- \li \snippet doc/src/snippets/qml/loader/connections.qml 0
- \li \snippet doc/src/snippets/qml/loader/MyItem.qml 0
+ \li \snippet doc/snippets/qml/loader/connections.qml 0
+ \li \snippet doc/snippets/qml/loader/MyItem.qml 0
\endtable
Alternatively, since \c MyItem.qml is loaded within the scope of the
\li application.qml
\li KeyReader.qml
\row
- \li \snippet doc/src/snippets/qml/loader/focus.qml 0
- \li \snippet doc/src/snippets/qml/loader/KeyReader.qml 0
+ \li \snippet doc/snippets/qml/loader/focus.qml 0
+ \li \snippet doc/snippets/qml/loader/KeyReader.qml 0
\endtable
Once \c KeyReader.qml is loaded, it accepts key events and sets
The following example uses a MouseArea in a \l Rectangle that changes
the \l Rectangle color to red when clicked:
- \snippet doc/src/snippets/qml/mousearea/mousearea.qml import
+ \snippet doc/snippets/qml/mousearea/mousearea.qml import
\codeline
- \snippet doc/src/snippets/qml/mousearea/mousearea.qml intro
+ \snippet doc/snippets/qml/mousearea/mousearea.qml intro
\clearfloat
Many MouseArea signals pass a \l{MouseEvent}{mouse} parameter that contains
Here is an extension of the previous example that produces a different
color when the area is right clicked:
- \snippet doc/src/snippets/qml/mousearea/mousearea.qml intro-extended
+ \snippet doc/snippets/qml/mousearea/mousearea.qml intro-extended
Behavioral Change in QtQuick 2.0
The code below displays "right" when the right mouse buttons is pressed:
- \snippet doc/src/snippets/qml/mousearea/mousearea.qml mousebuttons
+ \snippet doc/snippets/qml/mousearea/mousearea.qml mousebuttons
\sa acceptedButtons
*/
The following example displays a \l Rectangle that can be dragged along the X-axis. The opacity
of the rectangle is reduced when it is dragged to the right.
- \snippet doc/src/snippets/qml/mousearea/mousearea.qml drag
+ \snippet doc/snippets/qml/mousearea/mousearea.qml drag
\note Items cannot be dragged if they are anchored for the requested
\c drag.axis. For example, if \c anchors.left or \c anchors.right was set
If \c drag.filterChildren is set to true, a drag can override descendant MouseAreas. This
enables a parent MouseArea to handle drags, for example, while descendants handle clicks:
- \snippet doc/src/snippets/qml/mousearea/mouseareadragfilter.qml dragfilter
+ \snippet doc/snippets/qml/mousearea/mouseareadragfilter.qml dragfilter
*/
In the following example, we have two small rectangles that follow our touch points.
- \snippet doc/src/snippets/qml/multipointtoucharea/multipointtoucharea.qml 0
+ \snippet doc/snippets/qml/multipointtoucharea/multipointtoucharea.qml 0
By default this property holds an empty list.
For example, if there is a simple list model defined in a file \c ContactModel.qml like this:
- \snippet doc/src/snippets/qml/pathview/ContactModel.qml 0
+ \snippet doc/snippets/qml/pathview/ContactModel.qml 0
This data can be represented as a PathView, like this:
- \snippet doc/src/snippets/qml/pathview/pathview.qml 0
+ \snippet doc/snippets/qml/pathview/pathview.qml 0
\image pathview.gif
this attached property directly as \c PathView.isCurrentItem, while the child
\c nameText object must refer to this property as \c wrapper.PathView.isCurrentItem.
- \snippet doc/src/snippets/qml/pathview/pathview.qml 1
+ \snippet doc/snippets/qml/pathview/pathview.qml 1
\b Note that views do not enable \e clip automatically. If the view
is not clipped by another item or the screen, it will be necessary
This property may be used to adjust the appearance of the current item.
- \snippet doc/src/snippets/qml/pathview/pathview.qml 1
+ \snippet doc/snippets/qml/pathview/pathview.qml 1
*/
/*!
item in the delegate.
Here is an example delegate:
- \snippet doc/src/snippets/qml/pathview/pathview.qml 1
+ \snippet doc/snippets/qml/pathview/pathview.qml 1
*/
QQmlComponent *QQuickPathView::delegate() const
{
Below is a Column that contains three rectangles of various sizes:
- \snippet doc/src/snippets/qml/column/vertical-positioner.qml document
+ \snippet doc/snippets/qml/column/vertical-positioner.qml document
The Column automatically positions these items in a vertical formation, like this:
For example, the Column below sets the \l move property to a specific \l Transition:
- \snippet doc/src/snippets/qml/column/column-transitions.qml document
+ \snippet doc/snippets/qml/column/column-transitions.qml document
When the Space key is pressed, the \l {Item::visible}{visible} value of the green
\l Rectangle is toggled. As it appears and disappears, the blue \l Rectangle moves within
Below is a Row that contains three rectangles of various sizes:
- \snippet doc/src/snippets/qml/row/row.qml document
+ \snippet doc/snippets/qml/row/row.qml document
The Row automatically positions these items in a horizontal formation, like this:
For example, below is a Grid that contains five rectangles of various sizes:
- \snippet doc/src/snippets/qml/grid/grid.qml document
+ \snippet doc/snippets/qml/grid/grid.qml document
The Grid automatically positions the child items in a grid formation:
Below is a Flow that contains various \l Text items:
- \snippet doc/src/snippets/qml/flow.qml flow item
+ \snippet doc/snippets/qml/flow.qml flow item
The Flow item automatically positions the child \l Text items side by
side, wrapping as necessary:
with red, blending to yellow at one third of the height of the rectangle,
and ending with green:
- \snippet doc/src/snippets/qml/gradient.qml code
+ \snippet doc/snippets/qml/gradient.qml code
\clearfloat
\section1 Performance and Limitations
The following example shows the effects of some of the common properties on a
Rectangle item, which in this case is used to create a square:
- \snippet doc/src/snippets/qml/rectangle/rectangle.qml document
+ \snippet doc/snippets/qml/rectangle/rectangle.qml document
\clearfloat
\section1 Performance
\inlineimage rect-border-width.png
\enddiv
- \snippet doc/src/snippets/qml/rectangle/rect-border-width.qml 0
+ \snippet doc/snippets/qml/rectangle/rect-border-width.qml 0
\clearfloat
Here, the innermost rectangle's border is clipped on the bottom and right edges by its
\inlineimage declarative-rect_gradient.png
\enddiv
- \snippet doc/src/snippets/qml/rectangle/rectangle-gradient.qml rectangles
+ \snippet doc/snippets/qml/rectangle/rectangle-gradient.qml rectangles
\clearfloat
If both a gradient and a color are specified, the gradient will be used.
The following example shows rectangles with colors specified
using hexadecimal and named color notation:
- \snippet doc/src/snippets/qml/rectangle/rectangle-colors.qml rectangles
+ \snippet doc/snippets/qml/rectangle/rectangle-colors.qml rectangles
\clearfloat
If both a gradient and a color are specified, the gradient will be used.
The following Repeater creates three instances of a \l Rectangle item within
a \l Row:
- \snippet doc/src/snippets/qml/repeaters/repeater.qml import
+ \snippet doc/snippets/qml/repeaters/repeater.qml import
\codeline
- \snippet doc/src/snippets/qml/repeaters/repeater.qml simple
+ \snippet doc/snippets/qml/repeaters/repeater.qml simple
\image repeater-simple.png
a Repeater to be used inside a layout. For example, the following Repeater's
items are stacked between a red rectangle and a blue rectangle:
- \snippet doc/src/snippets/qml/repeaters/repeater.qml layout
+ \snippet doc/snippets/qml/repeaters/repeater.qml layout
\image repeater.png
\table
\row
- \li \snippet doc/src/snippets/qml/repeaters/repeater.qml index
+ \li \snippet doc/snippets/qml/repeaters/repeater.qml index
\li \image repeater-index.png
\endtable
\table
\row
- \li \snippet doc/src/snippets/qml/repeaters/repeater.qml modeldata
+ \li \snippet doc/snippets/qml/repeaters/repeater.qml modeldata
\li \image repeater-modeldata.png
\endtable
When the \c blueRect is clicked, it changes to the "reparented" state: its parent is changed to \c redRect and it is
positioned at (10, 10) within the red rectangle, as specified in the ParentChange.
- \snippet doc/src/snippets/qml/parentchange.qml 0
+ \snippet doc/snippets/qml/parentchange.qml 0
\image parentchange.png
using AnchorChanges, and the top and bottom anchor margins using
PropertyChanges:
- \snippet doc/src/snippets/qml/anchorchanges.qml 0
+ \snippet doc/snippets/qml/anchorchanges.qml 0
\image anchorchanges.png
The link must be in rich text or HTML format and the
\a link string provides access to the particular link.
- \snippet doc/src/snippets/qml/text/onLinkActivated.qml 0
+ \snippet doc/snippets/qml/text/onLinkActivated.qml 0
The example code will display the text
"The main website is at \l{http://qt.nokia.com}{Nokia Qt DF}."
The example below illustrates using a VisualDataModel with a ListView.
- \snippet doc/src/snippets/qml/visualdatamodel.qml 0
+ \snippet doc/snippets/qml/visualdatamodel.qml 0
*/
QQuickVisualDataModelPrivate::QQuickVisualDataModelPrivate(QQmlContext *ctxt)
the new directory's contents.
\c main.cpp:
- \snippet doc/src/snippets/qml/visualdatamodel_rootindex/main.cpp 0
+ \snippet doc/snippets/qml/visualdatamodel_rootindex/main.cpp 0
\c view.qml:
- \snippet doc/src/snippets/qml/visualdatamodel_rootindex/view.qml 0
+ \snippet doc/snippets/qml/visualdatamodel_rootindex/view.qml 0
If the \l model is a QAbstractItemModel subclass, the delegate can also
reference a \c hasModelChildren property (optionally qualified by a
The following example illustrates using groups to select items in a model.
- \snippet doc/src/snippets/qml/visualdatagroup.qml 0
+ \snippet doc/snippets/qml/visualdatagroup.qml 0
*/
QQmlListProperty<QQuickVisualDataGroup> QQuickVisualDataModel::groups()
as a property value source. It animates the \c color property's value from
its current value to a value of "red", over 1000 milliseconds:
- \snippet doc/src/snippets/qml/coloranimation.qml 0
+ \snippet doc/snippets/qml/coloranimation.qml 0
Like any other animation element, a ColorAnimation can be applied in a
number of ways, including transitions, behaviors and property value
When used as part of a Transition, you can also target a specific
StateChangeScript to run using the \c scriptName property.
- \snippet doc/src/snippets/qml/states/statechangescript.qml state and transition
+ \snippet doc/snippets/qml/states/statechangescript.qml state and transition
\sa StateChangeScript
*/
\l {Image::}{smooth} property to \c true, animates the width of the image,
then sets \l {Image::}{smooth} back to \c false:
- \snippet doc/src/snippets/qml/propertyaction.qml standalone
+ \snippet doc/snippets/qml/propertyaction.qml standalone
PropertyAction is also useful for setting the exact point at which a property
change should occur during a \l Transition. For example, if PropertyChanges
was used in a \l State to rotate an item around a particular
\l {Item::}{transformOrigin}, it might be implemented like this:
- \snippet doc/src/snippets/qml/propertyaction.qml transition
+ \snippet doc/snippets/qml/propertyaction.qml transition
However, with this code, the \c transformOrigin is not set until \e after
the animation, as a \l State is taken to define the values at the \e end of
then jump to \c Item.BottomRight. To fix this, insert a PropertyAction
before the RotationAnimation begins:
- \snippet doc/src/snippets/qml/propertyaction-sequential.qml sequential
+ \snippet doc/snippets/qml/propertyaction-sequential.qml sequential
This immediately sets the \c transformOrigin property to the value defined
in the end state of the \l Transition (i.e. the value defined in the
as a property value source. It animates the \c x value from its current
value to a value of 50, over 1000 milliseconds:
- \snippet doc/src/snippets/qml/numberanimation.qml 0
+ \snippet doc/snippets/qml/numberanimation.qml 0
Like any other animation element, a NumberAnimation can be applied in a
number of ways, including transitions, behaviors and property value
In the following example we use RotationAnimation to animate the rotation
between states via the shortest path:
- \snippet doc/src/snippets/qml/rotationanimation.qml 0
+ \snippet doc/snippets/qml/rotationanimation.qml 0
Notice the RotationAnimation did not need to set a \l target
value. As a convenience, when used in a transition, RotationAnimation will rotate all
The following example runs two number animations in a sequence. The \l Rectangle
animates to a \c x position of 50, then to a \c y position of 50.
- \snippet doc/src/snippets/qml/sequentialanimation.qml 0
+ \snippet doc/snippets/qml/sequentialanimation.qml 0
Animations defined within a \l Transition are automatically run in parallel,
so SequentialAnimation can be used to enclose the animations in a \l Transition
The following animation runs two number animations in parallel. The \l Rectangle
moves to (50,50) by animating its \c x and \c y properties at the same time.
- \snippet doc/src/snippets/qml/parallelanimation.qml 0
+ \snippet doc/snippets/qml/parallelanimation.qml 0
Like any other animation element, a ParallelAnimation can be applied in a
number of ways, including transitions, behaviors and property value
For example, to animate any objects that have changed their \c x or \c y properties
as a result of a state change, using an \c InOutQuad easing curve:
- \snippet doc/src/snippets/qml/propertyanimation.qml transition
+ \snippet doc/snippets/qml/propertyanimation.qml transition
\li In a \l Behavior
For example, to animate all changes to a rectangle's \c x property:
- \snippet doc/src/snippets/qml/propertyanimation.qml behavior
+ \snippet doc/snippets/qml/propertyanimation.qml behavior
\li As a property value source
For example, to repeatedly animate the rectangle's \c x property:
- \snippet doc/src/snippets/qml/propertyanimation.qml propertyvaluesource
+ \snippet doc/snippets/qml/propertyanimation.qml propertyvaluesource
\li In a signal handler
For example, to animate \c rect's \c width property over 500ms, from its current width to 30:
- \snippet doc/src/snippets/qml/propertyanimation.qml standalone
+ \snippet doc/snippets/qml/propertyanimation.qml standalone
\endlist
whenever the \l Rectangle's \c width value changes. When the MouseArea
is clicked, the \c width is changed, triggering the behavior's animation:
- \snippet doc/src/snippets/qml/behavior.qml 0
+ \snippet doc/snippets/qml/behavior.qml 0
Note that a property cannot have more than one assigned Behavior. To provide
multiple animations within a Behavior, use ParallelAnimation or
\li \l PathPercent - a way to spread out items along various segments of the path.
\endlist
- \snippet doc/src/snippets/qml/pathview/pathattributes.qml 2
+ \snippet doc/snippets/qml/pathview/pathattributes.qml 2
*/
QQmlListProperty<QQuickPathElement> QQuickPath::pathElements()
\row
\li \image declarative-pathattribute.png
\li
- \snippet doc/src/snippets/qml/pathview/pathattributes.qml 0
+ \snippet doc/snippets/qml/pathview/pathattributes.qml 0
(see the PathView documentation for the specification of ContactModel.qml
used for ContactModel above.)
\endtable
PathCurve provides an easy way to specify a curve passing directly through a set of points.
Typically multiple PathCurves are used in a series, as the following example demonstrates:
- \snippet doc/src/snippets/qml/path/basiccurve.qml 0
+ \snippet doc/snippets/qml/path/basiccurve.qml 0
This example produces the following path (with the starting point and PathCurve points
highlighted in red):
\table
\row
\li \image declarative-patharc.png
- \li \snippet doc/src/snippets/qml/path/basicarc.qml 0
+ \li \snippet doc/snippets/qml/path/basicarc.qml 0
\endtable
Note that a single PathArc cannot be used to specify a circle. Instead, you can
\table
\row
\li \image declarative-arcradius.png
- \li \snippet doc/src/snippets/qml/path/arcradius.qml 0
+ \li \snippet doc/snippets/qml/path/arcradius.qml 0
\endtable
*/
\table
\row
\li \image declarative-largearc.png
- \li \snippet doc/src/snippets/qml/path/largearc.qml 0
+ \li \snippet doc/snippets/qml/path/largearc.qml 0
\endtable
The default value is false.
\table
\row
\li \image declarative-arcdirection.png
- \li \snippet doc/src/snippets/qml/path/arcdirection.qml 0
+ \li \snippet doc/snippets/qml/path/arcdirection.qml 0
\endtable
\sa useLargeArc
In the following example, we animate a green rectangle along a bezier path.
- \snippet doc/src/snippets/qml/pathinterpolator.qml 0
+ \snippet doc/snippets/qml/pathinterpolator.qml 0
*/
QQuickPathInterpolator::QQuickPathInterpolator(QObject *parent) :
properties are to be modified, and define the new property values or
bindings. For example:
- \snippet doc/src/snippets/qml/propertychanges.qml import
+ \snippet doc/snippets/qml/propertychanges.qml import
\codeline
- \snippet doc/src/snippets/qml/propertychanges.qml 0
+ \snippet doc/snippets/qml/propertychanges.qml 0
When the mouse is pressed, the \l Rectangle changes to the \e resized
state. In this state, the PropertyChanges object sets the rectangle's
state, its \c width property is reset, giving the text its natural width
and displaying the whole string on a single line.
- \snippet doc/src/snippets/qml/propertychanges.qml reset
+ \snippet doc/snippets/qml/propertychanges.qml reset
\section2 Immediate property changes in transitions
bound to those of the red rectangle. Whenever these values change, the
green rectangle smoothly animates to its new position:
- \snippet doc/src/snippets/qml/smoothedanimation.qml 0
+ \snippet doc/snippets/qml/smoothedanimation.qml 0
A SmoothedAnimation can be configured by setting the \l velocity at which the
animation should occur, or the \l duration that the animation should take.
on the \c x and \c y values indicates that whenever these values are
changed, a SpringAnimation should be applied.
- \snippet doc/src/snippets/qml/springanimation.qml 0
+ \snippet doc/snippets/qml/springanimation.qml 0
Like any other animation element, a SpringAnimation can be applied in a
number of ways, including transitions, behaviors and property value
between the default state and the "clicked" state, thus toggling the color of the
rectangle between black and red.
- \snippet doc/src/snippets/qml/state.qml 0
+ \snippet doc/snippets/qml/state.qml 0
Notice the default state is referred to using an empty string ("").
be applied. For example, the following \l Rectangle changes in and out of the "hidden"
state when the \l MouseArea is pressed:
- \snippet doc/src/snippets/qml/state-when.qml 0
+ \snippet doc/snippets/qml/state-when.qml 0
If multiple states in a group have \c when clauses that evaluate to \c true
at the same time, the first matching state will be applied. For example, in
ScriptAction to specify the point in the transition at which
the StateChangeScript should to be run.
- \snippet snippets/declarative/states/statechangescript.qml state and transition
+ \snippet snippets/qml/states/statechangescript.qml state and transition
\sa ScriptAction
*/
group and uses this to color the window and text items
appropriately:
- \snippet doc/src/snippets/qml/systempalette.qml 0
+ \snippet doc/snippets/qml/systempalette.qml 0
\sa QPalette
*/
changes between the default and the "moved" state, any changes
to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad.
- \snippet doc/src/snippets/qml/transition.qml 0
+ \snippet doc/snippets/qml/transition.qml 0
Notice the example does not require \l{PropertyAnimation::}{to} and
\l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience,
To define multiple transitions, specify \l Item::transitions as a list:
- \snippet doc/src/snippets/qml/transitions-list.qml list of transitions
+ \snippet doc/snippets/qml/transitions-list.qml list of transitions
If multiple Transitions are specified, only a single (best-matching) Transition will be applied for any particular
state change. In the example above, when changing to \c state1, the first transition will be used, rather
properties, so the animation is always applied when changing between
the two states (i.e. when the mouse is pressed and released).
- \snippet doc/src/snippets/qml/transition-from-to.qml 0
+ \snippet doc/snippets/qml/transition-from-to.qml 0
If the transition was changed to this:
- \snippet doc/src/snippets/qml/transition-from-to-modified.qml modified transition
+ \snippet doc/snippets/qml/transition-from-to-modified.qml modified transition
The animation would only be applied when changing from the default state to
the "brighter" state (i.e. when the mouse is pressed, but not on release).
transition applies a sequential animation when the mouse is pressed,
and reverses the sequence of the animation when the mouse is released:
- \snippet doc/src/snippets/qml/transition-reversible.qml 0
+ \snippet doc/snippets/qml/transition-reversible.qml 0
If the transition did not set the \c to and \c reversible values, then
on the mouse release, the transition would play the PropertyAnimation
The top-level animations are run in parallel. To run them sequentially,
define them within a SequentialAnimation:
- \snippet doc/src/snippets/qml/transition-reversible.qml sequential animations
+ \snippet doc/snippets/qml/transition-reversible.qml sequential animations
*/
QQmlListProperty<QQuickAbstractAnimation> QQuickTransition::animations()
{
projects / konrad/qtdeclarative.git / commitdiff
