src/quick/doc/src/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 \page qtquick-states.html
  30 \title States
  31 \brief Creating and setting states
  32
  33 \target qmlstates
  34 \section1 States Elements
  35 \list
  36 \li \l State
  37 \li \l PropertyChanges
  38 \li \l StateGroup
  39 \li \l StateChangeScript
  40 \li \l ParentChange
  41 \li \l AnchorChanges
  42 \endlist
  43
  44 Many user interface designs are \e state driven; interfaces have configurations
  45 that differ depending on the current state. For example, a traffic signal will
  46 configure its flags or lights depending on its state. While in the signal's
  47 \c stop state, a red light will turn on while the yellow and the green lights
  48 will turn off. In the \c caution state, the yellow light is on while the other
  49 lights are turned off.
  50
  51 In QML, \e states are a set of property configurations defined in a \l State
  52 element. Different configurations could, for example:
  53
  54 \list
  55 \li Show some UI elements and hide others
  56 \li Present different available actions to the user
  57 \li Start, stop, or pause animations
  58 \li Execute some script required in the new state
  59 \li Change a property value for a particular item
  60 \li Show a different view or screen
  61 \endlist
  62
  63 All \l {Item}-based objects have a \c state property, and can specify additional
  64 states by adding new \c State objects to the item's \l {Item::}{states}
  65 property. Each state within a component has a unique \c name, an empty string
  66 being the default. To change the current state
  67 of an item, set the \l {Item::}{state} property to the name of the state.
  68
  69 Non-Item objects may use states through the \l StateGroup element.
  70
  71 \section1 Creating States
  72
  73 To create a state, add a \l State object to the item's \l {Item::}{states} property,
  74 which holds a list of states for that item.
  75
  76 A warning \c signal component may have two states, the \c NORMAL and the
  77 \c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the
  78 signal should be \c green and the warning \c flag is down. Meanwhile, in the
  79 \c CRITICAL state, the \c color should be \c red and the flag is \c up. We may
  80 model the states using the \c State element and the color and flag
  81 configurations with the \c PropertyChanges element.
  82 \snippet doc/snippets/qml/states.qml signal states
  83 The \l PropertyChanges element will change the values of object properties.
  84 Objects are referenced through their \l {qml-id}{id}. Objects outside
  85 the component are also referenced using the \c id property, exemplified by the
  86 property change to the external \c flag object.
  87
  88 Further, the state may change by assigning the \c state property with the
  89 appropriate signal state. A state switch could be in a \l MouseArea element,
  90 assigning a different state whenever the signal receives a mouse click.
  91 \snippet doc/snippets/qml/states.qml switch states
  92
  93 The State element is not limited to performing modifications on property values.
  94 It can also:
  95 \list
  96 \li Run some script using \l StateChangeScript
  97 \li Override an existing signal handler for an object using \l PropertyChanges
  98 \li Re-parent an \l Item using \l ParentChange
  99 \li Modify anchor values using \l AnchorChanges
 100 \endlist
 101
 102 \section1 The Default State
 103
 104 Every \l Item based component has a \c state property and a \e{default state}.
 105 The default state is the empty string (\c{""}) and contains all of an item's
 106 initial property values. The default state is useful for managing property
 107 values before state changes. Setting the \c state property to an empty string
 108 will load the default state.
 109
 110 \section1 The \c when Property
 111
 112 For convenience, the \l State element has a \c when property that can bind to
 113 expressions to change the state whenever the bound expression evaluates to
 114 \c true. The \c when property will revert the state back to the
 115 \l {The Default State}{default state} when the expression evaluates to false.
 116
 117 \snippet doc/snippets/qml/states.qml when property
 118 The \c bell component will change to the \c RINGING state whenever the
 119 \c signal.state is \c CRITICAL.
 120
 121 \section1 Animating State Changes
 122
 123 State changes induce abrupt value changes. The \l Transition element allow
 124 smoother changes during state changes. In transitions, animations and
 125 interpolation behaviors are definable. The
 126 \l {QML Animation and Transitions}{Animation and Transitions} article has more
 127 information about creating state animations.
 128
 129 The \l {declarative/animation/states}{States and Transitions example}
 130 demonstrates how to declare a basic set of states and apply animated
 131 transitions between them.
 132
 133 \l{Using QML Behaviors with States} explains a common problem when using Behaviors
 134 to animate state changes.
 135
 136 \section1 State Fast Forwarding
 137
 138 In order for Transition to correctly animate state changes, it is sometimes necessary
 139 for the engine to fast forward and rewind a state (that is, internally set and unset the state)
 140 before it is finally applied. The process is as follows:
 141
 142 \list 1
 143 \li The state is fast forwarded to determine the complete set of end values.
 144 \li The state is rewound.
 145 \li The state is fully applied, with transitions.
 146 \endlist
 147
 148 In some cases this may cause unintended behavior. For example, a state that changes
 149 a view's \e model or a Loader's \e sourceComponent will set these properties
 150 multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
 151
 152 State fast forwarding should be considered an implementation detail,
 153 and may change in later versions.
 154
 155 */