Update copyright headers
[qt:qt.git] / doc / src / declarative / qdeclarativestates.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
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 \l{Using QML Behaviors with States} explains a common problem when using Behaviors
137 to animate state changes.
138
139 \section1 State Fast Forwarding
140
141 In order for Transition to correctly animate state changes, it is sometimes necessary
142 for the engine to fast forward and rewind a state (that is, internally set and unset the state)
143 before it is finally applied. The process is as follows:
144
145 \list 1
146 \o The state is fast forwarded to determine the complete set of end values.
147 \o The state is rewound.
148 \o The state is fully applied, with transitions.
149 \endlist
150
151 In some cases this may cause unintended behavior. For example, a state that changes
152 a view's \i model or a Loader's \i sourceComponent will set these properties
153 multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
154
155 State fast forwarding should be considered an implementation detail,
156 and may change in later versions.
157
158 */