|  | Home

# QtStateMachine Class Reference
[QtCore module]

The QtStateMachine class provides a hierarchical finite state machine. More...

     #include <QtStateMachine>

Inherits QObject.

Note: All the functions in this class are reentrant.

- List of all members, including inherited members

### Public Types

- enum Error { NoError, NoInitialStateError, NoDefaultStateInHistoryState }

### Public Functions

- QtStateMachine ( QObject * parent = 0 )
- ~QtStateMachine ()
- void addState ( QtAbstractState * state )
- void clearError ()
- Error error () const
- QtAbstractState * errorState () const
- QString errorString () const
- QtState::RestorePolicy globalRestorePolicy () const
- QtAbstractState * initialState () const
- void postEvent ( QEvent * event, int delay = 0 )
- void removeState ( QtAbstractState * state )
- QtState * rootState () const
- void setErrorState ( QtAbstractState * state )
- void setGlobalRestorePolicy ( QtState::RestorePolicy restorePolicy )
- void setInitialState ( QtAbstractState * state )

- 29 public functions inherited from QObject

### Public Slots

- void start ()
- void stop ()

- 1 public slot inherited from QObject

### Signals

- void finished ()
- void started ()
- void stopped ()

- 1 signal inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 1 public type inherited from QObject
- 4 static public members inherited from QObject
- 7 protected functions inherited from QObject
- 2 protected variables inherited from QObject

## Detailed Description

The QtStateMachine class provides a hierarchical finite state machine.

The QtStateMachine class provides a hierarchical finite state machine based on Statecharts concepts and notation. QtStateMachine is part of The State Machine Framework.

A state machine manages a set of states (QtAbstractState objects) and transitions (QtAbstractTransition objects) between those states; the states and the transitions collectively define a state graph. Once a state graph has been defined, the state machine can execute it. QtStateMachine's execution algorithm is based on the State Chart XML (SCXML) algorithm.

The QtState class provides a state that you can use to set properties and invoke methods on QObjects when the state is entered or exited. This is typically used in conjunction with signals; the signals determine the flow of the state graph, whereas the states' property assigments and method invocations are the actions.

Use the addState() function to add a state to the state machine; alternatively, pass the machine's rootState() to the state constructor. Use the removeState() function to remove a state from the state machine.

     QPushButton button;

     QtStateMachine machine;
     QtState *s1 = new QtState();
     s1->setPropertyOnEntry(&button, "text", "Click me");
     machine.addState(s1);
     QtFinalState *s2 = new QtFinalState();
     s1->addTransition(&button, SIGNAL(clicked()), s2);
     machine.addState(s2);

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

The setInitialState() function sets the state machine's initial state; this state is entered when the state machine is started.

The start() function starts the state machine. The state machine executes asynchronously, i.e. you need to run an event loop in order for it to make progress. The started() signal is emitted when the state machine has entered the initial state.

The state machine processes events and takes transitions until a top-level final state is entered; the state machine then emits the finished() signal.

The stop() function stops the state machine. The stopped() signal is emitted when the state machine has stopped.

The postEvent() function posts an event to the state machine. This is useful when you are using custom events to trigger transitions.

The rootState() function returns the state machine's root state. All top-level states have the root state as their parent.

See also QtAbstractState and QtAbstractTransition.

## Member Type Documentation

### enum QtStateMachine::Error

This enum type defines errors that can occur in the state machine at run time. When the state machine encounters an unrecoverable error at run time, it will set the error code returned by error(), the error message returned by errorString(), and enter an error state based on the context of the error.

Constant | Value | Description
--- | --- | ---
`QtStateMachine::NoError` | `0` | No error has occurred.
`QtStateMachine::NoInitialStateError` | `1` | The machine has entered a QtState with children which does not have an initial state set. The context of this error is the state which is missing an initial state.
`QtStateMachine::NoDefaultStateInHistoryState` | `2` | The machine has entered a QtHistoryState which does not have a default state set. The context of this error is the QtHistoryState which is missing a default state.

See also setErrorState().

## Member Function Documentation

### QtStateMachine::QtStateMachine ( QObject * parent = 0 )

Constructs a new state machine with the given parent.

### QtStateMachine::~QtStateMachine ()

Destroys this state machine.

### void QtStateMachine::addState ( QtAbstractState * state )

Adds the given state to this state machine. The state becomes a top-level state (i.e. a child of the rootState()).

If the state is already in a different machine, it will first be removed from its old machine, and then added to this machine.

See also removeState().

### void QtStateMachine::clearError ()

Clears the error string and error code of the state machine.

### Error QtStateMachine::error () const

Returns the error code of the last error that occurred in the state machine.

### QtAbstractState * QtStateMachine::errorState () const

Returns the error state of the state machine's root state.

See also setErrorState() and QtAbstractStateGroup::errorState().

### QString QtStateMachine::errorString () const

Returns the error string of the last error that occurred in the state machine.

### void QtStateMachine::finished () `[signal]`

This signal is emitted when the state machine has reached a top-level final state.

See also QtStateMachine::started().

### QtState::RestorePolicy QtStateMachine::globalRestorePolicy () const

Returns the global restore policy of the state machine.

See also setGlobalRestorePolicy(), QtAbstractStateGroup::RestorePolicy, and QtAbstractStateGroup::restorePolicy().

### QtAbstractState * QtStateMachine::initialState () const

Returns this state machine's initial state, or 0 if no initial state has been set.

See also setInitialState().

### void QtStateMachine::postEvent ( QEvent * event, int delay = 0 )

Posts the given event for processing by this state machine, with a delay of delay milliseconds.

This function returns immediately. The event is added to the state machine's event queue. Events are processed in the order posted. The state machine takes ownership of the event and deletes it once it has been processed.

You can only post events when the state machine is running.

### void QtStateMachine::removeState ( QtAbstractState * state )

Removes the given state from this state machine. The state machine releases ownership of the state.

See also addState().

### QtState * QtStateMachine::rootState () const

Returns this state machine's root state.

### void QtStateMachine::setErrorState ( QtAbstractState * state )

Sets the error state of this state machine's root state to be state. When a running state machine encounters an error which puts it in an undefined state, it will enter an error state based on the context of the error that occurred. It will enter this state regardless of what is currently in the event queue.

If the erroneous state has an error state set, this will be entered by the machine. If no error state has been set, the state machine will search the parent hierarchy recursively for an error state. The error state of the root state can thus be seen as a global error state that applies for the states for which a more specific error state has not been set.

Before entering the error state, the state machine will set the error code returned by error() and error message returned by errorString().

The default error state will print a warning to the console containing the information returned by errorString(). By setting a new error state on either the state machine itself, or on specific states, you can fine tune error handling in the state machine.

If the root state's error state is set to 0, or if the error state selected by the machine itself contains an error, the default error state will be used.

See also errorState(), QtAbstractStateGroup::setErrorState(), and rootState().

### void QtStateMachine::setGlobalRestorePolicy ( QtState::RestorePolicy restorePolicy )

Sets the global restore policy of the state machine to restorePolicy. The default global restore policy is QtAbstractStateGroup::DoNotRestoreProperties.

The global restore policy cannot be set to QtAbstractStateGroup::GlobalRestorePolicy.

See also globalRestorePolicy(), QtAbstractStateGroup::RestorePolicy, and QtAbstractStateGroup::setRestorePolicy().

### void QtStateMachine::setInitialState ( QtAbstractState * state )

Sets this state machine's initial state.

See also initialState().

### void QtStateMachine::start () `[slot]`

Starts this state machine. The machine will reset its configuration and transition to the initial state. When a final top-level state is entered, the machine will emit the finished() signal.

See also started(), finished(), stop(), and initialState().

### void QtStateMachine::started () `[signal]`

This signal is emitted when the state machine has entered its initial state.

See also QtStateMachine::finished() and QtStateMachine::start().

### void QtStateMachine::stop () `[slot]`

Stops this state machine.

See also stopped().

### void QtStateMachine::stopped () `[signal]`

This signal is emitted when the state machine has stopped.

See also QtStateMachine::stop().