134 /*! |
134 /*! |
135 \qmlclass State QDeclarativeState |
135 \qmlclass State QDeclarativeState |
136 \since 4.7 |
136 \since 4.7 |
137 \brief The State element defines configurations of objects and properties. |
137 \brief The State element defines configurations of objects and properties. |
138 |
138 |
139 A state is specified as a set of batched changes from the default configuration. |
139 A \e state is a set of batched changes from the default configuration. |
140 |
140 |
141 \note setting the state of an object from within another state of the same object is |
141 All items have a default state that defines the default configuration of objects |
|
142 and property values. New states can be defined by adding State items to the \l {Item::states}{states} property to |
|
143 allow items to switch between different configurations. These configurations |
|
144 can, for example, be used to apply different sets of property values or execute |
|
145 different scripts. |
|
146 |
|
147 The following example displays a single \l Rectangle. In the default state, the rectangle |
|
148 is colored black. In the "clicked" state, a PropertyChanges element changes the |
|
149 rectangle's color to red. Clicking within the MouseArea toggles the rectangle's state |
|
150 between the default state and the "clicked" state, thus toggling the color of the |
|
151 rectangle between black and red. |
|
152 |
|
153 \snippet doc/src/snippets/declarative/state.qml 0 |
|
154 |
|
155 Notice the default state is referred to using an empty string (""). |
|
156 |
|
157 States are commonly used together with \l {state-transitions}{Transitions} to provide |
|
158 animations when state changes occur. |
|
159 |
|
160 \note Setting the state of an object from within another state of the same object is |
142 not allowed. |
161 not allowed. |
143 |
162 |
144 \sa {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative |
163 \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative |
145 */ |
164 */ |
146 |
165 |
147 /*! |
166 /*! |
148 \internal |
167 \internal |
149 \class QDeclarativeState |
168 \class QDeclarativeState |
171 d->group->removeState(this); |
190 d->group->removeState(this); |
172 } |
191 } |
173 |
192 |
174 /*! |
193 /*! |
175 \qmlproperty string State::name |
194 \qmlproperty string State::name |
176 This property holds the name of the state |
195 This property holds the name of the state. |
177 |
196 |
178 Each state should have a unique name. |
197 Each state should have a unique name within its item. |
179 */ |
198 */ |
180 QString QDeclarativeState::name() const |
199 QString QDeclarativeState::name() const |
181 { |
200 { |
182 Q_D(const QDeclarativeState); |
201 Q_D(const QDeclarativeState); |
183 return d->name; |
202 return d->name; |
185 |
204 |
186 void QDeclarativeState::setName(const QString &n) |
205 void QDeclarativeState::setName(const QString &n) |
187 { |
206 { |
188 Q_D(QDeclarativeState); |
207 Q_D(QDeclarativeState); |
189 d->name = n; |
208 d->name = n; |
|
209 d->named = true; |
|
210 } |
|
211 |
|
212 bool QDeclarativeState::isNamed() const |
|
213 { |
|
214 Q_D(const QDeclarativeState); |
|
215 return d->named; |
190 } |
216 } |
191 |
217 |
192 bool QDeclarativeState::isWhenKnown() const |
218 bool QDeclarativeState::isWhenKnown() const |
193 { |
219 { |
194 Q_D(const QDeclarativeState); |
220 Q_D(const QDeclarativeState); |
195 return d->when != 0; |
221 return d->when != 0; |
196 } |
222 } |
197 |
223 |
198 /*! |
224 /*! |
199 \qmlproperty bool State::when |
225 \qmlproperty bool State::when |
200 This property holds when the state should be applied |
226 This property holds when the state should be applied. |
201 |
227 |
202 This should be set to an expression that evaluates to true when you want the state to |
228 This should be set to an expression that evaluates to \c true when you want the state to |
203 be applied. |
229 be applied. For example, the following \l Rectangle changes in and out of the "hidden" |
204 |
230 state when the \l MouseArea is pressed: |
205 If multiple states in a group have \c when clauses that evaluate to true at the same time, |
231 |
|
232 \qml |
|
233 Rectangle { |
|
234 id: myRect |
|
235 width: 100; height: 100 |
|
236 color: "red" |
|
237 |
|
238 MouseArea { id: mouseArea; anchors.fill: parent } |
|
239 |
|
240 states: State { |
|
241 name: "hidden"; when: mouseArea.pressed |
|
242 PropertyChanges { target: myRect; opacity: 0 } |
|
243 } |
|
244 } |
|
245 \endqml |
|
246 |
|
247 If multiple states in a group have \c when clauses that evaluate to \c true at the same time, |
206 the first matching state will be applied. For example, in the following snippet |
248 the first matching state will be applied. For example, in the following snippet |
207 \c state1 will always be selected rather than \c state2 when sharedCondition becomes |
249 \c state1 will always be selected rather than \c state2 when sharedCondition becomes |
208 \c true. |
250 \c true. |
209 \qml |
251 \qml |
210 states: [ |
252 states: [ |
227 d->group->updateAutoState(); |
269 d->group->updateAutoState(); |
228 } |
270 } |
229 |
271 |
230 /*! |
272 /*! |
231 \qmlproperty string State::extend |
273 \qmlproperty string State::extend |
232 This property holds the state that this state extends |
274 This property holds the state that this state extends. |
|
275 |
|
276 When a state extends another state, it inherits all the changes of that state. |
233 |
277 |
234 The state being extended is treated as the base state in regards to |
278 The state being extended is treated as the base state in regards to |
235 the changes specified by the extending state. |
279 the changes specified by the extending state. |
236 */ |
280 */ |
237 QString QDeclarativeState::extends() const |
281 QString QDeclarativeState::extends() const |
484 } |
528 } |
485 } |
529 } |
486 // All the local reverts now become part of the ongoing revertList |
530 // All the local reverts now become part of the ongoing revertList |
487 d->revertList << additionalReverts; |
531 d->revertList << additionalReverts; |
488 |
532 |
|
533 #ifndef QT_NO_DEBUG_STREAM |
489 // Output for debugging |
534 // Output for debugging |
490 if (stateChangeDebug()) { |
535 if (stateChangeDebug()) { |
491 foreach(const QDeclarativeAction &action, applyList) { |
536 foreach(const QDeclarativeAction &action, applyList) { |
492 if (action.event) |
537 if (action.event) |
493 qWarning() << " QDeclarativeAction event:" << action.event->typeName(); |
538 qWarning() << " QDeclarativeAction event:" << action.event->typeName(); |
495 qWarning() << " QDeclarativeAction:" << action.property.object() |
540 qWarning() << " QDeclarativeAction:" << action.property.object() |
496 << action.property.name() << "From:" << action.fromValue |
541 << action.property.name() << "From:" << action.fromValue |
497 << "To:" << action.toValue; |
542 << "To:" << action.toValue; |
498 } |
543 } |
499 } |
544 } |
|
545 #endif |
500 |
546 |
501 d->transitionManager.transition(applyList, trans); |
547 d->transitionManager.transition(applyList, trans); |
502 } |
548 } |
503 |
549 |
504 QDeclarativeStateOperation::ActionList QDeclarativeStateOperation::actions() |
550 QDeclarativeStateOperation::ActionList QDeclarativeStateOperation::actions() |