/usr/share/qt5/doc/qtqml/qmlstatemachine.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 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 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- statemachine.qdoc -->
<title>The Declarative State Machine Framework | Qt QML 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="qtqml-index.html">Qt QML</a></li>
<li>The Declarative State Machine Framework</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="#using-both-qtquick-and-qtqml-statemachine-imports">Using both QtQuick and QtQml.StateMachine imports</a></li>
<li class="level1"><a href="#a-simple-state-machine">A Simple State Machine</a></li>
<li class="level1"><a href="#state-machines-that-finish">State Machines That Finish</a></li>
<li class="level1"><a href="#sharing-transitions">Sharing Transitions</a></li>
<li class="level1"><a href="#using-history-states">Using History States</a></li>
<li class="level1"><a href="#using-parallel-states">Using Parallel States</a></li>
<li class="level1"><a href="#exiting-a-composite-state">Exiting a Composite State</a></li>
<li class="level1"><a href="#targetless-transitions">Targetless Transitions</a></li>
<li class="level1"><a href="#related-information">Related Information</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">The Declarative State Machine Framework</h1>
<span class="subtitle"></span>
<!-- $$$qmlstatemachine.html-description -->
<div class="descr"> <a name="details"></a>
<p>The Declarative State Machine Framework provides types for creating and executing state graphs in QML. It is similar to the C++ State Machine framework based on Harel's Statecharts: A visual formalism for complex systems, which is also the basis for UML state diagrams. Like its C++ counterpart, the framework provides an API and execution model based on State Chart XML (SCXML) to embed the elements and semantics of statecharts in QML applications.</p>
<p>For user interfaces with multiple visual states, independent of the application's logical state, consider using QML States and Transitions.</p>
<p>These following QML types are provided by framework to create event-driven state machines:</p>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-finalstate.html">FinalState</a></p></td><td class="tblDescr"><p>Provides a final state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-historystate.html">HistoryState</a></p></td><td class="tblDescr"><p>Type provides a means of returning to a previously active substate</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></p></td><td class="tblDescr"><p>Type provides a transition based on a Qt signal</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-state.html">State</a></p></td><td class="tblDescr"><p>Provides a general-purpose state for StateMachine</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></p></td><td class="tblDescr"><p>Provides a hierarchical finite state machine</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtqml-statemachine-timeouttransition.html">TimeoutTransition</a></p></td><td class="tblDescr"><p>Type provides a transition based on a timer</p></td></tr>
</table></div>
<a name="using-both-qtquick-and-qtqml-statemachine-imports"></a>
<h2 id="using-both-qtquick-and-qtqml-statemachine-imports">Using both QtQuick and QtQml.StateMachine imports</h2>
<p><b>Warning:</b> If you're attempting to import both QtQuick and <i><a href="qtqml-qmlmodule.html">QtQml</a>.<a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></i> in one single QML file, make sure to import <i><a href="qtqml-qmlmodule.html">QtQml</a>.<a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></i> <i>last</i>. This way, the <i>State</i> type is provided by the Declarative State Machine Framework and not by QtQuick:</p>
<pre class="qml">import QtQuick 2.0
import QtQml.StateMachine 1.0
<span class="type"><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></span> {
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="comment">// okay, is of type QtQml.StateMachine.State</span>
}
}</pre>
<p>Alternatively, you can import <i><a href="qtqml-qmlmodule.html">QtQml</a>.<a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></i> into a separate namespace to avoid any ambiguity with QtQuick's <i>State</i> item:</p>
<pre class="qml">import QtQuick 2.0
import QtQml.StateMachine 1.0 as DSM
<span class="type">DSM</span>.StateMachine {
<span class="type">DSM</span>.State {
<span class="comment">// ...</span>
}
}</pre>
<a name="a-simple-state-machine"></a>
<h2 id="a-simple-state-machine">A Simple State Machine</h2>
<p>To demonstrate the core functionality of the State Machine API, let's look at an example: A state machine with three states, <code>s1</code>, <code>s2</code> and <code>s3</code>. The state machine is controlled by a single Button; when the button is clicked, the machine transitions to another state. Initially, the state machine is in state <code>s1</code>. The following is a state chart showing the different states in our example.</p>
<p class="centerAlign"><img src="images/statemachine-button.png" alt="" /></p><p>The following snippet shows the code needed to create such a state machine.</p>
<pre class="qml"> <span class="type">Button</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">id</span>: <span class="name">button</span>
<span class="comment">// change the button label to the active state id</span>
<span class="name">text</span>: <span class="name">s1</span>.<span class="name">active</span> ? <span class="string">"s1"</span> : <span class="name">s2</span>.<span class="name">active</span> ? <span class="string">"s2"</span> : <span class="string">"s3"</span>
}
<span class="type"><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></span> {
<span class="name">id</span>: <span class="name">stateMachine</span>
<span class="comment">// set the initial state</span>
<span class="name">initialState</span>: <span class="name">s1</span>
<span class="comment">// start the state machine</span>
<span class="name">running</span>: <span class="number">true</span>
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="comment">// create a transition from s1 to s2 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s2</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s2</span>
<span class="comment">// create a transition from s2 to s3 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s3</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s3</span>
<span class="comment">// create a transition from s3 to s1 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s1</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s3 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s3 exited"</span>)
}
}</pre>
<p>The state machine runs asynchronously to become part of your application's event loop.</p>
<a name="state-machines-that-finish"></a>
<h2 id="state-machines-that-finish">State Machines That Finish</h2>
<p>The state machine defined in the previous section never finishes. In order for a state machine to be able to finish, it needs to have a top-level <i>final</i> state (<a href="qml-qtqml-statemachine-finalstate.html">FinalState</a> object). When the state machine enters the top-level final state, the machine emits the <a href="qml-qtqml-statemachine-state.html#finished-signal">finished</a> signal and halts.</p>
<p>All you need to do to introduce a final state in the graph is create a <a href="qml-qtqml-statemachine-finalstate.html">FinalState</a> object and use it as the target of one or more transitions.</p>
<a name="sharing-transitions"></a>
<h2 id="sharing-transitions">Sharing Transitions</h2>
<p>Assume we wanted the user to be able to quit the application at any time by clicking a Quit button. In order to achieve this, we need to create a final state and make it the target of a transition associated with the Quit button's <i>clicked()</i> signal. We could add a transition for each state; however, this seems redundant and one would also have to remember to add such a transition from every new state that is added in the future.</p>
<p>We can achieve the same behavior (namely that clicking the Quit button quits the state machine, regardless of which state the state machine is in) by grouping states <code>s1</code>, <code>s2</code> and <code>s3</code>. This is done by creating a new top-level state and making the three original states children of the new state. The following diagram shows the new state machine.</p>
<p class="centerAlign"><img src="images/statemachine-button-nested.png" alt="" /></p><p>The three original states have been renamed <code>s11</code>, <code>s12</code> and <code>s13</code> to reflect that they are now childrens of the new top-level state, <code>s1</code>. Child states implicitly inherit the transitions of their parent state. This means it is now sufficient to add a single transition from <code>s1</code> to the final state, <code>s2</code>. New states added to <code>s1</code> will automatically inherit this transition.</p>
<p>All that's needed to group states is to specify the proper parent when the state is created. You also need to specify which of the child states is the initial one (the child state the state machine should enter when the parent state is the target of a transition).</p>
<pre class="qml"> <span class="type">Row</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">spacing</span>: <span class="number">2</span>
<span class="type">Button</span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="comment">// change the button label to the active state id</span>
<span class="name">text</span>: <span class="name">s11</span>.<span class="name">active</span> ? <span class="string">"s11"</span> : <span class="name">s12</span>.<span class="name">active</span> ? <span class="string">"s12"</span> : <span class="string">"s13"</span>
}
<span class="type">Button</span> {
<span class="name">id</span>: <span class="name">quitButton</span>
<span class="name">text</span>: <span class="string">"quit"</span>
}
}
<span class="type"><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></span> {
<span class="name">id</span>: <span class="name">stateMachine</span>
<span class="comment">// set the initial state</span>
<span class="name">initialState</span>: <span class="name">s1</span>
<span class="comment">// start the state machine</span>
<span class="name">running</span>: <span class="number">true</span>
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="comment">// set the initial state</span>
<span class="name">initialState</span>: <span class="name">s11</span>
<span class="comment">// create a transition from s1 to s2 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s2</span>
<span class="name">signal</span>: <span class="name">quitButton</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 exited"</span>)
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s11</span>
<span class="comment">// create a transition from s11 to s12 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s12</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s11 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s11 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s12</span>
<span class="comment">// create a transition from s12 to s13 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s13</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s13</span>
<span class="comment">// create a transition from s13 to s11 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s11</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s13 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s13 exited"</span>)
}
}
<span class="type"><a href="qml-qtqml-statemachine-finalstate.html">FinalState</a></span> {
<span class="name">id</span>: <span class="name">s2</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 exited"</span>)
}
<span class="name">onFinished</span>: <span class="name">Qt</span>.<span class="name">quit</span>()
}</pre>
<p>In this case we want the application to quit when the state machine is finished, so the machine's <i>finished()</i> signal is connected to the application's <i>quit()</i> slot.</p>
<p>A child state can override an inherited transition. For example, the following code adds a transition that effectively causes the Quit button to be ignored when the state machine is in state, <code>s12</code>.</p>
<pre class="qml"> <span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s12</span>
<span class="comment">// create a transition from s12 to s13 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s13</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// ignore Quit button when we are in state 12</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s12</span>
<span class="name">signal</span>: <span class="name">quitButton</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 exited"</span>)
}</pre>
<p>A transition can have any state as its target irrespective of where the target state is in the state hierarchy.</p>
<a name="using-history-states"></a>
<h2 id="using-history-states">Using History States</h2>
<p>Imagine that we wanted to add an "interrupt" mechanism to the example discussed in the previous section; the user should be able to click a button to have the state machine perform some non-related task, after which the state machine should resume whatever it was doing before (i.e. return to the old state, which is one of the three states in this case).</p>
<p>Such behavior can easily be modeled using <i>history states</i>. A history state (<a href="qml-qtqml-statemachine-historystate.html">HistoryState</a> object) is a pseudo-state that represents the child state that the parent state was in before it exited last.</p>
<p>A history state is created as a child of the state for which we wish to record the current child state; when the state machine detects the presence of such a state at runtime, it automatically records the current (real) child state when the parent state exits. A transition to the history state is in fact a transition to the child state that the state machine had previously saved; the state machine automatically "forwards" the transition to the real child state.</p>
<p>The following diagram shows the state machine after the interrupt mechanism has been added.</p>
<p class="centerAlign"><img src="images/statemachine-button-history.png" alt="" /></p><p>The following code shows how it can be implemented; in this example we simply display a message box when <code>s3</code> is entered, then immediately return to the previous child state of <code>s1</code> via the history state.</p>
<pre class="qml"> <span class="type">Row</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">spacing</span>: <span class="number">2</span>
<span class="type">Button</span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="comment">// change the button label to the active state id</span>
<span class="name">text</span>: <span class="name">s11</span>.<span class="name">active</span> ? <span class="string">"s11"</span> : <span class="name">s12</span>.<span class="name">active</span> ? <span class="string">"s12"</span> : <span class="name">s13</span>.<span class="name">active</span> ? <span class="string">"s13"</span> : <span class="string">"s3"</span>
}
<span class="type">Button</span> {
<span class="name">id</span>: <span class="name">interruptButton</span>
<span class="name">text</span>: <span class="name">s1</span>.<span class="name">active</span> ? <span class="string">"Interrupt"</span> : <span class="string">"Resume"</span>
}
<span class="type">Button</span> {
<span class="name">id</span>: <span class="name">quitButton</span>
<span class="name">text</span>: <span class="string">"quit"</span>
}
}
<span class="type"><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></span> {
<span class="name">id</span>: <span class="name">stateMachine</span>
<span class="comment">// set the initial state</span>
<span class="name">initialState</span>: <span class="name">s1</span>
<span class="comment">// start the state machine</span>
<span class="name">running</span>: <span class="number">true</span>
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="comment">// set the initial state</span>
<span class="name">initialState</span>: <span class="name">s11</span>
<span class="comment">// create a transition from s1 to s2 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s2</span>
<span class="name">signal</span>: <span class="name">quitButton</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s1 exited"</span>)
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s11</span>
<span class="comment">// create a transition from s1 to s2 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s12</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s11 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s11 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s12</span>
<span class="comment">// create a transition from s2 to s3 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s13</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s12 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s13</span>
<span class="comment">// create a transition from s3 to s1 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s1</span>
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s13 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s13 exited"</span>)
}
<span class="comment">// create a transition from s1 to s3 when the button is clicked</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s3</span>
<span class="name">signal</span>: <span class="name">interruptButton</span>.<span class="name">clicked</span>
}
<span class="type"><a href="qml-qtqml-statemachine-historystate.html">HistoryState</a></span> {
<span class="name">id</span>: <span class="name">s1h</span>
}
}
<span class="type"><a href="qml-qtqml-statemachine-finalstate.html">FinalState</a></span> {
<span class="name">id</span>: <span class="name">s2</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s2 exited"</span>)
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s3</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s1h</span>
<span class="name">signal</span>: <span class="name">interruptButton</span>.<span class="name">clicked</span>
}
<span class="comment">// do something when the state enters/exits</span>
<span class="name">onEntered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s3 entered"</span>)
<span class="name">onExited</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"s3 exited"</span>)
}
<span class="name">onFinished</span>: <span class="name">Qt</span>.<span class="name">quit</span>()
}</pre>
<a name="using-parallel-states"></a>
<h2 id="using-parallel-states">Using Parallel States</h2>
<p>Assume that you wanted to model a set of mutually exclusive properties of a car in a single state machine. Let's say the properties we are interested in are Clean vs Dirty, and Moving vs Not moving. It would take four mutually exclusive states and eight transitions to represent the states and freely move between all possible combinations as shown in the following state chart.</p>
<p class="centerAlign"><img src="images/statemachine-nonparallel.png" alt="" /></p><p>If we added a third property (say, Red vs Blue), the total number of states would double, to eight; and if we added a fourth property (say, Enclosed vs Convertible), the total number of states would double again, to 16.</p>
<p>This exponential increase can be reduced using parallel states, which enables linear growth in the number of states and transitions as we add more properties. Furthermore, states can be added to or removed from the parallel state without affecting any of their sibling states. The following state chart shows the different paralles states for the car example.</p>
<p class="centerAlign"><img src="images/statemachine-parallel.png" alt="" /></p><p>To create a parallel state group, set childMode to QState.ParallelStates.</p>
<pre class="qml"><span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="name">childMode</span>: <span class="name">QState</span>.<span class="name">ParallelStates</span>
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s11</span>
}
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s12</span>
}
}</pre>
<p>When a parallel state group is entered, all its child states will be simultaneously entered. Transitions within the individual child states operate normally. However, any of the child states may take a transition which exits the parent state. When this happens, the parent state and all of its child states are exited.</p>
<p>The parallelism in the State Machine framework follows an interleaved semantics. All parallel operations will be executed in a single, atomic step of the event processing, so no event can interrupt the parallel operations. However, events will still be processed sequentially, as the machine itself is single threaded. For example, consider the situation where there are two transitions that exit the same parallel state group, and their conditions become true simultaneously. In this case, the event that is processed last of the two will not have any effect.</p>
<a name="exiting-a-composite-state"></a>
<h2 id="exiting-a-composite-state">Exiting a Composite State</h2>
<p>A child state can be final (a <a href="qml-qtqml-statemachine-finalstate.html">FinalState</a> object); when a final child state is entered, the parent state emits the <a href="qml-qtqml-statemachine-state.html#finished-signal">State::finished</a> signal. The following diagram shows a composite state <code>s1</code> which does some processing before entering a final state:</p>
<p class="centerAlign"><img src="images/statemachine-finished.png" alt="" /></p><p>When <code>s1</code> 's final state is entered, <code>s1</code> will automatically emit <a href="qml-qtqml-statemachine-state.html#finished-signal">finished</a>. We use a signal transition to cause this event to trigger a state change:</p>
<pre class="qml"><span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">targetState</span>: <span class="name">s2</span>
<span class="name">signal</span>: <span class="name">s1</span>.<span class="name">finished</span>
}
}</pre>
<p>Using final states in composite states is useful when you want to hide the internal details of a composite state. The outside world should be able to enter the state and get a notification when the state has completed its work, without the need to know the internal details. This is a very powerful abstraction and encapsulation mechanism when building complex (deeply nested) state machines. (In the above example, you could of course create a transition directly from <code>s1</code> 's <code>done</code> state rather than relying on <code>s1</code> 's finished() signal, but with the consequence that implementation details of <code>s1</code> are exposed and depended on).</p>
<p>For parallel state groups, the <a href="qml-qtqml-statemachine-state.html#finished-signal">State::finished</a> signal is emitted when <i>all</i> the child states have entered final states.</p>
<a name="targetless-transitions"></a>
<h2 id="targetless-transitions">Targetless Transitions</h2>
<p>A transition need not have a target state. A transition without a target can be triggered the same way as any other transition; the difference is that it doesn't cause any state changes. This allows you to react to a signal or event when your machine is in a certain state, without having to leave that state. For example:</p>
<pre class="qml"><span class="type">Button</span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="name">text</span>: <span class="string">"button"</span>
<span class="type"><a href="qml-qtqml-statemachine-statemachine.html">StateMachine</a></span> {
<span class="name">id</span>: <span class="name">stateMachine</span>
<span class="name">initialState</span>: <span class="name">s1</span>
<span class="name">running</span>: <span class="number">true</span>
<span class="type"><a href="qml-qtqml-statemachine-state.html">State</a></span> {
<span class="name">id</span>: <span class="name">s1</span>
<span class="type"><a href="qml-qtqml-statemachine-signaltransition.html">SignalTransition</a></span> {
<span class="name">signal</span>: <span class="name">button</span>.<span class="name">clicked</span>
<span class="name">onTriggered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"button pressed"</span>)
}
}
}
}</pre>
<p>The "button pressed" message will be displayed each time the button is clicked, but the state machine will remain in its current state (s1). If the target state were explicitly set to s1, s1 would be exited and re-entered each time (the <a href="qml-qtqml-statemachine-qabstractstate.html#entered-signal">QAbstractState::entered</a> and <a href="qml-qtqml-statemachine-qabstractstate.html#exited-signal">QAbstractState::exited</a> signals would be emitted).</p>
<a name="related-information"></a>
<h2 id="related-information">Related Information</h2>
<ul>
<li><a href="qtqml-statemachine-qmlmodule.html">Declarative State Machine QML Types</a></li>
<li>The State Machine Framework</li>
</ul>
</div>
<!-- @@@qmlstatemachine.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>
|