|  | Home

# The State Machine Framework

- A Simple State Machine
- Sharing Transitions By Grouping States
- Using History States to Save and Restore the Current State
- Using Parallel States to Avoid a Combinatorial Explosion of States
- Detecting that a Composite State has Finished

The State Machine framework provides classes for creating and executing state graphs. The concepts and notation are based on those from Harel's Statecharts, which is also the basis of UML state diagrams. The semantics of state machine execution are based on State Chart XML (SCXML).

Statecharts provide a graphical way of modeling how a system reacts to stimuli. This is done by defining the possible states that the system can be in, and how the system can move from one state to another (transitions between states). A key characteristic of event-driven systems (such as Qt applications) is that behavior often depends not only on the last or current event, but also the events that preceded it. With statecharts, this information is easy to express.

The State Machine framework provides an API and execution model that can be used to effectively embed the elements and semantics of statecharts in Qt applications. The framework integrates tightly with Qt's existing event system and meta-object system; for example, transitions between states can be triggered by signals, and states can be configured to set properties and invoke methods on QObjects.

### A Simple State Machine

To demonstrate the core functionality of the State Machine API, let's look at a small example: A state machine with three states, `s1`, `s2` and `s3`. The state machine is controlled by a single QPushButton; when the button is clicked, the machine transitions to another state. Initially, the state machine is in state `s1`. The statechart for this machine is as follows:

The following snippet shows the code needed to create such a state machine.

     QtStateMachine machine;
     QtState *s1 = new QtState();
     QtState *s2 = new QtState();
     QtState *s3 = new QtState();

     s1->addTransition(button, SIGNAL(clicked()), s2);
     s2->addTransition(button, SIGNAL(clicked()), s3);
     s3->addTransition(button, SIGNAL(clicked()), s1);

     machine.addState(s1);
     machine.addState(s2);
     machine.addState(s3);
     machine.setInitialState(s1);

     machine.start();

Once the state machine has been set up, you need to start it by calling QtStateMachine::start(). The state machine executes asynchronously, i.e. it becomes part of your application's event loop.

The above state machine is perfectly fine, but it doesn't do anything; it merely transitions from one state to another. The QtState::setPropertyOnEntry() function can be used to have a state set a property of a QObject when the state is entered. In the following snippet, the value that should be assigned to a QLabel's text property is specified for each state:

     s1->setPropertyOnEntry(label, "text", "In state s1");
     s2->setPropertyOnEntry(label, "text", "In state s2");
     s3->setPropertyOnEntry(label, "text", "In state s3");

When any of the states is entered, the label's text will be changed accordingly.

The QtState::invokeMethodOnEntry() function can be used to have a state invoke a method (a slot) of a QObject when the state is entered. In the following snippet, the button's showMaximized() slot will be called when state `s3` is entered:

     s2->invokeMethodOnEntry(button, "showMaximized");

### Sharing Transitions By Grouping States

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 final state. When the state machine enters a top-level final state, the machine will emit the finished() signal and halt.

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 clicked() signal. We could add a transition from each of `s1`, `s2` and `s3`; 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.

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 `s1`, `s2` and `s3`. 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.

The three original states have been renamed `s11`, `s12` and `s13` to reflect that they are now children of the new top-level state, `s1`. Child states implicitly inherit the transitions of their parent state. This means it is now sufficient to add a single transition from `s1` to the final state `s2`. New states added to `s1` will also automatically inherit this transition.

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 (i.e. which child state the state machine should enter when the parent state is the target of a transition).

     QtState *s1 = new QtState();
     QtState *s11 = new QtState(s1);
     QtState *s12 = new QtState(s1);
     QtState *s13 = new QtState(s1);
     s1->setInitialState(s11);
     machine.addState(s1);

     QtFinalState *s2 = new QtFinalState();
     s1->addTransition(quitButton, SIGNAL(clicked()), s2);
     machine.addState(s2);

     QObject::connect(&machine, SIGNAL(finished()), QApplication::instance(), SLOT(quit()));

In this case we want the application to quit when the state machine is finished, so the machine's finished() signal is connected to the application's quit() slot.

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 `s12`.

     s12>addTransition(quitButton, SIGNAL(clicked()), s12);

### Using History States to Save and Restore the Current State

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 `s11`, `s12` and `s13` in this case).

Such behavior can easily be modeled using history states. A history state (QtHistoryState object) is a pseudo-state that represents the child state that the parent state was in the last time the parent state was exited.

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 is exited. 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.

The following diagram shows the state machine after the interrupt mechanism has been added.

The following code shows how it can be implemented; in this example we simply display a message box when `s3` is entered, then immediately return to the previous child state of `s1` via the history state.

     QtHistoryState *s1h = s1->addHistoryState();

     QtState *s3 = new QtState();
     s3->setPropertyOnEntry(label, "text", "In s3");
     QMessageBox mbox;
     mbox.addButton(QMessageBox::Ok);
     mbox.setText("Interrupted!");
     mbox.setIcon(QMessageBox::Information);
     s3->invokeMethodOnEntry(&mbox, "exec");
     s3->addTransition(s1h);
     machine.addState(s3);

     s1->addTransition(interruptButton, SIGNAL(clicked()), s3);

### Using Parallel States to Avoid a Combinatorial Explosion of States

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 be able to represent and freely move between all possible combinations.

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.

Using parallel states, the total number of states and transitions grows linearly as we add more properties, instead of exponentially. Furthermore, states can be added to or removed from the parallel state without affecting any of their sibling states.

The QtParallelStateGroup class is used to create groups of parallel states.

     QtParallelStateGroup *s1 = new QtParallelStateGroup();
     // s11 and s12 will be entered in parallel
     QtState *s11 = new QtState(s1);
     QtState *s12 = new QtState(s1);

### Detecting that a Composite State has Finished

A child state can be final; when a final child state is entered, a QtStateFinishedEvent is generated for the parent state. You can use the QtStateFinishedTransition class to trigger a transition based on this event.

This is useful when you want to hide the internal details of a state; i.e. the only thing the outside world should be able to do is enter the state, and get a notification when the state has finished (i.e. when a final child state has been entered).