improve the docs for the trafficlight example

4 files changed, 49 insertions, 41 deletions

diff --git a/doc/src/examples/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc
index 16ee8ad..50cab035 100644
--- a/doc/src/examples/trafficlight.qdoc
+++ b/doc/src/examples/trafficlight.qdoc
@@ -26,30 +26,41 @@
     \snippet examples/statemachine/trafficlight/main.cpp 0
 
     The LightWidget class represents a single light of the traffic light. It
-    provides a setOn() function to turn the light on or off. It paints itself
-    in the color that's passed to the constructor.
+    provides an \c on property and two slots, turnOn() and turnOff(), to turn
+    the light on and off, respectively. The widget paints itself in the color
+    that's passed to the constructor.
 
-    \snippet examples/statemachine/trafficlight/main.cpp 2
+    \snippet examples/statemachine/trafficlight/main.cpp 1
 
     The TrafficLightWidget class represents the visual part of the traffic
-    light; it's a widget that contains three lights, and provides accessor
-    functions for these.
+    light; it's a widget that contains three lights arranged vertically, and
+    provides accessor functions for these.
 
-    \snippet examples/statemachine/trafficlight/main.cpp 1
+    \snippet examples/statemachine/trafficlight/main.cpp 2
+
+    The createLightState() function creates a state that turns a light on when
+    the state is entered, and off when the state is exited. The state uses a
+    timer, and as we shall see the timeout is used to transition from one
+    LightState to another. Here is the statechart for the light state:
 
-    The LightState class represents a state that turns a light on when the
-    state is entered, and off when the state is exited. The class is a timer,
-    and as we shall see the timeout is used to transition from one LightState
-    to another.
+    \img trafficlight-example1.png
+    \omit
+    \caption This is a caption
+    \endomit
 
     \snippet examples/statemachine/trafficlight/main.cpp 3
 
-    The TrafficLight class combines the TrafficLightWidget with control flow
-    based on the LightState class. The state graph has four states:
-    red-to-yellow, yellow-to-green, green-to-yellow and yellow-to-red. The
-    initial state is red-to-yellow; when the state's timer times out, the
-    state machine transitions to yellow-to-green. The same process repeats
-    through the other states.
+    The TrafficLight class combines the TrafficLightWidget with a state
+    machine.  The state graph has four states: red-to-yellow, yellow-to-green,
+    green-to-yellow and yellow-to-red. The initial state is red-to-yellow;
+    when the state's timer times out, the state machine transitions to
+    yellow-to-green. The same process repeats through the other states.
+    This is what the statechart looks like:
+
+    \img trafficlight-example2.png
+    \omit
+    \caption This is a caption
+    \endomit
 
     \snippet examples/statemachine/trafficlight/main.cpp 4
 
diff --git a/doc/src/images/trafficlight-example1.png b/doc/src/images/trafficlight-example1.png
new file mode 100644
index 0000000..ec8c7ff
--- /dev/null
+++ b/doc/src/images/trafficlight-example1.png
diff --git a/doc/src/images/trafficlight-example2.png b/doc/src/images/trafficlight-example2.png
new file mode 100644
index 0000000..a12e4db
--- /dev/null
+++ b/doc/src/images/trafficlight-example2.png
diff --git a/examples/statemachine/trafficlight/main.cpp b/examples/statemachine/trafficlight/main.cpp
index 3c47a51..8a46fff 100644
--- a/examples/statemachine/trafficlight/main.cpp
+++ b/examples/statemachine/trafficlight/main.cpp
@@ -87,27 +87,6 @@ private:
 //! [0]
 
 //! [1]
-class LightState : public QState
-{
-public:
-    LightState(LightWidget *light, int duration, QState *parent = 0)
-        : QState(parent)
-    {
-        QTimer *timer = new QTimer(this);
-        timer->setInterval(duration);
-        timer->setSingleShot(true);
-        QState *timing = new QState(this);
-        QObject::connect(timing, SIGNAL(entered()), light, SLOT(turnOn()));
-        QObject::connect(timing, SIGNAL(entered()), timer, SLOT(start()));
-        QObject::connect(timing, SIGNAL(exited()), light, SLOT(turnOff()));
-        QFinalState *done = new QFinalState(this);
-        timing->addTransition(timer, SIGNAL(timeout()), done);
-        setInitialState(timing);
-    }
-};
-//! [1]
-
-//! [2]
 class TrafficLightWidget : public QWidget
 {
 public:
@@ -139,6 +118,24 @@ private:
     LightWidget *m_yellow;
     LightWidget *m_green;
 };
+//! [1]
+
+//! [2]
+QState *createLightState(LightWidget *light, int duration, QState *parent = 0)
+{
+    QState *lightState = new QState(parent);
+    QTimer *timer = new QTimer(lightState);
+    timer->setInterval(duration);
+    timer->setSingleShot(true);
+    QState *timing = new QState(lightState);
+    QObject::connect(timing, SIGNAL(entered()), light, SLOT(turnOn()));
+    QObject::connect(timing, SIGNAL(entered()), timer, SLOT(start()));
+    QObject::connect(timing, SIGNAL(exited()), light, SLOT(turnOff()));
+    QFinalState *done = new QFinalState(lightState);
+    timing->addTransition(timer, SIGNAL(timeout()), done);
+    lightState->setInitialState(timing);
+    return lightState;
+}
 //! [2]
 
 //! [3]
@@ -154,15 +151,15 @@ public:
         vbox->setMargin(0);
 
         QStateMachine *machine = new QStateMachine(this);
-        LightState *redGoingYellow = new LightState(widget->redLight(), 3000);
+        QState *redGoingYellow = createLightState(widget->redLight(), 3000);
         redGoingYellow->setObjectName("redGoingYellow");
-        LightState *yellowGoingGreen = new LightState(widget->yellowLight(), 1000);
+        QState *yellowGoingGreen = createLightState(widget->yellowLight(), 1000);
         yellowGoingGreen->setObjectName("yellowGoingGreen");
         redGoingYellow->addTransition(redGoingYellow, SIGNAL(finished()), yellowGoingGreen);
-        LightState *greenGoingYellow = new LightState(widget->greenLight(), 3000);
+        QState *greenGoingYellow = createLightState(widget->greenLight(), 3000);
         greenGoingYellow->setObjectName("greenGoingYellow");
         yellowGoingGreen->addTransition(yellowGoingGreen, SIGNAL(finished()), greenGoingYellow);
-        LightState *yellowGoingRed = new LightState(widget->yellowLight(), 1000);
+        QState *yellowGoingRed = createLightState(widget->yellowLight(), 1000);
         yellowGoingRed->setObjectName("yellowGoingRed");
         greenGoingYellow->addTransition(greenGoingYellow, SIGNAL(finished()), yellowGoingRed);
         yellowGoingRed->addTransition(yellowGoingRed, SIGNAL(finished()), redGoingYellow);