src/quick/doc/src/concepts/statesanimations/states.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \group qtquick-states
  30 \page qtquick-statesanimations-states.html
  31 \title Qt Quick States
  32 \brief Creating and setting states
  33
  34 \section1 Related Types
  35 \generatelist{related}
  36
  37 Many user interface designs are \e{state driven}; interfaces have configurations
  38 that differ depending on the current state. For example, a traffic signal will
  39 configure its flags or lights depending on its state. While in the signal's
  40 \c stop state, a red light will turn on while the yellow and the green lights
  41 will turn off. In the \c caution state, the yellow light is on while the other
  42 lights are turned off.
  43
  44 In QML, \e states are a set of property configurations defined in a \l State
  45 element. Different configurations could, for example:
  46
  47 \list
  48 \li Show some UI elements and hide others
  49 \li Present different available actions to the user
  50 \li Start, stop, or pause animations
  51 \li Execute some script required in the new state
  52 \li Change a property value for a particular item
  53 \li Show a different view or screen
  54 \endlist
  55
  56 All \l {Item}-based objects have a \c state property, and can specify additional
  57 states by adding new \c State objects to the item's \l {Item::}{states}
  58 property. Each state within a component has a unique \c name, an empty string
  59 being the default. To change the current state
  60 of an item, set the \l {Item::}{state} property to the name of the state.
  61
  62 Non-Item objects may use states through the \l StateGroup element.
  63
  64 \section1 Creating States
  65
  66 To create a state, add a \l State object to the item's \l {Item::}{states} property,
  67 which holds a list of states for that item.
  68
  69 A warning \c signal component may have two states, the \c NORMAL and the
  70 \c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the
  71 signal should be \c green and the warning \c flag is down. Meanwhile, in the
  72 \c CRITICAL state, the \c color should be \c red and the flag is \c up. We may
  73 model the states using the \c State element and the color and flag
  74 configurations with the \c PropertyChanges element.
  75 \snippet qml/states.qml signal states
  76 The \l PropertyChanges element will change the values of object properties.
  77 Objects are referenced through their
  78 \l{qtqml-syntax-objectattributes.html#the-id-assignment}{id}. Objects outside
  79 the component are also referenced using the \c id property, exemplified by the
  80 property change to the external \c flag object.
  81
  82 Further, the state may change by assigning the \c state property with the
  83 appropriate signal state. A state switch could be in a \l MouseArea element,
  84 assigning a different state whenever the signal receives a mouse click.
  85 \snippet qml/states.qml switch states
  86
  87 The State element is not limited to performing modifications on property values.
  88 It can also:
  89 \list
  90 \li Run some script using \l StateChangeScript
  91 \li Override an existing signal handler for an object using \l PropertyChanges
  92 \li Re-parent an \l Item using \l ParentChange
  93 \li Modify anchor values using \l AnchorChanges
  94 \endlist
  95
  96 \section1 The Default State
  97
  98 Every \l Item based component has a \c state property and a \e{default state}.
  99 The default state is the empty string (\c{""}) and contains all of an item's
 100 initial property values. The default state is useful for managing property
 101 values before state changes. Setting the \c state property to an empty string
 102 will load the default state.
 103
 104 \section1 The \c when Property
 105
 106 For convenience, the \l State element has a \c when property that can bind to
 107 expressions to change the state whenever the bound expression evaluates to
 108 \c true. The \c when property will revert the state back to the
 109 \l {The Default State}{default state} when the expression evaluates to false.
 110
 111 \snippet qml/states.qml when property
 112 The \c bell component will change to the \c RINGING state whenever the
 113 \c signal.state is \c CRITICAL.
 114
 115 \section1 Animating State Changes
 116
 117 State changes induce abrupt value changes. The \l Transition element allow
 118 smoother changes during state changes. In transitions, animations and
 119 interpolation behaviors are definable. The
 120 \l{qtquick-statesanimations-animations.html}
 121 {Animation and Transitions} article has more information about creating state
 122 animations.
 123
 124 The \l {declarative/animation/states}{States and Transitions example}
 125 demonstrates how to declare a basic set of states and apply animated
 126 transitions between them.
 127
 128 \l{qtquick-statesanimations-behaviors.html}{Using QML Behaviors with States}
 129 explains a common problem when using Behaviors to animate state changes.
 130
 131 \section1 State Fast Forwarding
 132
 133 In order for Transition to correctly animate state changes, it is sometimes necessary
 134 for the engine to fast forward and rewind a state (that is, internally set and unset the state)
 135 before it is finally applied. The process is as follows:
 136
 137 \list 1
 138 \li The state is fast forwarded to determine the complete set of end values.
 139 \li The state is rewound.
 140 \li The state is fully applied, with transitions.
 141 \endlist
 142
 143 In some cases this may cause unintended behavior. For example, a state that changes
 144 a view's \e model or a Loader's \e sourceComponent will set these properties
 145 multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
 146
 147 State fast forwarding should be considered an implementation detail,
 148 and may change in later versions.
 149
 150 */