From c89557db5b643eb8018de8ca87e5e56140ed6d2d Mon Sep 17 00:00:00 2001
From: Geir Vattekar <geir.vattekar@trolltech.com>
Date: Wed, 13 May 2009 12:40:27 +0200
Subject: Doc: Work on QStateMachine class description
Reviewed-by: Kent Hansen
---
src/corelib/statemachine/qstatemachine.cpp | 140 +++++++++++++++++------------
1 file changed, 85 insertions(+), 55 deletions(-)
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index 24af8e4..42e965a 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -89,68 +89,98 @@ QT_BEGIN_NAMESPACE
\since 4.6
\ingroup statemachine
- The QStateMachine class provides a hierarchical finite state machine based
- on \l{Statecharts: A visual formalism for complex systems}{Statecharts}
- concepts and notation. QStateMachine is part of \l{The State Machine
- Framework}.
-
- A state machine manages a set of states (QAbstractState objects) and
- transitions (QAbstractTransition 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. QStateMachine's
- execution algorithm is based on the \l{State Chart XML: State Machine
- Notation for Control Abstraction}{State Chart XML (SCXML)} algorithm.
-
- 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. This is
+ QStateMachine is based on the concepts and notation of
+ \l{Statecharts: A visual formalism for complex
+ systems}{Statecharts}. QStateMachine is part of \l{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. \l{QStateMachine}'s
+ execution algorithm is based on the \l{State Chart XML: State
+ Machine Notation for Control Abstraction}{State Chart XML (SCXML)}
+ algorithm. The framework's \l{The State Machine
+ Framework}{overview} gives several state graphs and the code to
+ build them.
+
+ The rootState() is the parent of all top-level states in the
+ machine; it is used, for instance, when the state graph is
+ deleted. It is created by the machine.
+
+ Use the addState() function to add a state to the state machine.
+ All top-level states are added to the root state. States are
+ removed with the removeState() function. Removing states while the
+ machine is running is discouraged.
+
+ Before the machine can be started, the \l{initialState}{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:
+
+ \code
+ 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();
+ \endcode
+
+ 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 \l{QObject}s when the state is entered or
+ exited. It also contains convenience functions for adding
+ transitions, e.g., \l{QSignalTransition}s as in this example. See
+ the QState class description for further details.
+
+ If an error is encountered, the machine will enter the
+ \l{errorState}{error state}, which is a special state created by
+ the machine. The types of errors possible are described by the
+ \l{QStateMachine::}{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.
+ So it is possible to handle the error, for instance, by connecting
+ to the \l{QAbstractState::}{entered()} signal of the error state.
+ It is also possible to set a custom error state with
+ setErrorState().
+
+ \omit This stuff will be moved elsewhere
+This is
typically used in conjunction with \l{Signals and Slots}{signals}; the
signals determine the flow of the state graph, whereas the states' property
assignments 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:
-
- \code
- 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();
- \endcode
-
- 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.
+ \endomit
- The rootState() function returns the state machine's root state. All
- top-level states have the root state as their parent.
-
- \sa QAbstractState, QAbstractTransition
+ \sa QAbstractState, QAbstractTransition, QState, {The State Machine Framework}
*/
/*!
--
cgit v0.12