From 7700ecce8cb3b64e1ef8c4804022ceda2bed24c9 Mon Sep 17 00:00:00 2001 From: Kent Hansen Date: Tue, 5 May 2009 19:45:06 +0200 Subject: doc improvements --- src/corelib/statemachine/qfinalstate.cpp | 8 +++++--- src/corelib/statemachine/qhistorystate.cpp | 12 +++++++---- src/corelib/statemachine/qstate.cpp | 22 +++++++++++++++----- src/corelib/statemachine/qstatemachine.cpp | 32 ++++++++++++++++++++---------- 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 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 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 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() */ /*! -- cgit v0.12