<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- pinball.qdoc -->
<title>Qt SCXML Pinball Example | Qt SCXML 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="qtscxml-index.html">Qt SCXML</a></td><td ><a href="examples-qtscxml.html">Qt SCXML Examples</a></td><td >Qt SCXML Pinball Example</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtscxml-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="#running-the-example">Running the Example</a></li>
<li class="level1"><a href="#pinball-features">Pinball Features</a></li>
<li class="level1"><a href="#scxml-part-internal-logic-description">SCXML Part: Internal Logic Description</a></li>
<li class="level2"><a href="#maintaining-light-state">Maintaining Light State</a></li>
<li class="level2"><a href="#maintaining-game-state">Maintaining Game State</a></li>
<li class="level2"><a href="#maintaining-logical-state-of-buttons">Maintaining Logical State of Buttons</a></li>
<li class="level2"><a href="#maintaining-game-modes">Maintaining Game Modes</a></li>
<li class="level2"><a href="#game-on">Game On</a></li>
<li class="level2"><a href="#generating-blinking-lights">Generating Blinking Lights</a></li>
<li class="level1"><a href="#gui-part-user-interface-description">GUI Part: User Interface Description</a></li>
<li class="level1"><a href="#c-part-glue-gui-with-scxml">C++ Part: Glue GUI with SCXML</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt SCXML Pinball Example</h1>
<span class="subtitle"></span>
<!-- $$$pinball-brief -->
<p>Encapsulates the internal logic of an application in an SCXML file.</p>
<!-- @@@pinball -->
<!-- $$$pinball-description -->
<div class="descr"> <a name="details"></a>
<p><i>Pinball</i> demonstrates a clear separation between the user interface, which may be easily replaced, and the internal logic encapsulated in an SCXML file, which could also be used with another user interface.</p>
<a name="running-the-example"></a>
<h2 id="running-the-example">Running the Example</h2>
<p>To run the example from Qt Creator, open the <b>Welcome</b> mode and select the example from <b>Examples</b>. For more information, visit Building and Running an Example.</p>
<a name="pinball-features"></a>
<h2 id="pinball-features">Pinball Features</h2>
<p class="centerAlign"><img src="images/pinball.png" alt="Screenshot of the Pinball example" /></p><p>The Pinball example mimics a pinball game. The targets on the pinball table are substituted by GUI controls, mainly by push buttons. Display elements, including current score, highscore, and targets' lights, are substituted by labels. Usually, the state of the targets' lights changes very often during a game: the lights get turned on or off permanently or they blink at varying speed indicating a game (or a certain target) entered a temporary state. The state of each target light is presented as an enabled or a disabled label. There is no real ball, but clicking a target's button represents hitting a real pinball target with a ball.</p>
<p>Our pinball contains the following features:</p>
<ul>
<li>Initially and when the game ends, the pinball table enters <code>offState</code>. In that state, all lights on the table blink slowly (at intervals of 1 second).</li>
<li>After clicking the <b>START</b> button, the pinball table enters <code>onState</code>. All lights are turned off and the pinball table is ready to be played.</li>
<li>When the table is in <code>onState</code> and the players click the <b>BALL OUT</b> button, the game ends and enters <code>offState</code>. If the players' score is higher than the current highscore, the highscore is updated.</li>
<li>The goal is to collect the <b>JACKPOT</b>. In order to do that, the players must hit all five <b>CRAZY</b> letters twice. They have unlimited time for hitting them for the first time. However, after they have collected all the letters for the first time, they enter the <code>hurryState</code> and must collect them again within 5 seconds. If the time has passed and the letters were not collected again, the players must start collecting the letters from scratch.</li>
<li>Scores:<ul>
<li>1.000 per letter hit when not in <code>hurryState</code>.</li>
<li>10.000 per letter hit when in <code>hurryState</code>.</li>
<li>100.000 bonus for all 5 letters when not in <code>hurryState</code>.</li>
<li>1.000.000 bonus for all 5 letters when in <code>hurryState</code> (<b>JACKPOT</b>).</li>
</ul>
</li>
<li>When not in <code>hurryState</code>, the letters already hit should blink at intermediate speed (500ms). Letters not hit yet should stay off.</li>
<li>When in <code>hurryState</code>, the letters already hit should stay on. Letters not hit yet should blink fast (200ms). In addition, the <b>HURRY</b> light should blink at the same speed.</li>
<li>When the jackpot gets collected, the <b>JACKPOT</b> light should stay on.</li>
</ul>
<a name="scxml-part-internal-logic-description"></a>
<h2 id="scxml-part-internal-logic-description">SCXML Part: Internal Logic Description</h2>
<p>The <i>pinball.scxml</i> file describes the internal logic implemented for the pinball game. In this example, we have chosen the ECMAScript data model:</p>
<pre class="cpp">
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
name="Pinball" datamodel="ecmascript">
</pre>
<p>The ECMAScript data model enables declaring variables with initial values that can be modified later. We declare the <code>"highscore"</code> and <code>"score"</code> variables with the initial values of 0:</p>
<pre class="cpp">
<datamodel>
<data id="highScore" expr="0"/>
<data id="score" expr="0"/>
</datamodel>
</pre>
<p>We define a root parallel state <code>"global"</code>, with two child states, <code>guiControl</code> and <code>internalState</code>, which are also parallel. Because the top <code>global</code> state is parallel, all of its direct children are active when it is active. In this example, the role of <code>global</code> is to collect the child states and make them both active at a time.</p>
<p class="centerAlign"><img src="images/pinball-statechart-global.png" alt="" /></p><a name="maintaining-light-state"></a>
<h3 id="maintaining-light-state">Maintaining Light State</h3>
<p>The <code>guiControl</code> element is responsible for maintaining the current state of each light control that is visible on the pinball table. Each light has a corresponding state.</p>
<p class="centerAlign"><img src="images/pinball-statechart-guicontrol.png" alt="" /></p><p>For example, the light of the letter <b>C</b> corresponds to the <code>cLight</code> state. Each light state has two child states indicating whether the light is on or off:</p>
<pre class="cpp">
<parallel id="global">
<parallel id="guiControl">
<state id="cLight">
<state id="cLightOn">
<transition event="turnOffC" target="cLightOff"/>
</state>
<state id="cLightOff">
<transition event="turnOnC" target="cLightOn"/>
</state>
</state>
</pre>
<p>As mentioned before, the <code>guiControl</code> state is always active, and since it is of parallel type, all its direct children are always active too. Therefore, the <code>cLight</code> state is always active. However, only one of its children, <code>cLightOn</code> or <code>cLightOff</code>, is active at a time. The same applies to the other children of the <code>guiControl</code> state. In addition, we define transitions between on and off substates. For example, whenever the active state is <code>cLightOn</code> and a <code>turnOffC</code> event is received, we change the active substate of <code>cLight</code> to <code>cLightOff</code>. Whenever the active state is <code>cLightOff</code> and we receive a <code>turnOnC</code> event, we change the active substate of <code>cLight</code> to <code>cLightOn</code>.</p>
<p>In our application, we use instances of QLabel class in C++ to represent real lights on the table. When the light transitions into the <i>on</i> or <i>off</i> state, we enable or disable the particular label accordingly. The connection between the state machine and the GUI part of the application will be shown in the <a href="qtscxml-sudoku-example.html#cpp">C++ code</a> later on. For now, it is enough to realize that changes to active states inside the state machine will serve as the external interface of the state machine that the other parts of the application (such as the GUI part) can listen to.</p>
<p>All of the mentioned events that switch the state of a light will be generated by this state machine inside the <code>internalState</code> in reaction to running timers or external triggers.</p>
<a name="maintaining-game-state"></a>
<h3 id="maintaining-game-state">Maintaining Game State</h3>
<p>The <code>internalState</code> state consists of two main parts: <code>logicalState</code> and <code>workflow</code>.</p>
<p class="centerAlign"><img src="images/pinball-statechart-internalstate.png" alt="" /></p><p>The <code>logicalState</code> state holds the definitions for the modes that the game is able to go into and for the logical states of collected targets. The <code>workflow</code> state implements a generator for light blinking and calculates most of the new states the machine should go into depending on incoming events and on currently active states. As mentioned already, <code>internalState</code> is always active, and since it is of a parallel type, <code>logicalState</code> and <code>workflow</code> are always active too.</p>
<a name="maintaining-logical-state-of-buttons"></a>
<h3 id="maintaining-logical-state-of-buttons">Maintaining Logical State of Buttons</h3>
<p>The <code>logicalState</code> state consist of two parts: <code>letterState</code> and <code>modeState</code>.</p>
<p class="centerAlign"><img src="images/pinball-statechart-logicalstate.png" alt="" /></p><p>As previously mentioned, <code>logicalState</code> is always active, and since it is of parallel type, the <code>letterState</code> and <code>modeState</code> children are always active too. Now let us look at the first part, the <code>letterState</code>, which contains one parallel <code>lettersState</code>:</p>
<pre class="cpp">
<state id="letterState">
<parallel id="lettersState">
<state id="letter.C">
<state id="cLetterOff">
<transition event="cLetterTriggered" cond="In('onState')" target="cLetterOn"/>
</state>
<final id="cLetterOn"/>
</state>
<state id="letter.R">
...
</state>
<state id="letter.A">
...
</state>
<state id="letter.Z">
...
</state>
<state id="letter.Y">
...
</state>
<transition event="resetLetters" target="lettersState"/>
</parallel>
</state>
</pre>
<p>The <code>lettersState</code> state maintains the logical state of the buttons pretending to be targets that were clicked by the players. The letter state for the letter <b>C</b> holds whether the target for the letter <b>C</b> was hit, while the light state for the letter <b>C</b> holds whether the light for the target for the letter <b>C</b> should be currently on or off. In a real pinball game, these states are usually orthogonal, which means that if you have not hit a target yet, the target is blinking, indicating that it is currently worth hitting. This blinking means that the light state switches between on and off at short intervals, while the target state is continouosly off, because it has not been hit yet. The author of a pinball table can decide that after a target is hit (that is, after the target state switches to on) the target's light is continuously turned off or on or the intervals between lights blinking become shorter or longer.</p>
<p>As mentioned before, <code>letterState</code> is always active, which means that its only child <code>lettersState</code> should always be active too. However, there is one exception: for a short while the <code>lettersState</code> may end up being <i>not active</i>. This happens when the transition for <code>lettersState</code> is being performed. This transition is triggered when the <code>resetLetters</code> event occurs, and it instructs the state machine to exit <code>lettersState</code> and all its descendant states and reenter <code>lettersState</code> and set up all its descendant states with their initial states. In short, the <code>resetLetters</code> event resets the <code>lettersState</code> and all its descendant states to the default configuration.</p>
<p>The <code>lettersState</code> contains five direct substates that correspond to five different letters. The content for other letters' states than C is not shown here, but it is analogous to the content for C's state.</p>
<p>The <code>letter.C</code> state contains two substates reflecting its off and on states: <code>cLetterOff</code> and <code>cLetterOn</code>. The <code>letter.C</code> state inside its parallel parent <code>lettersState</code> is always active (under the condition that <code>lettersState</code> is active, as described before). However, only one of its child states is active at a time: <code>cLetterOff</code> or <code>cLetterOn</code>. The initial substate of the <code>letter.C</code> state is <code>cLetterOff</code> meaning that whenever the <code>letter.C</code> state is being activated (which happens initially and after the <code>resetLetters</code> event) its active substate will be set to <code>cLetterOff</code>.</p>
<p>The <code>cLetterOff</code> state defines a transition, which will be triggered by the <code>cLetterTriggered</code> event. This transition activates <code>cLetterOn</code>, the other child of <code>letter.C</code>, only when the machine is in <code>onState</code> (that is, when the pinball game is running). The <code>cLetterTriggered</code> event is expected to be an event posted into the state machine from outside of the state machine. This event should be generated when the ball hits the letter <b>C</b> target. In our example we mimic it by the clicking the letter <b>C</b> button.</p>
<p>The <code>cLetterOn</code> state is defined as a final state, which means that whenever this state is activated the <code>done.state.letter.C</code> event will be automatically posted by the state machine. This event will be used later for updating the current score.</p>
<p>Moreover, when all <code>lettersState</code> children reach their final state, the state machine will automatically post the <code>done.state.lettersState</code> event. This event will be used later, too, for updating the current score and for turning on or off the hurry state.</p>
<a name="maintaining-game-modes"></a>
<h3 id="maintaining-game-modes">Maintaining Game Modes</h3>
<p>The <code>modeState</code> state consists of two substates, <code>offState</code> and <code>onState</code>.</p>
<p class="centerAlign"><img src="images/pinball-statechart-modestate.png" alt="" /></p><p>The <code>offState</code> state describes what should happen before the pinball game is started and when it is over, while <code>onState</code> represents the logic appropriate for the active game.</p>
<pre class="cpp">
<state id="offState">
<onentry>
<if cond="highScore &lt; score">
<assign location="highScore" expr="score"/>
</if>
<raise event="resetLetters"/>
<raise event="update"/>
</onentry>
<transition event="startTriggered" target="onState"/>
</state>
</pre>
<p>When the pinball application starts or a game ends, the machine goes into <code>offState</code>. Entering that state invokes some actions, which are enclosed inside an <code><onentry></code> element. First, we update the <code>highScore</code> variable in case the current <code>highScore</code> value is less than current <code>score</code> value. This is being checked inside the <code>"cond"</code> attribute of the <code><if></code> element (note that we need to escape the "<" character with "&lt;"). Even in the <code>off</code> state, we want to show the last reached score, so we do not clear it here; we will do that when we enter the <code>on</code> state. Next, we raise two events: <code>resetLetters</code> to logically reset all letters that might have been hit during the last game and <code>update</code> to immediately activate the blinking and updating of all lights. When the machine is in <code>offState</code>, it is ready to transition into the <code>onState</code> if only the <code>startTriggered</code> event occurs, which is described by the <transition> element. This event is expected to be generated externally after clicking the <b>START</b> button on the pinball table.</p>
<pre class="cpp">
<parallel id="onState">
<onentry>
<assign location="score" expr="0"/>
</onentry>
<state id="hurryState">
<state id="hurryStateOff">
<onentry>
<raise event="resetLetters"/>
<raise event="update"/>
</onentry>
<transition event="goToHurryOn" target="hurryStateOn"/>
</state>
<state id="hurryStateOn">
<onentry>
<send event="goToHurryOff" id="hurryId" delay="5s"/>
<raise event="resetLetters"/>
<raise event="update"/>
</onentry>
<transition event="goToHurryOff" target="hurryStateOff"/>
<onexit>
<cancel sendid="hurryId"/>
</onexit>
</state>
</state>
<state id="jackpotState">
<state id="jackpotStateOff">
<onentry>
<raise event="update"/>
</onentry>
<transition event="goForJackpot" target="jackpotStateOn"/>
</state>
<state id="jackpotStateOn">
<onentry>
<raise event="update"/>
</onentry>
</state>
</state>
<transition event="ballOutTriggered" target="offState"/>
</parallel>
</pre>
<a name="game-on"></a>
<h3 id="game-on">Game On</h3>
<p>When the state machine enters <code>onState</code>, it first clears the current score variable. The <code>onState</code> state is of the parallel type and has two direct child states: <code>hurryState</code> and <code>jackpotState</code>. They are active as long as their parent, <code>onState</code>, is active. Both <code>hurryState</code> and <code>jackpotState</code> contain two substates that reflect their off and on states. Only one substate of <code>hurryState</code> and one substate of <code>jackpotState</code> can be active at a time. Initially, the off substates are active.</p>
<p class="centerAlign"><img src="images/pinball-statechart-onstate.png" alt="" /></p><p>Whenever we enter <code>hurryStateOff</code> or <code>hurryStateOn</code>, we generate the same two events we generate when entering the <code>onState</code> state: <code>resetLetters</code> and <code>update</code>. In addition, when we enter the <code>hurryStateOn</code> state, we send a delayed event, <code>goToHurryOff</code>, with a delay of five seconds, marked with <code>hurryId</code>. This means that after five seconds we just switch the state back to <code>hurryStateOff</code> without granting the bonus points. In this way, we implement the five-second hurry feature of the pinball table. We also define transitions from <code>hurryStateOff</code> to <code>hurryStateOn</code> when the <code>goToHurryOn</code> event occurs and from <code>hurryStateOn</code> to <code>hurryStateOff</code> when the <code>goToHurryOff</code> event occurs. When we exit the <code>hurryStateOn</code> state, we cancel the possibly pending delayed event that was marked with <code>hurryId</code>. This is important in case the five secons have not elapsed yet, but players have collected all the five letters in the hurry state. We then collect the jackpot and want the pending timer to finish.</p>
<p>The substates of <code>jackpotState</code> generate the request to update the state of lights. The <code>jackpotStateOff</code> state defines the transition to <code>jackpotStateOn</code> when the <code>goForJackpot</code> event occurs. The opposite transition is not needed, because when the jackpot gets collected, the corresponding light remains lit until the end of game. When a new game starts, the <code>jackpotState</code> is entered again which causes its initial active substate to be <code>jackpotStateOff</code>.</p>
<p>In addition, the <code>onState</code> state defines one transition in reaction to the <code>ballOutTriggered</code> event which instructs the machine to go into the <code>offState</code>. The <code>ballOutTriggered</code> event is expected to be an event posted into the state machine from outside of the state machine. This event should be generated when the ball gets out of playing area of the table. In our example we mimic it by the clicking <b>BALL OUT</b> button. Posting the event from outside of state machine will be shown in the <a href="qtscxml-sudoku-example.html#cpp">C++ code</a> later on.</p>
<a name="generating-blinking-lights"></a>
<h3 id="generating-blinking-lights">Generating Blinking Lights</h3>
<p>The <code>workflow</code> state is responsible for generating the blinking lights. The generator is defined in its <code>lightImpulseGenerator</code> substate. In addition, it is responsible for reacting to events that have been posted so far from the other parts of the state machine.</p>
<pre class="cpp">
<state id="workflow">
<state id="lightImpulseGenerator">
<state id="lightImpulseOn"/>
<state id="lightImpulseOff"/>
<onentry>
<raise event="update"/>
</onentry>
<transition event="scheduleNewImpulse">
<cancel sendid="lightId"/>
<if cond="In('offState')">
<send event="lightImpulse" id="lightId" delay="1s"/>
<elseif cond="In('hurryStateOff')"/>
<send event="lightImpulse" id="lightId" delay="500ms"/>
<else/>
<send event="lightImpulse" id="lightId" delay="200ms"/>
</if>
</transition>
<transition event="update">
<raise event="scheduleNewImpulse"/>
<raise event="updateLights"/>
</transition>
<transition event="lightImpulse" cond="In('lightImpulseOn')" target="lightImpulseOff"/>
<transition event="lightImpulse" cond="In('lightImpulseOff')" target="lightImpulseOn"/>
</state>
<transition event="done.state.letter.*">
...
</transition>
<transition event="done.state.lettersState">
...
</transition>
<transition event="updateLights">
...
</transition>
<transition event="updateLightsAccordingToLettersState">
...
</transition>
<transition event="turnOnLights">
...
</transition>
<transition event="turnOffLights">
...
</transition>
</state>
</pre>
<p>The <code>lightImpulseGenerator</code> contains two child states: <code>lightImpulseOn</code> and <code>lightImpulseOff</code>, with only one active at a time.</p>
<p class="centerAlign"><img src="images/pinball-statechart-workflow.png" alt="" /></p><p>Whenever the delayed <code>lightImpulse</code> event is being delivered, it immediately causes the transition from <code>lightImpluseOn</code> into <code>lightImpulseOff</code> or vice versa, depending on the state the machine was in. In effect, the <code>lightImpulseGenerator</code> toggles between its on and off state. These transitions are defined inside <code>lightImpulseGenerator</code>, so it means that during this toggling the machine also exits <code>lightImpulseGenerator</code> and reenters it immediately afterwards. Entering <code>lightImpulseGenerator</code> causes the generation of the <code>update</code> event. The <code>update</code> event triggers a targetless transition and posts two other events: <code>scheduleNewImpulse</code> and <code>updateLights</code>. The first one, <code>scheduleNewImpulse</code>, returns back to the <code>lightImpulseGenerator</code>, which posts a delayed <code>lightImpulse</code> event. After the delay, the <code>lightImpulse</code> event gets delivered back to <code>lightImpulseGenerator</code>, which causes it to toggle its substate again. In this way, the machine enters into a cycle. The current delay of the <code>lightImpulse</code> event depends on the state in which the machine was in the time of posting the delayed event. If a <code>scheduleNewImpulse</code> event occurs on demand, before the next delayed <code>lightImpulse</code> event gets delivered, we cancel any possible pending events.</p>
<pre class="cpp">
<transition event="done.state.letter.*">
<if cond="In('hurryStateOff')">
<assign location="score" expr="score + 1000"/>
<elseif cond="In('hurryStateOn')"/>
<assign location="score" expr="score + 10000"/>
</if>
<raise event="updateLights"/>
</transition>
<transition event="done.state.lettersState">
<if cond="In('hurryStateOff')">
<assign location="score" expr="score + 100000"/>
<raise event="goToHurryOn"/>
<elseif cond="In('hurryStateOn')"/>
<assign location="score" expr="score + 1000000"/>
<raise event="goToHurryOff"/>
<raise event="goForJackpot"/>
</if>
</transition>
</pre>
<p>Whenever we receive the event the name of which matches the <code>done.state.letter.*</code>, we update the current score. When the machine enters the final substate of the <code>letter.C</code>, it emits the <code>done.state.letter.C</code> event. The same happens for all other letters we have previously defined. We capture the events for all letters, that is why we have used an asterisk after a dot in the event name. The transition above is targetless, since we just listen for matching events and update the internal data accordingly without changing any active state. The new score is being increased by 1.000 or 10.000 points, depending on whether we currently are in <code>hurryStateOff</code> or <code>hurryStateOn</code>. After the score is updated, we generate the <code>updateLights</code> event in order to immediately update the letters' lights accordingly. We do not generate the <code>update</code> event here, since we do not want to toggle the light impulse now, but just update the lights according to the current impulse state.</p>
<p>We also intercept the <code>done.state.lettersState</code> event, which is being generated when all the letters have been hit. Depending on which state we are currently in, we grant the players either a small bonus of 100.000 or a big one of 1.000.000 (jackpot). In addition, we toggle the <code>hurryState</code> substate by sending the <code>goToHurryOn</code> or <code>goToHurryOff</code> event. When all letters have been collected while in <code>hurryStateOn</code>, we also raise the <code>goForJackpot</code> event which instructs the machine to activate the <code>jackpotStateOn</code>.</p>
<pre class="cpp">
<transition event="updateLights">
<send event="updateScore">
<param name="highScore" expr="highScore"/>
<param name="score" expr="score"/>
</send>
<if cond="In('jackpotStateOn')">
<raise event="turnOnJackpot"/>
<else/>
<raise event="turnOffJackpot"/>
</if>
<if cond="In('lightImpulseOn')">
<if cond="In('offState')">
<raise event="turnOnLights"/>
<raise event="turnOnHurry"/>
<raise event="turnOnJackpot"/>
<raise event="turnOnGameOver"/>
<elseif cond="In('hurryStateOff')"/>
<raise event="updateLightsAccordingToLettersState"/>
<raise event="turnOffHurry"/>
<raise event="turnOffGameOver"/>
<else/>
<raise event="turnOnLights"/>
<raise event="turnOnHurry"/>
<raise event="turnOffGameOver"/>
</if>
<else/>
<if cond="In('offState')">
<raise event="turnOffLights"/>
<raise event="turnOffHurry"/>
<raise event="turnOffJackpot"/>
<elseif cond="In('hurryStateOff')"/>
<raise event="turnOffLights"/>
<else/>
<raise event="updateLightsAccordingToLettersState"/>
</if>
<raise event="turnOffHurry"/>
<raise event="turnOffGameOver"/>
</if>
</transition>
<transition event="updateLightsAccordingToLettersState">
<if cond="In('cLetterOn')">
<raise event="turnOnC"/>
<else/>
<raise event="turnOffC"/>
</if>
<if cond="In('rLetterOn')">
<raise event="turnOnR"/>
<else/>
<raise event="turnOffR"/>
</if>
<if cond="In('aLetterOn')">
<raise event="turnOnA"/>
<else/>
<raise event="turnOffA"/>
</if>
<if cond="In('zLetterOn')">
<raise event="turnOnZ"/>
<else/>
<raise event="turnOffZ"/>
</if>
<if cond="In('yLetterOn')">
<raise event="turnOnY"/>
<else/>
<raise event="turnOffY"/>
</if>
</transition>
<transition event="turnOnLights">
<raise event="turnOnC"/>
<raise event="turnOnR"/>
<raise event="turnOnA"/>
<raise event="turnOnZ"/>
<raise event="turnOnY"/>
</transition>
<transition event="turnOffLights">
<raise event="turnOffC"/>
<raise event="turnOffR"/>
<raise event="turnOffA"/>
<raise event="turnOffZ"/>
<raise event="turnOffY"/>
</transition>
</pre>
<p>When we receive the <code>updateLights</code> event, we first want to send a <code>updateScore</code> event outside of the state machine. We pass the current values of the <code>highScore</code> and <code>score</code> variables to the event. This event is received by the C++ part.</p>
<p>Next, depending on whether we are in <code>jackpotStateOn</code> or <code>jackpotStateOff</code>, we send the <code>turnOnJackpot</code> or the <code>turnOffJackpot</code> event, which instructs the <code>guiControl</code> state to transition to <code>jackpotLightOn</code> or <code>jackpotLightOff</code>, respectively.</p>
<p>When the machine is in <i>idle</i> state, (that is, in the off state) or when the game is on, but no interaction occurs, the <code>updateLights</code> event is delivered periodically during the game, each time with the <code>lightImpulseOn</code> or <code>lightImpulseOff</code> state toggled. Depending on the current state of the light impulse and on the active state (<code>offState</code>, <code>hurryStateOff</code> or <code>hurryStateOn</code>), we turn on or off all the lights according to the description of the pinball table.</p>
<a name="gui-part-user-interface-description"></a>
<h2 id="gui-part-user-interface-description">GUI Part: User Interface Description</h2>
<p>The GUI part of the application consists of a <i>mainwindow.ui</i> file which describes the static user interface of the game.</p>
<a name="cpp"></a><a name="c-part-glue-gui-with-scxml"></a>
<h2 id="c-part-glue-gui-with-scxml">C++ Part: Glue GUI with SCXML</h2>
<p>The C++ part of the application consists of a <code>MainWindow</code> class which glues the GUI part with the SCXML part. The class is declared in <i>mainwindow.h</i>.</p>
<pre class="cpp">
<span class="keyword">class</span> MainWindow;
}
<span class="keyword">class</span> <span class="type"><a href="qscxmlstatemachine.html">QScxmlStateMachine</a></span>;
QT_END_NAMESPACE
<span class="keyword">class</span> MainWindow : <span class="keyword">public</span> <span class="type">QWidget</span>
{
Q_OBJECT
<span class="keyword">public</span>:
<span class="keyword">explicit</span> MainWindow(<span class="type"><a href="qscxmlstatemachine.html">QScxmlStateMachine</a></span> <span class="operator">*</span>machine<span class="operator">,</span> <span class="type">QWidget</span> <span class="operator">*</span>parent <span class="operator">=</span> nullptr);
<span class="operator">~</span>MainWindow();
<span class="keyword">private</span>:
<span class="type">void</span> initAndConnect(<span class="keyword">const</span> <span class="type">QString</span> <span class="operator">&</span>state<span class="operator">,</span> <span class="type">QWidget</span> <span class="operator">*</span>widget);
QT_PREPEND_NAMESPACE(Ui<span class="operator">::</span>MainWindow) <span class="operator">*</span>m_ui;
<span class="type"><a href="qscxmlstatemachine.html">QScxmlStateMachine</a></span> <span class="operator">*</span>m_machine;
};
</pre>
<p>The <code>MainWindow</code> class holds the pointer to the <code>QScxmlStateMachine *m_machine</code> which is the state machine class automatically generated by Qt out of SCMXL file and the pointer to the <code>Ui::MainWindow *m_ui</code> which describes the GUI part. It also declares two helper methods.</p>
<pre class="cpp">
<span class="preprocessor">#include "mainwindow.h"</span>
<span class="preprocessor">#include "ui_mainwindow.h"</span>
<span class="preprocessor">#include <QScxmlStateMachine></span>
<span class="preprocessor">#include <QStringListModel></span>
QT_USE_NAMESPACE
MainWindow<span class="operator">::</span>MainWindow(<span class="type"><a href="qscxmlstatemachine.html">QScxmlStateMachine</a></span> <span class="operator">*</span>machine<span class="operator">,</span> <span class="type">QWidget</span> <span class="operator">*</span>parent) :
<span class="type">QWidget</span>(parent)<span class="operator">,</span>
m_ui(<span class="keyword">new</span> Ui<span class="operator">::</span>MainWindow)<span class="operator">,</span>
m_machine(machine)
{
m_ui<span class="operator">-</span><span class="operator">></span>setupUi(<span class="keyword">this</span>);
<span class="comment">// lights</span>
initAndConnect(QLatin1String(<span class="string">"cLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>cLabel);
initAndConnect(QLatin1String(<span class="string">"rLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>rLabel);
initAndConnect(QLatin1String(<span class="string">"aLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>aLabel);
initAndConnect(QLatin1String(<span class="string">"zLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>zLabel);
initAndConnect(QLatin1String(<span class="string">"yLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>yLabel);
initAndConnect(QLatin1String(<span class="string">"hurryLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>hurryLabel);
initAndConnect(QLatin1String(<span class="string">"jackpotLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>jackpotLabel);
initAndConnect(QLatin1String(<span class="string">"gameOverLightOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>gameOverLabel);
<span class="comment">// help labels</span>
initAndConnect(QLatin1String(<span class="string">"offState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>offStateLabel);
initAndConnect(QLatin1String(<span class="string">"hurryStateOff"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>normalStateLabel);
initAndConnect(QLatin1String(<span class="string">"hurryStateOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>hurryStateLabel);
initAndConnect(QLatin1String(<span class="string">"jackpotStateOn"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>jackpotStateLabel);
<span class="comment">// context enablement</span>
initAndConnect(QLatin1String(<span class="string">"offState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>startButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>cButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>rButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>aButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>zButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>yButton);
initAndConnect(QLatin1String(<span class="string">"onState"</span>)<span class="operator">,</span> m_ui<span class="operator">-</span><span class="operator">></span>ballOutButton);
<span class="comment">// datamodel update</span>
m_machine<span class="operator">-</span><span class="operator">></span>connectToEvent(<span class="string">"updateScore"</span><span class="operator">,</span> <span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> (<span class="keyword">const</span> <span class="type"><a href="qscxmlevent.html">QScxmlEvent</a></span> <span class="operator">&</span>event) {
<span class="keyword">const</span> <span class="type">QVariant</span> data <span class="operator">=</span> event<span class="operator">.</span>data();
<span class="keyword">const</span> <span class="type">QString</span> highScore <span class="operator">=</span> data<span class="operator">.</span>toMap()<span class="operator">.</span>value(<span class="string">"highScore"</span>)<span class="operator">.</span>toString();
m_ui<span class="operator">-</span><span class="operator">></span>highScoreLabel<span class="operator">-</span><span class="operator">></span>setText(highScore);
<span class="keyword">const</span> <span class="type">QString</span> score <span class="operator">=</span> data<span class="operator">.</span>toMap()<span class="operator">.</span>value(<span class="string">"score"</span>)<span class="operator">.</span>toString();
m_ui<span class="operator">-</span><span class="operator">></span>scoreLabel<span class="operator">-</span><span class="operator">></span>setText(score);
});
<span class="comment">// gui interaction</span>
connect(m_ui<span class="operator">-</span><span class="operator">></span>cButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"cLetterTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>rButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"rLetterTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>aButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"aLetterTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>zButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"zLetterTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>yButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"yLetterTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>startButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"startTriggered"</span>);
});
connect(m_ui<span class="operator">-</span><span class="operator">></span>ballOutButton<span class="operator">,</span> <span class="operator">&</span><span class="type">QAbstractButton</span><span class="operator">::</span>clicked<span class="operator">,</span>
<span class="operator">[</span><span class="keyword">this</span><span class="operator">]</span> { m_machine<span class="operator">-</span><span class="operator">></span>submitEvent(<span class="string">"ballOutTriggered"</span>);
});
}
</pre>
<p>The constructor of the <code>MainWindow</code> class instantiates the GUI part of the application and stores the pointer to the passed <code>QScxmlStateMachine</code>. It also initializes the GUI part and glues the GUI part to the state machine by connecting their communication interfaces together.</p>
<p>The <code>initAndConnect()</code> method connects the state with the corresponding GUI widget by binding its activity with the enabling of the widget, so that whenever the state is active, its corresponding widget is enabled and whenever the state is inactive, the widget is disabled. We do that for all lights, targets, and description labels.</p>
<p>We also intercept the <code>updateScore</code> event sent by the state machine, in order to update the score displays with the values passed with the event.</p>
<p>The info about hitting any GUI target needs to be passed to the state machine and we do that by connecting all target buttons' <code>clicked</code> signals to the lambda expressions which submit the corresponding event into the state machine.</p>
<pre class="cpp">
<span class="preprocessor">#include "mainwindow.h"</span>
<span class="preprocessor">#include "pinball.h"</span>
<span class="preprocessor">#include <QApplication></span>
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>argv)
{
<span class="type">QApplication</span> app(argc<span class="operator">,</span> argv);
Pinball machine;
MainWindow mainWindow(<span class="operator">&</span>machine);
machine<span class="operator">.</span>start();
mainWindow<span class="operator">.</span>show();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}
</pre>
<p>In the <code>main()</code> function in the <i>main.cpp</i> file, we instantiate the <code>app</code> application object, <code>Pinball</code> state machine, and <code>MainWindow</code> GUI class. We initialize and start the state machine, show the main window, and execute the application.</p>
<p>Files:</p>
<ul>
<li><a href="qtscxml-pinball-main-cpp.html">pinball/main.cpp</a></li>
<li><a href="qtscxml-pinball-mainwindow-cpp.html">pinball/mainwindow.cpp</a></li>
<li><a href="qtscxml-pinball-mainwindow-h.html">pinball/mainwindow.h</a></li>
<li><a href="qtscxml-pinball-mainwindow-ui.html">pinball/mainwindow.ui</a></li>
<li><a href="qtscxml-pinball-pinball-cpp.html">pinball/pinball.cpp</a></li>
<li><a href="qtscxml-pinball-pinball-h.html">pinball/pinball.h</a></li>
<li><a href="qtscxml-pinball-pinball-pro.html">pinball/pinball.pro</a></li>
<li><a href="qtscxml-pinball-pinball-scxml.html">pinball/pinball.scxml</a></li>
</ul>
</div>
<!-- @@@pinball -->
</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
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
6ed78e842caa17fd5c94d65d685685e0
>
files
>
156
