diff options
author | Bea Lam <bea.lam@nokia.com> | 2012-07-03 11:45:26 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-07-05 01:47:53 +0200 |
commit | 422033971f5d74b8ed7dcf3492379403d4d0eb3d (patch) | |
tree | 0b4e599f47fae7ec482e06bc34091c29c9853ab1 /src/quick/doc/src/concepts/statesanimations/states.qdoc | |
parent | 7481adc7d72665de7873b99f58764f2a6b906c9c (diff) |
Reorganize "concept" pages in QtQuick docs
This removes concepts/topic.qdoc and move this content into individual
concept topic pages under individual directories for each concept to
avoid having a really long "concepts" index page.
This change also:
- Moves components.qdoc ("Defining reusable components") into the
appdevguide/ since it's not specific to QtQuick features - it's more
about how to use a QtQml feature to build QML apps.
- Moves the part of qtqml/doc/src/cppintegration/data.qdoc that
discusses how to use C++ models with QtQuick views into
quick/doc/src/concepts/modelviewsdata/data-cppmodels.qdoc.
Change-Id: Id18a1d56acaaac41714c13cbc94bb3b80f337355
Reviewed-by: Chris Adams <christopher.adams@nokia.com>
Diffstat (limited to 'src/quick/doc/src/concepts/statesanimations/states.qdoc')
-rw-r--r-- | src/quick/doc/src/concepts/statesanimations/states.qdoc | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/src/quick/doc/src/concepts/statesanimations/states.qdoc b/src/quick/doc/src/concepts/statesanimations/states.qdoc new file mode 100644 index 0000000000..e3ac12549c --- /dev/null +++ b/src/quick/doc/src/concepts/statesanimations/states.qdoc @@ -0,0 +1,150 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qtquick-states +\page qtquick-statesanimations-states.html +\title Qt Quick States +\brief Creating and setting states + +\section1 Related Types +\generatelist{related} + +Many user interface designs are \e{state driven}; interfaces have configurations +that differ depending on the current state. For example, a traffic signal will +configure its flags or lights depending on its state. While in the signal's +\c stop state, a red light will turn on while the yellow and the green lights +will turn off. In the \c caution state, the yellow light is on while the other +lights are turned off. + +In QML, \e states are a set of property configurations defined in a \l State +element. Different configurations could, for example: + +\list +\li Show some UI elements and hide others +\li Present different available actions to the user +\li Start, stop, or pause animations +\li Execute some script required in the new state +\li Change a property value for a particular item +\li Show a different view or screen +\endlist + +All \l {Item}-based objects have a \c state property, and can specify additional +states by adding new \c State objects to the item's \l {Item::}{states} +property. Each state within a component has a unique \c name, an empty string +being the default. To change the current state +of an item, set the \l {Item::}{state} property to the name of the state. + +Non-Item objects may use states through the \l StateGroup element. + +\section1 Creating States + +To create a state, add a \l State object to the item's \l {Item::}{states} property, +which holds a list of states for that item. + +A warning \c signal component may have two states, the \c NORMAL and the +\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the +signal should be \c green and the warning \c flag is down. Meanwhile, in the +\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may +model the states using the \c State element and the color and flag +configurations with the \c PropertyChanges element. +\snippet qml/states.qml signal states +The \l PropertyChanges element will change the values of object properties. +Objects are referenced through their +\l{qtqml-syntax-objectattributes.html#the-id-assignment}{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 qml/states.qml switch states + +The State element is not limited to performing modifications on property values. +It can also: +\list +\li Run some script using \l StateChangeScript +\li Override an existing signal handler for an object using \l PropertyChanges +\li Re-parent an \l Item using \l ParentChange +\li Modify anchor values using \l AnchorChanges +\endlist + +\section1 The Default State + +Every \l Item based component has a \c state property and a \e{default state}. +The default state is the empty string (\c{""}) and contains all of an item's +initial property values. The default state is useful for managing property +values before state changes. Setting the \c state property to an empty string +will load the default state. + +\section1 The \c when Property + +For convenience, the \l State element has a \c when property that can bind to +expressions to change the state whenever the bound expression evaluates to +\c true. The \c when property will revert the state back to the +\l {The Default State}{default state} when the expression evaluates to false. + +\snippet qml/states.qml when property +The \c bell component will change to the \c RINGING state whenever the +\c signal.state is \c CRITICAL. + +\section1 Animating State Changes + +State changes induce abrupt value changes. The \l Transition element allow +smoother changes during state changes. In transitions, animations and +interpolation behaviors are definable. The +\l{qtquick-statesanimations-animations.html} +{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{qtquick-statesanimations-behaviors.html}{Using QML Behaviors with States} +explains a common problem when using Behaviors to animate state changes. + +\section1 State Fast Forwarding + +In order for Transition to correctly animate state changes, it is sometimes necessary +for the engine to fast forward and rewind a state (that is, internally set and unset the state) +before it is finally applied. The process is as follows: + +\list 1 +\li The state is fast forwarded to determine the complete set of end values. +\li The state is rewound. +\li The state is fully applied, with transitions. +\endlist + +In some cases this may cause unintended behavior. For example, a state that changes +a view's \e model or a Loader's \e sourceComponent will set these properties +multiple times (to apply, rewind, and then reapply), which can be relatively expensive. + +State fast forwarding should be considered an implementation detail, +and may change in later versions. + +*/ |