From d557d6e5dc73c88f9de26bf2e3dd2c6955400467 Mon Sep 17 00:00:00 2001 From: Kent Hansen Date: Mon, 28 Sep 2009 19:08:00 +0200 Subject: doc: Describe the semantics of targetless state machine transitions --- doc/src/frameworks-technologies/statemachine.qdoc | 29 +++++++++++++++++++++++ src/corelib/statemachine/qabstracttransition.cpp | 4 ++++ 2 files changed, 33 insertions(+) diff --git a/doc/src/frameworks-technologies/statemachine.qdoc b/doc/src/frameworks-technologies/statemachine.qdoc index 2b137dd..ed8bc85 100644 --- a/doc/src/frameworks-technologies/statemachine.qdoc +++ b/doc/src/frameworks-technologies/statemachine.qdoc @@ -304,6 +304,35 @@ For parallel state groups, the QState::finished() signal is emitted when \e all the child states have entered final states. + \section1 Targetless Transitions + + A transition need not have a target state. A transition without a target can + be triggered the same way as any other transition; the difference is that + when a targetless transition is triggered, it doesn't cause any state + changes. This allows you to react to a signal or event when your machine is + in a certain state, without having to leave that state. Example: + + \code + QStateMachine machine; + QState *s1 = new QState(&machine); + + QPushButton button; + QSignalTransition *trans = new QSignalTransition(&button, SIGNAL(clicked())); + s1->addTransition(trans); + + QMessageBox msgBox; + msgBox.setText("The button was clicked; carry on."); + QObject::connect(trans, SIGNAL(triggered()), &msgBox, SLOT(exec())); + + machine.setInitialState(s1); + \endcode + + The message box will be displayed each time the button is clicked, but the + state machine will remain in its current state (s1). If the target state + were explicitly set to s1, however, s1 would be exited and re-entered each + time (e.g. the QAbstractState::entered() and QAbstractState::exited() + signals would be emitted). + \section1 Events, Transitions and Guards A QStateMachine runs its own event loop. For signal transitions diff --git a/src/corelib/statemachine/qabstracttransition.cpp b/src/corelib/statemachine/qabstracttransition.cpp index 8b858c7..76baa0a 100644 --- a/src/corelib/statemachine/qabstracttransition.cpp +++ b/src/corelib/statemachine/qabstracttransition.cpp @@ -93,6 +93,10 @@ QT_BEGIN_NAMESPACE \property QAbstractTransition::targetState \brief the target state of this transition + + If a transition has no target state, the transition may still be + triggered, but this will not cause the state machine's configuration to + change (i.e. the current state will not be exited and re-entered). */ /*! -- cgit v0.12