summaryrefslogtreecommitdiffstats
path: root/src/corelib/statemachine
diff options
context:
space:
mode:
authorKent Hansen <khansen@trolltech.com>2009-05-05 17:45:06 (GMT)
committerKent Hansen <khansen@trolltech.com>2009-05-05 17:45:06 (GMT)
commit7700ecce8cb3b64e1ef8c4804022ceda2bed24c9 (patch)
treeb545d35d7b7e297e7fc9c0d91b38d23f88de3bd2 /src/corelib/statemachine
parentb8a4216f2fb5bc6e5fd5b54c661344e60fc9093c (diff)
downloadQt-7700ecce8cb3b64e1ef8c4804022ceda2bed24c9.zip
Qt-7700ecce8cb3b64e1ef8c4804022ceda2bed24c9.tar.gz
Qt-7700ecce8cb3b64e1ef8c4804022ceda2bed24c9.tar.bz2
doc improvements
Diffstat (limited to 'src/corelib/statemachine')
-rw-r--r--src/corelib/statemachine/qfinalstate.cpp8
-rw-r--r--src/corelib/statemachine/qhistorystate.cpp12
-rw-r--r--src/corelib/statemachine/qstate.cpp22
-rw-r--r--src/corelib/statemachine/qstatemachine.cpp32
4 files changed, 51 insertions, 23 deletions
diff --git a/src/corelib/statemachine/qfinalstate.cpp b/src/corelib/statemachine/qfinalstate.cpp
index 772ec87..0980336 100644
--- a/src/corelib/statemachine/qfinalstate.cpp
+++ b/src/corelib/statemachine/qfinalstate.cpp
@@ -55,9 +55,9 @@ QT_BEGIN_NAMESPACE
A final state is used to communicate that (part of) a QStateMachine has
finished its work. When a final top-level state is entered, the state
machine's \l{QStateMachine::finished()}{finished}() signal is emitted. In
- general, when a final substate (a child of a QState) is entered, a
- QStateFinishedEvent is generated for the final state's parent
- state. QFinalState is part of \l{The State Machine Framework}.
+ general, when a final substate (a child of a QState) is entered, the parent
+ state's \l{QState::finished()}{finished}() signal is emitted. QFinalState
+ is part of \l{The State Machine Framework}.
To use a final state, you create a QFinalState object and add a transition
to it from another state. Example:
@@ -76,6 +76,8 @@ QT_BEGIN_NAMESPACE
machine.setInitialState(s1);
machine.start();
\endcode
+
+ \sa QStateMachine::finished(), QState::finished()
*/
class QFinalStatePrivate : public QAbstractStatePrivate
diff --git a/src/corelib/statemachine/qhistorystate.cpp b/src/corelib/statemachine/qhistorystate.cpp
index b6ec471..d1b2391 100644
--- a/src/corelib/statemachine/qhistorystate.cpp
+++ b/src/corelib/statemachine/qhistorystate.cpp
@@ -58,9 +58,8 @@ QT_BEGIN_NAMESPACE
other child states of the parent state. QHistoryState is part of \l{The
State Machine Framework}.
- Use QState::addHistoryState() to construct a history state. Use the
- setDefaultState() function to set the state that should be entered if the
- parent state has never been entered. Example:
+ Use the setDefaultState() function to set the state that should be entered
+ if the parent state has never been entered. Example:
\code
QStateMachine machine;
@@ -69,7 +68,7 @@ QT_BEGIN_NAMESPACE
QState *s11 = new QState(s1);
QState *s12 = new QState(s1);
- QState *s1h = s1->addHistoryState();
+ QHistoryState *s1h = new QHistoryState(s1);
s1h->setDefaultState(s11);
machine.addState(s1);
@@ -83,6 +82,9 @@ QT_BEGIN_NAMESPACE
// state if s1 has never been entered.
s1->addTransition(button, SIGNAL(clicked()), s1h);
\endcode
+
+ By default a history state is shallow, meaning that it won't remember nested
+ states. This can be configured through the historyType property.
*/
/*!
@@ -95,6 +97,8 @@ QT_BEGIN_NAMESPACE
\property QHistoryState::historyType
\brief the type of history that this history state records
+
+ The default value of this property is QHistoryState::ShallowHistory.
*/
/*!
diff --git a/src/corelib/statemachine/qstate.cpp b/src/corelib/statemachine/qstate.cpp
index 3220619..4c9e033 100644
--- a/src/corelib/statemachine/qstate.cpp
+++ b/src/corelib/statemachine/qstate.cpp
@@ -68,22 +68,30 @@ QT_BEGIN_NAMESPACE
The assignProperty() function is used for defining property assignments that
should be performed when a state is entered.
+ Top-level states must be passed QStateMachine::rootState() as their parent
+ state, or added to a state machine using QStateMachine::addState().
+
\section1 States with Child States
- For non-parallel state groups, the setInitialState() function must be called
- to set the initial state. The child states are mutually exclusive states,
- and the state machine needs to know which child state to enter when the
- parent state is the target of a transition.
+ The childMode property determines how child states are treated. For
+ non-parallel state groups, the setInitialState() function must be called to
+ set the initial state. The child states are mutually exclusive states, and
+ the state machine needs to know which child state to enter when the parent
+ state is the target of a transition.
+
+ The state emits the QState::finished() signal when a final child state
+ (QFinalState) is entered.
The setErrorState() sets the state's error state. The error state is the
state that the state machine will transition to if an error is detected when
attempting to enter the state (e.g. because no initial state has been set).
+
*/
/*!
\property QState::initialState
- \brief the initial state of this state
+ \brief the initial state of this state (one of its child states)
*/
/*!
@@ -96,6 +104,8 @@ QT_BEGIN_NAMESPACE
\property QState::childMode
\brief the child mode of this state
+
+ The default value of this property is QState::ExclusiveStates.
*/
/*!
@@ -456,6 +466,8 @@ bool QState::event(QEvent *e)
\fn QState::finished()
This signal is emitted when a final child state of this state is entered.
+
+ \sa QFinalState
*/
/*!
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index 232d801..6f626f5 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -163,6 +163,8 @@ QT_BEGIN_NAMESPACE
\property QStateMachine::initialState
\brief the initial state of this state machine
+
+ The initial state must be one of the rootState()'s child states.
*/
/*!
@@ -181,6 +183,9 @@ QT_BEGIN_NAMESPACE
\property QStateMachine::globalRestorePolicy
\brief the restore policy for states of this state machine.
+
+ The default value of this property is
+ QStateMachine::DoNotRestoreProperties.
*/
#ifndef QT_NO_ANIMATION
@@ -188,6 +193,10 @@ QT_BEGIN_NAMESPACE
\property QStateMachine::animationsEnabled
\brief whether animations are enabled
+
+ The default value of this property is true.
+
+ \sa QAbstractTransition::addAnimation()
*/
#endif
@@ -1663,7 +1672,7 @@ void QStateMachine::setInitialState(QAbstractState *state)
If the state is already in a different machine, it will first be removed
from its old machine, and then added to this machine.
- \sa removeState(), rootState()
+ \sa removeState(), rootState(), setInitialState()
*/
void QStateMachine::addState(QAbstractState *state)
{
@@ -1700,10 +1709,9 @@ void QStateMachine::removeState(QAbstractState *state)
}
/*!
- 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.
+ Starts this state machine. The machine will reset its configuration and
+ transition to the initial state. When a final top-level state (QFinalState)
+ is entered, the machine will emit the finished() signal.
\sa started(), finished(), stop(), initialState()
*/
@@ -1730,9 +1738,10 @@ void QStateMachine::start()
}
/*!
- Stops this state machine.
+ Stops this state machine. The state machine will stop processing events and
+ then emit the stopped() signal.
- \sa stopped()
+ \sa stopped(), start()
*/
void QStateMachine::stop()
{
@@ -1813,7 +1822,8 @@ QSet<QAbstractState*> QStateMachine::configuration() const
/*!
\fn QStateMachine::started()
- This signal is emitted when the state machine has entered its initial state.
+ This signal is emitted when the state machine has entered its initial state
+ (QStateMachine::initialState).
\sa QStateMachine::finished(), QStateMachine::start()
*/
@@ -1822,7 +1832,7 @@ QSet<QAbstractState*> QStateMachine::configuration() const
\fn QStateMachine::finished()
This signal is emitted when the state machine has reached a top-level final
- state.
+ state (QFinalState).
\sa QStateMachine::started()
*/
@@ -1832,7 +1842,7 @@ QSet<QAbstractState*> QStateMachine::configuration() const
This signal is emitted when the state machine has stopped.
- \sa QStateMachine::stop()
+ \sa QStateMachine::stop(), QStateMachine::finished()
*/
/*!
@@ -2110,7 +2120,7 @@ QSignalEvent::~QSignalEvent()
Returns the index of the signal.
- \sa QMetaObject::indexOfSignal()
+ \sa QMetaObject::indexOfSignal(), QMetaObject::method()
*/
/*!