1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
/*!
\page quick-states.html
\if defined(qtdesignstudio)
\previouspage quick-property-bindings.html
\else
\previouspage quick-connections-backend.html
\endif
\nextpage qmldesigner-pathview-editor.html
\title Adding States
User interfaces are designed to present different interface configurations
in different scenarios, or to modify their appearances in response to user
interaction. Often, there are a set of changes that are made concurrently,
such that the interface could be seen to be internally changing from one
\e state to another.
This applies generally to interfaces regardless of their complexity. A photo
viewer may initially present images in a grid, and when an image is clicked,
change to a detailed state where the individual image is expanded and the
interface is changed to present new options for image editing. At the other
end of the scale, when a button is pressed, it may change to a
\e pressed state in which its color and position are modified so that it
appears to be pressed down.
In QML, any item can change between different states to apply sets of
changes that modify the properties of relevant items. Each state can
present a different configuration that can, for example:
\list
\li Show some UI items and hide others.
\li Present different available actions to the user.
\li Start, stop, or pause animations.
\li Execute some script required in the new state.
\li Change a property value for a particular item.
\li Show a different view.
\endlist
\section1 Creating States
The \uicontrol States view displays the different \l{State}{states}
of a UI, beginning with a \e {base state}.
\image qmldesigner-transitions.png "States view"
To add states, click the \inlineimage plus.png
button. Click the new state to switch to it in \uicontrol {Form Editor},
and then modify the properties of components in \uicontrol Properties.
For example, to change the appearance of a button, you can hide the button
image and show another image in its place. Or, to add movement to the view,
you can change the position of an object in \uicontrol {Form Editor}
and then add animation to the change between the states.
The properties that you change in a state are highlighted with blue color.
In \uicontrol {Text Editor}, you can see the changes recorded as changes
to the base state.
\image qmldesigner-states.png "States and Properties views"
\section1 Setting the Default State
To determine the startup state of the application,
select \inlineimage icons/action-icon.png
to open the \uicontrol Actions menu, and then select
\uicontrol {Set as Default}.
To reset the state later, select \uicontrol Actions >
\uicontrol {Reset Default}.
\section1 Applying States
To determine when a state should be applied, select \uicontrol Actions >
\uicontrol {Set when Condition}. In \uicontrol {Binding Editor}, specify
a \l [QtQuick]{State::when}{when} property for the state. Set the value of
the property to an expression that evaluates to \c true when you want the
state to be applied.
In \uicontrol {Binding Editor}, select the component and property to
create the expression. For example, to change the state when a button is
pressed, you could select a button component and its pressed property.
\image qtquick-states-binding-editor.png "Binding Editor in States view"
\section1 Using States
To keep the QML code clean, you should create a base state that contains all
the types you will need in the application. You can then create states,
in which you hide and show a set of items and modify their properties.
This allows you to:
\list
\li Align items on different views with each other.
\li Avoid excessive property changes. If an item is invisible in the
base state, you must define all changes to its child types as
property changes, which leads to complicated QML code.
\li Minimize the differences between the base state and the other states
to keep the QML code short and readable and to improve performance.
\li Avoid problems when using transitions and animation when changing
states.
\endlist
To create views for an application by using states:
\image qmldesigner-screen-design.png "Designing views"
\list 1
\li In the base state, add all items you will need in the application
(1). While you work on one view, you can click the
\inlineimage eye_open.png
icon to hide items on the canvas that are not part of a view.
\li In \uicontrol States, click the empty slot to create a
new state and give it a name. For example, \c Normal.
\li In \uicontrol Properties (2), deselect the \uicontrol Visibility
check box or set \uicontrol Opacity to 0 for each item that is not
needed in this view. If you specify the setting for the parent item,
all child items inherit it and are also hidden.
\li Create additional states for each view and set the visibility
or opacity of the items in the view.
\li To determine which state is applied when the application starts,
select \uicontrol Actions > \uicontrol {Set as Default}.
\endlist
\if defined(qtcreator)
\include qtquick-states-scxml.qdocinc scxml state machines
\endif
\section1 Animating Transitions Between States
To make movement between states smooth, you can animate transitions.
Animations are created by applying animation types to property values.
Animation types interpolate property values to create smooth transitions.
As well, state transitions may assign animations to state changes.
To create an animation, use an appropriate animation type for the type of
the property that is to be animated, and apply the animation depending on
the type of behavior that is required.
You can drag and drop the following QML types from \uicontrol Library
> \uicontrol {QML Types} > \uicontrol {Qt Quick - Animation} to
\uicontrol Navigator or \uicontrol {Form Editor}:
\list
\li \l [QML] {ColorAnimation}{Color Animation} is a specialized
property animation that defines an animation to be applied when a
color value changes.
\li \l [QML] {NumberAnimation}{Number Animation} is a specialized
property animation that defines an animation to be applied when a
numerical value changes.
\li \l [QML] {ParallelAnimation}{Parallel Animation} enables
animations to be run in parallel.
\li \l [QML] {PauseAnimation}{Pause Animation} is used in a
sequential animation to create a step where nothing happens, for
a specified duration.
\li \l [QML] {PropertyAction}{Property Action} immediately changes
a property value during an animation, without animating the
property change.
\li \l [QML] {PropertyAnimation}{Property Animation} animates
changes in the value of a property.
\li \l [QML] {ScriptAction}{Script Action} defines scripts to be
run during an animation.
\li \l [QML] {SequentialAnimation}{Sequential Animation} enables
animations to be run sequentially.
\endlist
For more information, see \l{Animation and Transitions in Qt Quick}.
\if defined(qtcreator)
For an example of assigning number animations to states, see
\l {Creating a Qt Quick Application}.
\endif
Alternatively, you can use the \uicontrol Timeline view to animate the
properties of UI components and to bind the animations to states. For more
information, see \l {Binding Animations to States}.
*/
|
