/usr/share/qt5/doc/qtquick/qtquick-statesanimations-states.html is in qtdeclarative5-doc-html 5.5.1-2ubuntu6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?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.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtquick-index.html">Qt Quick</a></li>
<li>Qt Quick States</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</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>
<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"><span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">signal</span>
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>
<span class="name">state</span>: <span class="string">"NORMAL"</span>
<span class="name">states</span>: [
<span class="type"><a href="qml-qtquick-state.html">State</a></span> {
<span class="name">name</span>: <span class="string">"NORMAL"</span>
<span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">signal</span>; <span class="name">color</span>: <span class="string">"green"</span>}
<span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">flag</span>; <span class="name">state</span>: <span class="string">"FLAG_DOWN"</span>}
},
<span class="type"><a href="qml-qtquick-state.html">State</a></span> {
<span class="name">name</span>: <span class="string">"CRITICAL"</span>
<span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">signal</span>; <span class="name">color</span>: <span class="string">"red"</span>}
<span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">flag</span>; <span class="name">state</span>: <span class="string">"FLAG_UP"</span>}
}
]
}</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"><span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">signalswitch</span>
<span class="name">width</span>: <span class="number">75</span>; <span class="name">height</span>: <span class="number">75</span>
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="type"><a href="qml-qtquick-mousearea.html">MouseArea</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: {
<span class="keyword">if</span> (<span class="name">signal</span>.<span class="name">state</span> <span class="operator">==</span> <span class="string">"NORMAL"</span>)
<span class="name">signal</span>.<span class="name">state</span> <span class="operator">=</span> <span class="string">"CRITICAL"</span>
<span class="keyword">else</span>
<span class="name">signal</span>.<span class="name">state</span> <span class="operator">=</span> <span class="string">"NORMAL"</span>
}
}
}</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"><span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">bell</span>
<span class="name">width</span>: <span class="number">75</span>; <span class="name">height</span>: <span class="number">75</span>
<span class="name">color</span>: <span class="string">"yellow"</span>
<span class="name">states</span>: <span class="name">State</span> {
<span class="name">name</span>: <span class="string">"RINGING"</span>
<span class="name">when</span>: (<span class="name">signal</span>.<span class="name">state</span> <span class="operator">==</span> <span class="string">"CRITICAL"</span>)
<span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> {<span class="name">target</span>: <span class="name">speaker</span>; <span class="name">play</span>: <span class="string">"RING!"</span>}
}
}</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 States and Transitions 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">
<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> 2015 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>
|