QStateMachine Class Reference
[QtCore module]

Detailed Description

The QStateMachine class provides a hierarchical finite state machine.

QStateMachine is based on the concepts and notation of Statecharts. QStateMachine is part of The State Machine Framework.

A state machine manages a set of states (classes that inherit from QAbstractState) and transitions (descendants of QAbstractTransition) between those states; these states and transitions define a state graph. Once a state graph has been built, the state machine can execute it. QStateMachine's execution algorithm is based on the State Chart XML (SCXML) algorithm. The framework's overview gives several state graphs and the code to build them.

Use the addState() function to add a top-level state to the state machine. States are removed with the removeState() function. Removing states while the machine is running is discouraged.

Before the machine can be started, the initial state must be set. The initial state is the state that the machine enters when started. You can then start() the state machine. The started() signal is emitted when the initial state is entered.

The machine is event driven and keeps its own event loop. Events are posted to the machine through postEvent(). Note that this means that it executes asynchronously, and that it will not progress without a running event loop. You will normally not have to post events to the machine directly as Qt's transitions, e.g., QEventTransition and its subclasses, handle this. But for custom transitions triggered by events, postEvent() is useful.

The state machine processes events and takes transitions until a top-level final state is entered; the state machine then emits the finished() signal. You can also stop() the state machine explicitly. The stopped() signal is emitted in this case.

The following snippet shows a state machine that will finish when a button is clicked:

 QPushButton button;

 QStateMachine machine;
 QState *s1 = new QState();
 s1->assignProperty(&button, "text", "Click me");

 QFinalState *s2 = new QFinalState();
 s1->addTransition(&button, SIGNAL(clicked()), s2);

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

This code example uses QState, which inherits QAbstractState. The QState class provides a state that you can use to set properties and invoke methods on QObjects when the state is entered or exited. It also contains convenience functions for adding transitions, e.g., QSignalTransitions as in this example. See the QState class description for further details.

If an error is encountered, the machine will look for an error state, and if one is available, it will enter this state. The types of errors possible are described by the Error enum. After the error state is entered, the type of the error can be retrieved with error(). The execution of the state graph will not stop when the error state is entered. If no error state applies to the erroneous state, the machine will stop executing and an error message will be printed to the console.

See also QAbstractState, QAbstractTransition, QState, and The State Machine Framework.

Member Type Documentation