![]() |
Home |
The QtStateMachine class provides a hierarchical finite state machine. More...
#include <QtStateMachine>
Inherits QObject.
Note: All the functions in this class are reentrant.
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.
The following snippet shows a state machine that will finish when a button is clicked:
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.
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().
Constructs a new state machine with the given parent.
Destroys this state machine.
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() and rootState().
Clears the error string and error code of the state machine.
Returns the error code of the last error that occurred in the state machine.
Returns the error state of the state machine's root state.
See also setErrorState() and QtState::errorState().
Returns the error string of the last error that occurred in the state machine.
This signal is emitted when the state machine has reached a top-level final state.
See also QtStateMachine::started().
Returns the global restore policy of the state machine.
See also setGlobalRestorePolicy() and QtActionState::restorePolicy().
Returns this state machine's initial state, or 0 if no initial state has been set.
See also setInitialState().
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.
Removes the given state from this state machine. The state machine releases ownership of the state.
See also addState().
Returns this state machine's root 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(), QtState::setErrorState(), and rootState().
Sets the global restore policy of the state machine to restorePolicy. The default global restore policy is QtActionState::DoNotRestoreProperties.
The global restore policy cannot be set to QtActionState::GlobalRestorePolicy.
See also globalRestorePolicy() and QtActionState::setRestorePolicy().
Sets this state machine's initial state.
See also initialState().
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().
This signal is emitted when the state machine has entered its initial state.
See also QtStateMachine::finished() and QtStateMachine::start().
Stops this state machine.
See also stopped().
This signal is emitted when the state machine has stopped.
See also QtStateMachine::stop().
Copyright © 2009 Nokia | Trademarks | Qt Solutions |