doc/src/declarative/qdeclarativestates.qdoc

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