doc: Describe the semantics of targetless state machine transitions

2 files changed, 33 insertions, 0 deletions

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).
 */
 
 /*!