From 23e1c7afed25ccb95cc24d2caa692853f35464ec Mon Sep 17 00:00:00 2001
From: David Boddie <dboddie@trolltech.com>
Date: Mon, 7 Sep 2009 14:53:59 +0200
Subject: Doc: Added a note that a state machine requires a running event loop.

Reviewed-by: Trust Me
---
 .../src_corelib_statemachine_qstatemachine.cpp     | 15 ++++++++
 src/corelib/statemachine/qstatemachine.cpp         | 42 ++++++----------------
 2 files changed, 26 insertions(+), 31 deletions(-)
 create mode 100644 doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp

diff --git a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp
new file mode 100644
index 0000000..128799f
--- /dev/null
+++ b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp
@@ -0,0 +1,15 @@
+//! [simple state machine]
+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();
+//! [simple state machine]
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index f562fb3..a5cdd45 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -78,13 +78,13 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-  \class QStateMachine
-  \reentrant
+    \class QStateMachine
+    \reentrant
 
-  \brief The QStateMachine class provides a hierarchical finite state machine.
+    \brief The QStateMachine class provides a hierarchical finite state machine.
 
-  \since 4.6
-  \ingroup statemachine
+    \since 4.6
+    \ingroup statemachine
 
     QStateMachine is based on the concepts and notation of
     \l{Statecharts: A visual formalism for complex
@@ -128,21 +128,7 @@ QT_BEGIN_NAMESPACE
     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
+    \snippet doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp simple state machine
 
     This code example uses QState, which inherits QAbstractState. The
     QState class provides a state that you can use to set properties
@@ -160,17 +146,7 @@ QT_BEGIN_NAMESPACE
     no error state applies to the erroneous state, the machine will stop 
     executing and an error message will be printed to the console.
 
-    \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.
-
-  The postEvent() function posts an event to the state machine. This is useful
-  when you are using custom events to trigger transitions.
-    \endomit
-
-  \sa QAbstractState, QAbstractTransition, QState, {The State Machine Framework}
+    \sa QAbstractState, QAbstractTransition, QState, {The State Machine Framework}
 */
 
 /*!
@@ -1748,6 +1724,10 @@ bool QStateMachine::isRunning() const
   transition to the initial state.  When a final top-level state (QFinalState)
   is entered, the machine will emit the finished() signal.
 
+  \note A state machine will not run without a running event loop, such as
+  the main application event loop started with QCoreApplication::exec() or
+  QApplication::exec().
+
   \sa started(), finished(), stop(), initialState()
 */
 void QStateMachine::start()
-- 
cgit v0.12