diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/images/statemachine-customevents2.png | bin | 0 -> 6713 bytes | |||
| -rw-r--r-- | doc/src/statemachine.qdoc | 45 |
2 files changed, 40 insertions, 5 deletions
diff --git a/doc/src/images/statemachine-customevents2.png b/doc/src/images/statemachine-customevents2.png Binary files differnew file mode 100644 index 0000000..57b37ef --- /dev/null +++ b/doc/src/images/statemachine-customevents2.png diff --git a/doc/src/statemachine.qdoc b/doc/src/statemachine.qdoc index 27bd4f8..5a89f4d 100644 --- a/doc/src/statemachine.qdoc +++ b/doc/src/statemachine.qdoc @@ -147,6 +147,9 @@ QObject::connect(s3, SIGNAL(exited()), button, SLOT(showMinimized())); \endcode + Custom states can reimplement QAbstractState::onEntry() and + QAbstractState::onExit(). + \section1 State Machines That Finish The state machine defined in the previous section never finishes. In order @@ -155,6 +158,9 @@ final state, the machine will emit the QStateMachine::finished() signal and halt. + All you need to do to introduce a final state in the graph is create a + QFinalState object and use it as the target of one or more transitions. + \section1 Sharing Transitions By Grouping States Assume we wanted the user to be able to quit the application at any time by @@ -315,16 +321,32 @@ \section1 Detecting that a Composite State has Finished A child state can be final (a QFinalState object); when a final child state - is entered, the parent state emits the QState::finished() signal. + is entered, the parent state emits the QState::finished() signal. The + following diagram shows a composite state \c s1 which does some processing + before entering a final state: \img statemachine-finished.png \omit \caption This is a caption \endomit - 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 completed its work. + When \c s1 's final state is entered, \c s1 will automatically emit + finished(). We use a signal transition to cause this event to trigger a + state change: + + \code + s1->addTransition(s1, SIGNAL(finished()), s2); + \endcode + + Using final states in composite states is useful when you want to hide the + internal details of a composite 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 completed its work. This is a very powerful abstraction and + encapsulation mechanism when building complex (deeply nested) state + machines. (In the above example, you could of course create a transition + directly from \c s1 's \c done state rather than relying on \c s1 's + finished() signal, but with the consequence that implementation details of + \c s1 are exposed and depended on). For parallel state groups, the QState::finished() signal is emitted when \e all the child states have entered final states. @@ -425,7 +447,20 @@ machine.postEvent(new StringEvent("Hello")); machine.postEvent(new StringEvent("world")); \endcode - + + An event that is not handled by any relevant transition will be silently + consumed by the state machine. It can be useful to group states and provide + a default handling of such events; for example, as illustrated in the + following statechart: + + \img statemachine-customevents2.png + \omit + \caption This is a caption + \endomit + + For deeply nested statecharts, you can add such "fallback" transitions at + the level of granularity that's most appropriate. + \section1 Using Restore Policy To Automatically Restore Properties In some state machines it can be useful to focus the attention on assigning properties in states, |
