QML States Controlling

English
[toc align_right="yes" depth="3"]

QML States Controlling

Introduction

QML offers very powerful "constructs":http://doc.qt.io/qt-4.8/qml-state.html to model states and dynamic behaviors. We refer to a state as a collection of parameters describing an entity at a given moment. The behavior of the entity could be described as a sequence of changing states. The model known as Finite State Machine (FSM) is widely used in many domains including the computer sciences also. For a painless introduction see "here":http://lamsonproject.org/docs/introduction_to_finite_state_machines.html and "here":http://ai-depot.com/FiniteStateMachines/.

In this article we are analyzing a more complicated state machine model, which has states that are state machine by their self. At the beginning we summarize the QML states constructs and some techniques for their control that we need for implementation. In the main article part we discuss a QML implementation of the considered FSM model. The analysis highlights the QML States/Transition elements also.

The simplest FSM model could be viewed as a sequencer. Starting from an initial state the states are navigated in a linear manner – one by one in preliminary defined ordering. The transition diagram known as state transition diagram is illustrated bellow:

sequencer state diagram
Simple Sequencer State Diagram

The FSM model we are going to implement supposes that some of states have branches:

brancher state diagram

Sequencer with Branches State Diagram

Entering such a state causes activating of its internal state machine. Completing this FSM
we return to the next state of the FSM at global level. This model could be referred to as a sequencer with nested FSMs.

QML States

More States Definitions

In QML each state is identified by its name, which is of String type. Having several states defined, we could store their names in a variant property like that:

<br />import QtQuick 1.1<br />Rectangle {id:top1<br /> width: 100<br /> height: 100<br /> color:&quot;red&amp;quot;<br />property variant statesNames:[&quot;state1&amp;quot;,&quot;state2&amp;quot;]<br />property int counter:0<br /> states:[<br /> State {<br /> name:&quot;state1&amp;quot;<br /> PropertyChanges {target:top1;color:&quot;pink&amp;quot;}<br /> },<br /> State {<br /> name:&quot;state2&amp;quot;<br /> PropertyChanges {target:top1;color:&quot;yellow&amp;quot;}<br /> }<br /> ]<br /> Timer {id:zen<br /> interval: 2000; running: true; repeat: true<br /> onTriggered: {<br /> if(counter&amp;lt;2){<br /> top1.state=statesNames[counter]<br /> counter=counter+1<br /> }<br /> else<br /> Qt.quit()<br /> }<br /> }<br />}<br />

If we have actions associated with a state we could use StateChangeScript element, which offers a script block.

Nested variant Types

As we know, variant type acts as a list. Now suppose that an element of a variant property is also of variant type:

<br />Rectangle {<br /> width: 360<br /> height: 360<br /> property variant nestedStrings:[&quot;first&amp;quot;,&quot;second&amp;quot;]<br /> property variant sequence :[&quot;element1&amp;quot;,nestedStrings,&quot;element3&amp;quot;]<br /> Component.onCompleted: {<br /> console.log(sequence[2])<br /> console.log(&quot;nested elements&amp;quot;,sequence[1][0])<br /> }<br />}<br />

Further, we could define in a variant list definition that an element is also a list using square brackets like that:

<br />property variant listIntoList:[ [&quot;string1&amp;quot;],[&quot;string21&amp;quot;,&quot;string22&amp;quot;],[&quot;string3&amp;quot;] ]<br />

The nested list elements are accessed this way:

<br />listIntoList[1][1]<br />

FSM Model Implementation

We are considering a FSM that has 5 states. The states 1, 3 and 5 have no internal states. The states 2 and 4 have internal states – 5 states each.

Definition of States

The states set is defined in a QML element (e.g. Rectangle) starting from first state (its branch if any), second state (its branch if any), etc. The states are members of QML states property. Note that states names are global and visible in the rectangle scope. The goal of this definition is to introduce the states identifiers and actions associated with states (use StateChangeScript element).

Ordering of States

The states names are arranged in a variant type property following the next rules:

- If a state has a branch it is defined in the list as a nested list.

- If a state has no branch it is defined in the list as a nested list with one element only.

- All states (on global level as well as nested ones) are accessed this way:

Property_name [][]<code>

Where the first index controls global states and the second one controls states in the corresponding branch (if any).

The following diagram illustrates the above definitions:

[[Image:http://i1072.photobucket.com/albums/w362/vabo123/nestedStates.jpg|nested states]]

property variant stateOrder :[[state1],[state21,state22],[state3],
[state41,state42,state43],[state5]]
stateOrder[1][1] //refers to state22

== Implementation Details ==

The demo code is available "here":http://bit.ly/1fzD7JO. The code is not optimized to easy explanation of basic ideas. A fragment of implementation follows:

Rectangle {id:top1
width: 500
height: 500
color:"#f9f0e7"
property bool branch //Controls if a state has a branch
property int currentIndex:0 //Current index for outer loop
property int innerCounter:0 //Current index for inner (branch) loop
//statesParameters property holds two parameters for each state:
// a bool value if a state has or has no branch and the number
// of states in a branch
property variant statesParameters:[ [true,5],[false,1],[true,5],[false,1],[true,5] ]
//Images could be stored in a list
property variant imagesList: [ ["kiparisi/kip1.jpg","kiparisi/piramidalen.jpg",
"kiparisi/spiral.jpg","kiparisi/tuya.jpg","kiparisi/septe.jpg"] ]
//A rectangle that contains explanatory text is added
Rectangle {id:frame
x:60;y:60
width:350; height:30
color:"white"
Rectangle {
Text {id:literal
text: "This is the initial state. A timer generates state transitions."
}
}
}
Rectangle {
x:180;y:180
Image {id:picture; source:"Qt_logo.jpg"}
}
property variant stateNames:[ ["state11","state12","state13","state14","state15"],
["state2"],
["state31","state32","state33","state34","state35"],
["state4"],
["state51","state52","state53","state54","state55"]
]
property int counter:0
Timer {id:zen
interval: 2000; running: true; repeat: true
onTriggered: {
if(counter<5)
branch=statesParameters[counter][0];
else
Qt.quit();
if(branch==false)
{
innerCounter=0;
top1.state=stateNames[counter][innerCounter];
counter=counter+1;
currentIndex=counter;
}
else
{
if(innerCounter<statesParameters[counter][1])
{
top1.state=stateNames[counter][innerCounter];
innerCounter=innerCounter+1;
}
else{
counter=currentIndex+1;
if(counter>=5) Qt.quit();
}
}
}//end of onTriggered
}// end of Timer
states:[
State {
name:"state11"
PropertyChanges {target:top1;color:"Snow"}
StateChangeScript {
name:"stateScript11"
script:{
literal.text="Cupressaceae - State 11"
picture.source=imagesList[0][2]
}
}
},
State {
name:"state12"
PropertyChanges {target:top1;color:"Azure"}
StateChangeScript {
name:"stateScript12"
script:{
literal.text="Cupressaceae - State 12"
picture.source=imagesList[0][0]
}
}
},
. . .

State {
name:"state55"
PropertyChanges {target:top1;color:"PeachPuff"}
StateChangeScript {
name:"stateScript55"
script:{
literal.text="Roses - State55"
picture.source="roses/katerach.jpg"
}
}
}
]
}//end of top1

A Timer element is used to initiate the transition from the current state to the next one. Each state is represented visually by different images. The actions performed for each state are included in a StateChangesScript element block. There are three types of actions – changing the color of the frame containing the images, changing the images and altering the explanatory text in the upper text box.

The states are visited one by one. You may change the Timer interval property to control the rate of images rendering. The transition is implemented changing the property state of QML state "model":http://doc.qt.io/qt-4.8/qdeclarativestates.html.