diff options
Diffstat (limited to 'doc/src/qtquick2')
| -rw-r--r-- | doc/src/qtquick2/anchor-layout.qdoc | 143 | ||||
| -rw-r--r-- | doc/src/qtquick2/animation.qdoc | 271 | ||||
| -rw-r--r-- | doc/src/qtquick2/basicelements.qdoc | 131 | ||||
| -rw-r--r-- | doc/src/qtquick2/behaviors-and-states.qdoc | 207 | ||||
| -rw-r--r-- | doc/src/qtquick2/canvaspainting.qdoc | 44 | ||||
| -rw-r--r-- | doc/src/qtquick2/elements.qdoc | 359 | ||||
| -rw-r--r-- | doc/src/qtquick2/focus.qdoc | 206 | ||||
| -rw-r--r-- | doc/src/qtquick2/modelview.qdoc | 378 | ||||
| -rw-r--r-- | doc/src/qtquick2/mouseevents.qdoc | 118 | ||||
| -rw-r--r-- | doc/src/qtquick2/positioners.qdoc | 140 | ||||
| -rw-r--r-- | doc/src/qtquick2/qmltexthandling.qdoc | 75 | ||||
| -rw-r--r-- | doc/src/qtquick2/qtquick-intro.qdoc | 143 | ||||
| -rw-r--r-- | doc/src/qtquick2/qtquick2.qdoc | 38 | ||||
| -rw-r--r-- | doc/src/qtquick2/righttoleft.qdoc | 196 | ||||
| -rw-r--r-- | doc/src/qtquick2/shaders.qdoc | 52 | ||||
| -rw-r--r-- | doc/src/qtquick2/states.qdoc | 156 | ||||
| -rw-r--r-- | doc/src/qtquick2/writingcomponents.qdoc | 498 |
17 files changed, 3155 insertions, 0 deletions
diff --git a/doc/src/qtquick2/anchor-layout.qdoc b/doc/src/qtquick2/anchor-layout.qdoc new file mode 100644 index 0000000000..6e56768f8a --- /dev/null +++ b/doc/src/qtquick2/anchor-layout.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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 \i 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 \i 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 \i rect2 is bound to the right edge of \i 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, +\i rect2 is anchored to the right of \i rect1 and the left of \i rect3. If either of the blue +rectangles are moved, \i 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 \i margins and \i 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 \i rect2, producing the following: + +\image edge2.png + +\note Anchor margins only apply to anchors; they are \i 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. + +*/ diff --git a/doc/src/qtquick2/animation.qdoc b/doc/src/qtquick2/animation.qdoc new file mode 100644 index 0000000000..626571f50e --- /dev/null +++ b/doc/src/qtquick2/animation.qdoc @@ -0,0 +1,271 @@ +/**************************************************************************** +** +** 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 +\ingroup qml-features +\title QML Animation and Transitions +\brief the animation system in Qt Quick + +\keyword qml-animation-elements +\section1 Animation and Transitions Elements +\list +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation +\endlist + +\keyword qml-property-animation-elements +Elements that animate properties based on data types +\list +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes +\endlist + +In QML, 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. + +\keyword qml-triggering-animations +\section1 Triggering Animations + +There are several ways of setting animation to an object. + +\keyword qml-direct-animation +\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/src/snippets/declarative/animation.qml direct property change + +However, to create more control, \i {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/src/snippets/declarative/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{QML 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/src/snippets/declarative/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/src/snippets/declarative/animation.qml wildcard animation + +\section2 Default Animation as Behaviors + +Default property animations are set using \i {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/src/snippets/declarative/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 \i {in parallel} or \i {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/src/snippets/declarative/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 +\o PauseAnimation: enables pauses during animations +\o ScriptAction: allows JavaScript to be executed during an animation, and can +be used together with StateChangeScript to reused existing scripts +\o PropertyAction: changes a property \i immediately during an animation, +without animating the property change +\endlist + +These are specialized animation elements that animate different property types +\list +\o SmoothedAnimation: a specialized NumberAnimation that provides smooth +changes in animation when the target value changes +\o SpringAnimation: provides a spring-like animation with specialized +attributes such as \l {SpringAnimation::}{mass}, +\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon} +\o ParentAnimation: used for animating a parent change (see ParentChange) +\o 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/src/snippets/declarative/animation-elements.qml color +\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 +\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 +\snippet doc/src/snippets/declarative/animation-standalone.qml 0 + +\snippet doc/src/snippets/declarative/animation-transitions.qml 0 +\snippet doc/src/snippets/declarative/animation-groups.qml 0 + +\snippet doc/src/snippets/declarative/animation-groups.qml 1 +\snippet doc/src/snippets/declarative/animation-groups.qml 0 +\image propanim.gif + diff --git a/doc/src/qtquick2/basicelements.qdoc b/doc/src/qtquick2/basicelements.qdoc new file mode 100644 index 0000000000..ae212f1964 --- /dev/null +++ b/doc/src/qtquick2/basicelements.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** 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 Qt Quick Basic Elements +\brief introduction to the Qt Quick Elements + +Qt Quick includes \i 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 +\o \l {Item} +\o \l {Rectangle} +\o \l {Image} +\o \l {Text} +\o \l {TextInput} +\o \l {TextEdit} +\o \l {FocusScope} +\o \l {Component} +\o \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{QML 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. +*/ diff --git a/doc/src/qtquick2/behaviors-and-states.qdoc b/doc/src/qtquick2/behaviors-and-states.qdoc new file mode 100644 index 0000000000..626b6e61e3 --- /dev/null +++ b/doc/src/qtquick2/behaviors-and-states.qdoc @@ -0,0 +1,207 @@ +/**************************************************************************** +** +** 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 +\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 +\o a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and +\o 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 + +*/ diff --git a/doc/src/qtquick2/canvaspainting.qdoc b/doc/src/qtquick2/canvaspainting.qdoc new file mode 100644 index 0000000000..8590c74913 --- /dev/null +++ b/doc/src/qtquick2/canvaspainting.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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 + \o \l{Canvas} + \o \l{Context2D} +\endlist + +The Canvas and Context2D elements implement the \l{HTML Canvas API 2D Context} +and allows applications to have custom painting routines. + +*/ diff --git a/doc/src/qtquick2/elements.qdoc b/doc/src/qtquick2/elements.qdoc new file mode 100644 index 0000000000..4dde7216e5 --- /dev/null +++ b/doc/src/qtquick2/elements.qdoc @@ -0,0 +1,359 @@ +/**************************************************************************** +** +** 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 QML Elements +\brief a listing of standard QML elements + + +\target elements + +These are the functionally grouped lists of QML 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. + +To see the QML elements listed by functional area, see the +\l{Groups Of Related QML Elements} page. + +\section1 Basic QML Elements +\list +\o \l {Item} - Basic item element inherited by QML elements +\o \l {Component} - Encapsulates QML elements during importing +\o \l {QtObject} {QtObject} - Basic element containing only the \c {objectName} property +\endlist + +\section1 Graphics +\list +\o \l {Rectangle} - A rectangle element +\o \l {Image} - For incorporating bitmaps into a scene +\o \l {BorderImage} - Allows the use of images as borders +\o \l {AnimatedImage} - For playing animations stored in a series of frames +\o \l {Gradient} - For defining a color gradient +\o \l {GradientStop} - Used to define a color within a \l {Gradient} +\o \l {SystemPalette} - Provides access to the Qt palettes +\o \l {Canvas} - Provides a 2D canvas element +\endlist + +\section1 Text Handling +\list +\o \l {Text} - For inserting formatted text into a scene +\o \l {TextInput} - Captures user key input +\o \l {TextEdit} - Displays multiple lines of editable formatted text +\o \l {IntValidator} - Validates values as integers +\o \l {DoubleValidator} - Validates real values +\o \l {RegExpValidator} - Validator for string regular expressions +\o \l {FontLoader} - Loads fonts by name or URL +\endlist + +\section1 Mouse and Interaction Area +\list +\o \l {MouseArea} - Sets up an area for mouse interaction +\o \l {Keys} - Provides components with attached properties to handle key input. +\o \l {FocusScope} - Element that mediate keyboard focus changes +\o \l {Flickable} - Provides a surface that can be "flicked" +\o \l {Flipable} - Provides a surface that produces "flipping" effects +\o \l {PinchArea} - Enables simple pinch gesture handling +\o \l {MultiPointTouchArea} - Enables handling of multiple touch points +\endlist + +\section1 Positioners and Repeater +\list +\o \l {Column} - Arranges its children vertically +\o \l {Row} - Arranges its children horizontally +\o \l {Grid} - Positions its children in a grid +\o \l {Flow} - Positions its children with wrapping support +\o \l {Repeater} - Uses a model to create multiple components +\endlist + +\section1 Transformations +\list +\o \l {Scale} - Assigns item scaling behaviors +\o \l {Rotation} - Assigns item rotation behaviors +\o \l {Translate} - Assigns item translation behaviors +\endlist + +\section1 States +\list +\o \l {State} - Defines sets of configurations of objects and properties +\o \l {PropertyChanges} - Describes property changes within a state +\o \l {StateGroup} - Contains a set of states and state transitions +\o \l {StateChangeScript} - Allows script binding in a state +\o \l {ParentChange} - Re-parent an Item in a state change +\o \l {AnchorChanges} - Change the anchors of an item in a state +\endlist + +\section1 Animation and Transitions +\list +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation +\endlist + +Elements that animate properties based on data types +\list +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes +\o \l {PathAnimation} - Animates position along a path +\endlist + +Elements that provide lower-level animation control +\list +\o \l {PathInterpolator} - Allows manual animation along a path +\o \l {AnimationController} - Allows manual control of animation progress +\endlist + +\section1 Models and Data Handling +\list +\o \l {QtQuick2::ListModel}{ListModel} - Defines a list of data +\o \l {QtQuick2::ListElement}{ListElement} - Defines a data item in a \l {QtQuick2::ListModel}{ListModel} +\o \l {VisualItemModel} - Contains items that already defines its own visual delegate +\o \l {VisualDataModel} - Encapsulates a model and a delegate +\o \l {XmlListModel} - Specifies a model using XPath expressions +\o \l {XmlRole} - Specifies a role for an \l {XmlListModel} +\o \l {Binding} - Binds any value to any property +\o \l {Package} - Collection that enables sharing of items within different views +\endlist + +\section1 Views +\list +\o \l {ListView} - Provides a list visualization of a model +\o \l {GridView} - Provides a grid visualization of a model +\o \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information. +\endlist + +\section1 Path Definition +\list +\o \l {Path} - Defines a path used by \l {PathView} +\o \l {PathLine} - Defines a line in \l {Path} +\o \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} +\o \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} +\o \l {PathArc} - Defines an arc in a \l {Path} +\o \l {PathCurve} - Defines a point on a Catmull-Rom curve in a \l {Path} +\o \l {PathSvg} - Defines a sub-path specified as a SVG path data string in a \l {Path} +\o \l {PathAttribute} - Allows the setting of attributes along a \l {Path} +\o \l {PathPercent} - Modifies the item distribution along a \l {Path} +\endlist + +\section1 Utility +\list +\o \l {Connections} - Explicitly connects signals and signal handlers +\o \l {Timer} - Provides timed triggers +\o \l {QmlGlobalQtObject}{Qt} - The QML global Qt object provides useful enums and functions from Qt. +\o \l {WorkerScript} - Enables the use of threads in QML +\o \l {Loader} - Controls the loading of items or components +\endlist + +\section1 Graphical Effects +\list +\o \l {ShaderEffect} - Allows GLSL shaders to be used as graphical effects +\o \l {ShaderEffectSource} - Usable as a texture in ShaderEffect +\o \l {GridMesh} - Generates a gird mesh of vertices for use by ShaderEffect +\o The \l{QtQuick.Particles 2} module provides a set of Particle System elements for QtQuick 2 +\endlist + +\section1 Accessibility +\list +\o \l {Accessible} - Attached property to make components accessible +\endlist + +*/ + + +/*! + \group qml-groups + \title Groups Of Related QML Elements + + \brief If you know what kind of QML element you want (Basic Visual, + Interaction, Animation, etc), look here. + + This is a list of functional groups of QML elements. + + \generatelist{related} + +*/ + +/*! + \group qml-basic-visual-elements + \title Basic QML Visual Elements + \ingroup qml-groups + + \brief Elements for constructing basic visual items. + + \generatelist{related} + +*/ + +/*! + \group qml-basic-interaction-elements + \title Basic QML Interaction Elements + \ingroup qml-groups + + \brief Elements for handling basic interactions. + + \generatelist{related} + +*/ + +/*! + \group qml-state-elements + \title QML State Elements + \ingroup qml-groups + + \brief Elements for handling state changes. + + \generatelist{related} + +*/ + +/*! + \group qml-event-elements + \title QML Event Elements + \ingroup qml-groups + + \brief Elements for handling events. + + \generatelist{related} + +*/ + +/*! + \group qml-animation-transition + \title QML Animation and Transition Elements + \ingroup qml-groups + + \brief Elements for handling animations and transitions. + + \generatelist{related} + +*/ + +/*! + \group qml-working-with-data + \title Working With Data in QML + \ingroup qml-groups + + \brief Elements for working with data. + + \generatelist{related} + +*/ + +/*! + \group qml-view-elements + \title QML View Elements + \ingroup qml-groups + + \brief Elements for handling views. + + \generatelist{related} + +*/ + +/*! + \group qml-positioning-elements + \title QML Positioning Elements + \ingroup qml-groups + + \brief Elements for positioning items. + + \generatelist{related} + +*/ + +/*! + \group qml-utility-elements + \title QML Utility Elements + \ingroup qml-groups + + \brief Elements for handling misc operations. + + \generatelist{related} + +*/ + +/*! + \group qml-transform-elements + \title QML Transform Elements + \ingroup qml-groups + + \brief Elements for handling transformations. + + \generatelist{related} + +*/ + +/*! + \group qml-particle-elements + \title QML Particle Elements + \ingroup qml-groups + + \brief Elements for handling particle effects. + + This is the QtQuick 1.0 particle system, incompatible with QtQuick 2.0 + + There is a completely separate \l{QtQuick.Particles 2}{QtQuick 2.0 particle system} + + \generatelist{related} + +*/ + +/*! + \group qml-shader-elements + \title QML Shader Elements + \ingroup qml-groups + + \brief Elements for using OpenGL shading language code together with the QML code. + + \generatelist{related} + +*/ + +/*! + \group qml-shader-elements + \title QML Shader Elements + \ingroup qml-groups + + \brief Elements for using OpenGL shading language code together with the QML code. + + \generatelist{related} + +*/ diff --git a/doc/src/qtquick2/focus.qdoc b/doc/src/qtquick2/focus.qdoc new file mode 100644 index 0000000000..05d797e7be --- /dev/null +++ b/doc/src/qtquick2/focus.qdoc @@ -0,0 +1,206 @@ +/**************************************************************************** +** +** 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 +\i 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 +\o Qt receives the key action and generates a key event. +\o If the Qt widget containing the \l QDeclarativeView has focus, the key event +is delivered to it. Otherwise, regular Qt key handling continues. +\o The key event is delivered by the scene to the QML \l Item with +\i {active focus}. If no Item has active focus, the key event is +\l {QEvent::ignore()}{ignored} and regular Qt key handling continues. +\o 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/src/snippets/declarative/focus/rectangle.qml simple key event +\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event end + +\o 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/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/focus/widget.qml window + +The MyWidget code: +\snippet doc/src/snippets/declarative/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 \i {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/src/snippets/declarative/focus/myfocusscopewidget.qml widget in focusscope + +\image declarative-qmlfocus3.png + + +Conceptually \i {focus scopes} are quite simple. +\list +\o 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. +\o 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/src/snippets/declarative/focus/clickablewidget.qml clickable window + +The MyClickableWidget code: +\snippet doc/src/snippets/declarative/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/src/snippets/declarative/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. +*/ diff --git a/doc/src/qtquick2/modelview.qdoc b/doc/src/qtquick2/modelview.qdoc new file mode 100644 index 0000000000..56c726eab8 --- /dev/null +++ b/doc/src/qtquick2/modelview.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** 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 QML 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 \i models, \i views, and \i 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 +\o \bold Model - contains the data and its structure. There are several QML +elements for creating models. +\o \bold View - a container that displays the data. The view might +display the data in a list or a grid. +\o \bold 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 + \o \l{ListView} - arranges items in a horizontal or vertical list + \o \l{GridView} - arranges items in a grid within the available space + \o \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 \i 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/src/snippets/declarative/listview-decorations.qml model + \snippet doc/src/snippets/declarative/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/src/snippets/declarative/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 \i 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/src/snippets/declarative/listview-sections.qml model + \snippet doc/src/snippets/declarative/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/src/snippets/declarative/listview-sections.qml section + \image listview-section.png + +\keyword qml-view-delegate +\section1 View Delegates + + Views need a \i 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/src/snippets/declarative/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 \i{language} of + the model, and the color of one of the fields depends on the property + \i{fruit_color} of the view. + + \snippet doc/src/snippets/declarative/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, \i type and \i age, and a + ListView with a delegate that binds to these roles to display their values: + + \snippet doc/src/snippets/declarative/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 \i model name + instead. For example, if a \l Text element had \i type or \i age properties, + the text in the above example would display those property values instead of + the \i type and \i 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 \i 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 \i modelData role. The \i + modelData role is also provided for models that have only one role. In this + case the \i 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/src/snippets/declarative/qml-data-models/listelements.qml model + + The above model has two roles, \i name and \i cost. These can be bound + to by a ListView delegate, for example: + + \snippet doc/src/snippets/declarative/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/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model + \dots + \snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area + + When the MouseArea is clicked, \c fruitModel will have two roles, \i cost and \i 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, \i title, \i link and \i 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/src/snippets/declarative/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 \i + myText text. Note the use of the fully qualified \i model.color property to + avoid clashing with \i 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/src/snippets/declarative/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. + + +*/ diff --git a/doc/src/qtquick2/mouseevents.qdoc b/doc/src/qtquick2/mouseevents.qdoc new file mode 100644 index 0000000000..d981c7c1dd --- /dev/null +++ b/doc/src/qtquick2/mouseevents.qdoc @@ -0,0 +1,118 @@ +/**************************************************************************** +** +** 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 QML Mouse Events +\brief handling mouse events in QML + +\tableofcontents + +\section1 Mouse Elements + +\list +\o \l{MouseArea} Element +\o \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/src/snippets/declarative/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 +\o canceled +\o clicked +\o doubleClicked +\o entered +\o exited +\o positionChanged +\o pressAndHold +\o pressed +\o released +\endlist + +These signals have signal handlers that are invoked when the signals are emitted. +\snippet doc/src/snippets/declarative/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/src/snippets/declarative/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. +*/ diff --git a/doc/src/qtquick2/positioners.qdoc b/doc/src/qtquick2/positioners.qdoc new file mode 100644 index 0000000000..c7110f7cf9 --- /dev/null +++ b/doc/src/qtquick2/positioners.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** 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 +\o \l{#Column}{Column} arranges its children in a column +\o \l{#Row}{Row} arranges its children in a row +\o \l{#Grid}{Grid} arranges its children in a grid +\o \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/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/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}. +*/ diff --git a/doc/src/qtquick2/qmltexthandling.qdoc b/doc/src/qtquick2/qmltexthandling.qdoc new file mode 100644 index 0000000000..876ab3c42f --- /dev/null +++ b/doc/src/qtquick2/qmltexthandling.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** 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 +\ingroup QML Features + +\title QML Text Handling and Validators +\brief elements that accept and handle text input + +\tableofcontents + +\section1 Text Elements + +\list +\o \l{Text} +\o \l{TextInput} +\o \l{TextEdit} +\endlist + +\section1 Validators +\list +\o \l{IntValidator} +\o \l{DoubleValidator} +\o \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/src/snippets/declarative/texthandling.qml int validator +The validator elements bind to \c {TextInput}'s \c validator property. + +\snippet doc/src/snippets/declarative/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. + +*/ diff --git a/doc/src/qtquick2/qtquick-intro.qdoc b/doc/src/qtquick2/qtquick-intro.qdoc new file mode 100644 index 0000000000..8aeab7e199 --- /dev/null +++ b/doc/src/qtquick2/qtquick-intro.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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{QtDeclarative 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 QtDeclarative Module + +To make Qt Quick possible, Qt introduces the \l{QtDeclarative} module. The +module creates a JavaScript runtime that QML runs under with a Qt based backend. +Because QtDeclarative 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 QtDeclarative 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 +\o Get started with Qt Quick application development quickly and easily with +examples, tutorials, and project wizards. +\o 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. +\o 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. +\o Build and deploy Qt Quick applications that target multiple desktop and +mobile platforms, such as Microsoft Windows, Mac OS X, Linux, and Maemo. +\o 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. +\o Deploy applications to mobile devices and create application installation +packages for Maemo devices that can be published in the Ovi Store +and other channels. +\o 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 +\o \l{Qt Quick Licensing Information} +\endlist +*/ diff --git a/doc/src/qtquick2/qtquick2.qdoc b/doc/src/qtquick2/qtquick2.qdoc new file mode 100644 index 0000000000..6a1b7999c9 --- /dev/null +++ b/doc/src/qtquick2/qtquick2.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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 QtDeclarative + module. These elements work with the Scenegraph renderer and + their own canvas. + */ diff --git a/doc/src/qtquick2/righttoleft.qdoc b/doc/src/qtquick2/righttoleft.qdoc new file mode 100644 index 0000000000..b2cff57ee0 --- /dev/null +++ b/doc/src/qtquick2/righttoleft.qdoc @@ -0,0 +1,196 @@ +/**************************************************************************** +** +** 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 QML 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/src/snippets/declarative/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/src/snippets/declarative/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{QML 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/src/snippets/declarative/righttoleft.qml 2 + +Or set all child elements to also inherit the layout direction: + +\snippet doc/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/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 + +*/ diff --git a/doc/src/qtquick2/shaders.qdoc b/doc/src/qtquick2/shaders.qdoc new file mode 100644 index 0000000000..825eb29ac1 --- /dev/null +++ b/doc/src/qtquick2/shaders.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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 +*/ diff --git a/doc/src/qtquick2/states.qdoc b/doc/src/qtquick2/states.qdoc new file mode 100644 index 0000000000..559b4facac --- /dev/null +++ b/doc/src/qtquick2/states.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** 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 +\ingroup qml-features +\title QML States +\brief creating and setting states in QML + +\target qmlstates +\section1 States Elements +\list +\o \l State +\o \l PropertyChanges +\o \l StateGroup +\o \l StateChangeScript +\o \l ParentChange +\o \l AnchorChanges +\endlist + +Many user interface designs are \i 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, \i states are a set of property configurations defined in a \l State +element. Different configurations could, for example: + +\list +\o Show some UI elements and hide others +\o Present different available actions to the user +\o Start, stop, or pause animations +\o Execute some script required in the new state +\o Change a property value for a particular item +\o 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/src/snippets/declarative/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/src/snippets/declarative/states.qml switch states + +The State element is not limited to performing modifications on property values. +It can also: +\list +\o Run some script using \l StateChangeScript +\o Override an existing signal handler for an object using \l PropertyChanges +\o Re-parent an \l Item using \l ParentChange +\o Modify anchor values using \l AnchorChanges +\endlist + +\section1 The Default State + +Every \l Item based component has a \c state property and a \i{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/src/snippets/declarative/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 +\o The state is fast forwarded to determine the complete set of end values. +\o The state is rewound. +\o 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 \i model or a Loader's \i 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. + +*/ diff --git a/doc/src/qtquick2/writingcomponents.qdoc b/doc/src/qtquick2/writingcomponents.qdoc new file mode 100644 index 0000000000..64d28eff0b --- /dev/null +++ b/doc/src/qtquick2/writingcomponents.qdoc @@ -0,0 +1,498 @@ +/**************************************************************************** +** +** 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/src/snippets/declarative/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 +\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 +\o \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{QDeclarativeExtensionPlugin}{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 +\o \bold 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} +\o \bold Methods of JavaScript code can be invoked internally or externally (for example, + \l Animation has a \l {Animation::}{start()} method) +\o \bold 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 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/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 \o QML Type Name \o Default value \o C++ Type Name +\row \o \l int \o 0 \o int +\row \o \l bool \o \c false \o bool +\row \o \l double \o 0.0 \o double +\row \o \l real \o 0.0 \o double +\row \o \l string \o "" (empty string) \o QString +\row \o \l url \o "" (empty url) \o QUrl +\row \o \l color \o #000000 (black) \o QColor +\row \o \l date \o \c undefined \o QDateTime +\row \o \l variant \o \c undefined \o 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/src/snippets/declarative/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/src/snippets/declarative/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 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/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 +\o onClicked +\o onHovered +\o 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 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0 +\o \snippet doc/src/snippets/declarative/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 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0 +\o \snippet doc/src/snippets/declarative/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/src/snippets/declarative/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/src/snippets/declarative/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. + +*/ |