<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- states.qdoc -->
<title>Qt Quick States | Qt Quick 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td >Qt Quick States</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtquick-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#related-types">Related Types</a></li>
<li class="level1"><a href="#creating-states">Creating States</a></li>
<li class="level1"><a href="#the-default-state">The Default State</a></li>
<li class="level1"><a href="#the-when-property">The <code>when</code> Property</a></li>
<li class="level1"><a href="#animating-state-changes">Animating State Changes</a></li>
<li class="level1"><a href="#state-fast-forwarding">State Fast Forwarding</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Quick States</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-statesanimations-states.html-description -->
<div class="descr"> <a name="details"></a>
<a name="related-types"></a>
<h2 id="related-types">Related Types</h2>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-anchorchanges.html">AnchorChanges</a></p></td><td class="tblDescr"><p>Specifies how to change the anchors of an item in a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-parentchange.html">ParentChange</a></p></td><td class="tblDescr"><p>Specifies how to reparent an Item in a state change</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></p></td><td class="tblDescr"><p>Describes new property bindings or values for a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-state.html">State</a></p></td><td class="tblDescr"><p>Defines configurations of objects and properties</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-statechangescript.html">StateChangeScript</a></p></td><td class="tblDescr"><p>Specifies how to run a script in a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-stategroup.html">StateGroup</a></p></td><td class="tblDescr"><p>Provides built-in state support for non-Item types</p></td></tr>
</table></div>
<p>Many user interface designs are <i>state driven</i>; interfaces have configurations that differ depending on the current state. For example, a traffic signal will configure its flags or lights depending on its state. While in the signal's <code>stop</code> state, a red light will turn on while the yellow and the green lights will turn off. In the <code>caution</code> state, the yellow light is on while the other lights are turned off.</p>
<p>In QML, <i>states</i> are a set of property configurations defined in a <a href="qml-qtquick-state.html">State</a> type. Different configurations could, for example:</p>
<ul>
<li>Show some UI components and hide others</li>
<li>Present different available actions to the user</li>
<li>Start, stop, or pause animations</li>
<li>Execute some script required in the new state</li>
<li>Change a property value for a particular item</li>
<li>Show a different view or screen</li>
</ul>
<p>All <a href="qml-qtquick-item.html">Item</a>-based objects have a <code>state</code> property, and can specify additional states by adding new <code>State</code> objects to the item's <a href="qml-qtquick-item.html#states-prop">states</a> property. Each state within a component has a unique <code>name</code>, an empty string being the default. To change the current state of an item, set the <a href="qml-qtquick-item.html#state-prop">state</a> property to the name of the state.</p>
<p>Non-Item objects may use states through the <a href="qml-qtquick-stategroup.html">StateGroup</a> type.</p>
<a name="creating-states"></a>
<h2 id="creating-states">Creating States</h2>
<p>To create a state, add a <a href="qml-qtquick-state.html">State</a> object to the item's <a href="qml-qtquick-item.html#states-prop">states</a> property, which holds a list of states for that item.</p>
<p>A warning <code>signal</code> component may have two states, the <code>NORMAL</code> and the <code>CRITICAL</code> state. Suppose that in the <code>NORMAL</code> state, the <code>color</code> of the signal should be <code>green</code> and the warning <code>flag</code> is down. Meanwhile, in the <code>CRITICAL</code> state, the <code>color</code> should be <code>red</code> and the flag is <code>up</code>. We may model the states using the <code>State</code> type and the color and flag configurations with the <code>PropertyChanges</code> type.</p>
<pre class="qml">
Rectangle {
id: signal
width: 200; height: 200
state: "NORMAL"
states: [
State {
name: "NORMAL"
PropertyChanges { target: signal; color: "green"}
PropertyChanges { target: flag; state: "FLAG_DOWN"}
},
State {
name: "CRITICAL"
PropertyChanges { target: signal; color: "red"}
PropertyChanges { target: flag; state: "FLAG_UP"}
}
]
}
</pre>
<p>The <a href="qml-qtquick-propertychanges.html">PropertyChanges</a> type will change the values of object properties. Objects are referenced through their id. Objects outside the component are also referenced using the <code>id</code> property, exemplified by the property change to the external <code>flag</code> object.</p>
<p>Further, the state may change by assigning the <code>state</code> property with the appropriate signal state. A state switch could be in a <a href="qml-qtquick-mousearea.html">MouseArea</a> type, assigning a different state whenever the signal receives a mouse click.</p>
<pre class="qml">
Rectangle {
id: signalswitch
width: 75; height: 75
color: "blue"
MouseArea {
anchors.fill: parent
onClicked: {
if (signal.state == "NORMAL")
signal.state = "CRITICAL"
else
signal.state = "NORMAL"
}
}
}
</pre>
<p>The State type is not limited to performing modifications on property values. It can also:</p>
<ul>
<li>Run some script using <a href="qml-qtquick-statechangescript.html">StateChangeScript</a></li>
<li>Override an existing signal handler for an object using <a href="qml-qtquick-propertychanges.html">PropertyChanges</a></li>
<li>Re-parent an <a href="qml-qtquick-item.html">Item</a> using <a href="qml-qtquick-parentchange.html">ParentChange</a></li>
<li>Modify anchor values using <a href="qml-qtquick-anchorchanges.html">AnchorChanges</a></li>
</ul>
<a name="the-default-state"></a>
<h2 id="the-default-state">The Default State</h2>
<p>Every <a href="qml-qtquick-item.html">Item</a> based component has a <code>state</code> property and a <i>default state</i>. The default state is the empty string (<code>""</code>) and contains all of an item's initial property values. The default state is useful for managing property values before state changes. Setting the <code>state</code> property to an empty string will load the default state.</p>
<a name="the-when-property"></a>
<h2 id="the-when-property">The <code>when</code> Property</h2>
<p>For convenience, the <a href="qml-qtquick-state.html">State</a> type has a <code>when</code> property that can bind to expressions to change the state whenever the bound expression evaluates to <code>true</code>. The <code>when</code> property will revert the state back to the <a href="qtquick-statesanimations-states.html#the-default-state">default state</a> when the expression evaluates to false.</p>
<pre class="qml">
Rectangle {
id: bell
width: 75; height: 75
color: "yellow"
states: State {
name: "RINGING"
when: (signal.state == "CRITICAL")
PropertyChanges {target: speaker; play: "RING!"}
}
}
</pre>
<p>The <code>bell</code> component will change to the <code>RINGING</code> state whenever the <code>signal.state</code> is <code>CRITICAL</code>.</p>
<a name="animating-state-changes"></a>
<h2 id="animating-state-changes">Animating State Changes</h2>
<p>State changes induce abrupt value changes. The <a href="qmlexampletoggleswitch.html#transition">Transition</a> type allow smoother changes during state changes. In transitions, animations and interpolation behaviors are definable. The <a href="qtquick-statesanimations-animations.html">Animation and Transitions</a> article has more information about creating state animations.</p>
<p>The <a href="qtquick-animation-example.html">Animation</a> example demonstrates how to declare a basic set of states and apply animated transitions between them.</p>
<p><a href="qtquick-statesanimations-behaviors.html">Using Qt Quick Behaviors with States</a> explains a common problem when using Behaviors to animate state changes.</p>
<a name="state-fast-forwarding"></a>
<h2 id="state-fast-forwarding">State Fast Forwarding</h2>
<p>In order for Transition to correctly animate state changes, it is sometimes necessary for the engine to fast forward and rewind a state (that is, internally set and unset the state) before it is finally applied. The process is as follows:</p>
<ol class="1" type="1"><li>The state is fast forwarded to determine the complete set of end values.</li>
<li>The state is rewound.</li>
<li>The state is fully applied, with transitions.</li>
</ol>
<p>In some cases this may cause unintended behavior. For example, a state that changes a view's <i>model</i> or a Loader's <i>sourceComponent</i> will set these properties multiple times (to apply, rewind, and then reapply), which can be relatively expensive.</p>
<p>State fast forwarding should be considered an implementation detail, and may change in later versions.</p>
</div>
<!-- @@@qtquick-statesanimations-states.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
6e2327ca1c896c6d674ae53117299f21
>
files
>
1721
