doc/src/declarative/qdeclarativestates.qdoc

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