<?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.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="qtqml-index.html">Qt QML</a></td><td >The Declarative State Machine Framework</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtqml-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="#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">
</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">
</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">
Button {
anchors.fill: parent
id: button
// change the button label to the active state id
text: s1.active ? "s1" : s2.active ? "s2" : "s3"
}
StateMachine {
id: stateMachine
// set the initial state
initialState: s1
// start the state machine
running: true
State {
id: s1
// create a transition from s1 to s2 when the button is clicked
SignalTransition {
targetState: s2
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s1 entered")
onExited: console.log("s1 exited")
}
State {
id: s2
// create a transition from s2 to s3 when the button is clicked
SignalTransition {
targetState: s3
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s2 entered")
onExited: console.log("s2 exited")
}
State {
id: s3
// create a transition from s3 to s1 when the button is clicked
SignalTransition {
targetState: s1
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s3 entered")
onExited: console.log("s3 exited")
}
}
</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">
Row {
anchors.fill: parent
spacing: 2
Button {
id: button
// change the button label to the active state id
text: s11.active ? "s11" : s12.active ? "s12" : "s13"
}
Button {
id: quitButton
text: "quit"
}
}
StateMachine {
id: stateMachine
// set the initial state
initialState: s1
// start the state machine
running: true
State {
id: s1
// set the initial state
initialState: s11
// create a transition from s1 to s2 when the button is clicked
SignalTransition {
targetState: s2
signal: quitButton.clicked
}
// do something when the state enters/exits
onEntered: console.log("s1 entered")
onExited: console.log("s1 exited")
State {
id: s11
// create a transition from s11 to s12 when the button is clicked
SignalTransition {
targetState: s12
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s11 entered")
onExited: console.log("s11 exited")
}
State {
id: s12
// create a transition from s12 to s13 when the button is clicked
SignalTransition {
targetState: s13
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s12 entered")
onExited: console.log("s12 exited")
}
State {
id: s13
// create a transition from s13 to s11 when the button is clicked
SignalTransition {
targetState: s11
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s13 entered")
onExited: console.log("s13 exited")
}
}
FinalState {
id: s2
onEntered: console.log("s2 entered")
onExited: console.log("s2 exited")
}
onFinished: Qt.quit()
}
</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">
State {
id: s12
// create a transition from s12 to s13 when the button is clicked
SignalTransition {
targetState: s13
signal: button.clicked
}
// ignore Quit button when we are in state 12
SignalTransition {
targetState: s12
signal: quitButton.clicked
}
// do something when the state enters/exits
onEntered: console.log("s12 entered")
onExited: console.log("s12 exited")
}
</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">
Row {
anchors.fill: parent
spacing: 2
Button {
id: button
// change the button label to the active state id
text: s11.active ? "s11" : s12.active ? "s12" : s13.active ? "s13" : "s3"
}
Button {
id: interruptButton
text: s1.active ? "Interrupt" : "Resume"
}
Button {
id: quitButton
text: "quit"
}
}
StateMachine {
id: stateMachine
// set the initial state
initialState: s1
// start the state machine
running: true
State {
id: s1
// set the initial state
initialState: s11
// create a transition from s1 to s2 when the button is clicked
SignalTransition {
targetState: s2
signal: quitButton.clicked
}
// do something when the state enters/exits
onEntered: console.log("s1 entered")
onExited: console.log("s1 exited")
State {
id: s11
// create a transition from s1 to s2 when the button is clicked
SignalTransition {
targetState: s12
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s11 entered")
onExited: console.log("s11 exited")
}
State {
id: s12
// create a transition from s2 to s3 when the button is clicked
SignalTransition {
targetState: s13
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s12 entered")
onExited: console.log("s12 exited")
}
State {
id: s13
// create a transition from s3 to s1 when the button is clicked
SignalTransition {
targetState: s1
signal: button.clicked
}
// do something when the state enters/exits
onEntered: console.log("s13 entered")
onExited: console.log("s13 exited")
}
// create a transition from s1 to s3 when the button is clicked
SignalTransition {
targetState: s3
signal: interruptButton.clicked
}
HistoryState {
id: s1h
}
}
FinalState {
id: s2
onEntered: console.log("s2 entered")
onExited: console.log("s2 exited")
}
State {
id: s3
SignalTransition {
targetState: s1h
signal: interruptButton.clicked
}
// do something when the state enters/exits
onEntered: console.log("s3 entered")
onExited: console.log("s3 exited")
}
onFinished: Qt.quit()
}
</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">
</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">
</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">
</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> 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
>
144
