More work on a documentation for pinball example

Change-Id: I4f6bec3d992a15f7ad3d905f8fff632da8c1f25b
Reviewed-by: Erik Verbruggen <erik.verbruggen@theqtcompany.com>

3 files changed, 101 insertions, 44 deletions

diff --git a/examples/pinball-ecmascript-common/mainwindow.cpp b/examples/pinball-ecmascript-common/mainwindow.cpp
index 1bba03f..ea5995d 100644
--- a/examples/pinball-ecmascript-common/mainwindow.cpp
+++ b/examples/pinball-ecmascript-common/mainwindow.cpp
@@ -48,67 +48,67 @@ QT_USE_NAMESPACE
 
 MainWindow::MainWindow(Pinball *machine, QWidget *parent) :
     QWidget(parent),
-    ui(new Ui::MainWindow),
+    m_ui(new Ui::MainWindow),
     m_machine(machine)
 {
-    ui->setupUi(this);
+    m_ui->setupUi(this);
 
     // lights
-    initAndConnect(QLatin1String("cLightOn"), ui->cLabel);
-    initAndConnect(QLatin1String("rLightOn"), ui->rLabel);
-    initAndConnect(QLatin1String("aLightOn"), ui->aLabel);
-    initAndConnect(QLatin1String("zLightOn"), ui->zLabel);
-    initAndConnect(QLatin1String("yLightOn"), ui->yLabel);
-    initAndConnect(QLatin1String("hurryLightOn"), ui->hurryLabel);
-    initAndConnect(QLatin1String("jackpotLightOn"), ui->jackpotLabel);
-    initAndConnect(QLatin1String("gameOverLightOn"), ui->gameOverLabel);
+    initAndConnect(QLatin1String("cLightOn"), m_ui->cLabel);
+    initAndConnect(QLatin1String("rLightOn"), m_ui->rLabel);
+    initAndConnect(QLatin1String("aLightOn"), m_ui->aLabel);
+    initAndConnect(QLatin1String("zLightOn"), m_ui->zLabel);
+    initAndConnect(QLatin1String("yLightOn"), m_ui->yLabel);
+    initAndConnect(QLatin1String("hurryLightOn"), m_ui->hurryLabel);
+    initAndConnect(QLatin1String("jackpotLightOn"), m_ui->jackpotLabel);
+    initAndConnect(QLatin1String("gameOverLightOn"), m_ui->gameOverLabel);
 
     // help labels
-    initAndConnect(QLatin1String("offState"), ui->offStateLabel);
-    initAndConnect(QLatin1String("hurryStateOff"), ui->normalStateLabel);
-    initAndConnect(QLatin1String("hurryStateOn"), ui->hurryStateLabel);
-    initAndConnect(QLatin1String("jackpotStateOn"), ui->jackpotStateLabel);
+    initAndConnect(QLatin1String("offState"), m_ui->offStateLabel);
+    initAndConnect(QLatin1String("hurryStateOff"), m_ui->normalStateLabel);
+    initAndConnect(QLatin1String("hurryStateOn"), m_ui->hurryStateLabel);
+    initAndConnect(QLatin1String("jackpotStateOn"), m_ui->jackpotStateLabel);
 
     // context enablement
-    initAndConnect(QLatin1String("offState"), ui->startButton);
-    initAndConnect(QLatin1String("onState"), ui->cButton);
-    initAndConnect(QLatin1String("onState"), ui->rButton);
-    initAndConnect(QLatin1String("onState"), ui->aButton);
-    initAndConnect(QLatin1String("onState"), ui->zButton);
-    initAndConnect(QLatin1String("onState"), ui->yButton);
-    initAndConnect(QLatin1String("onState"), ui->ballOutButton);
+    initAndConnect(QLatin1String("offState"), m_ui->startButton);
+    initAndConnect(QLatin1String("onState"), m_ui->cButton);
+    initAndConnect(QLatin1String("onState"), m_ui->rButton);
+    initAndConnect(QLatin1String("onState"), m_ui->aButton);
+    initAndConnect(QLatin1String("onState"), m_ui->zButton);
+    initAndConnect(QLatin1String("onState"), m_ui->yButton);
+    initAndConnect(QLatin1String("onState"), m_ui->ballOutButton);
+
+    // datamodel update
+    connect(m_machine, &Pinball::event_updateScore,
+            this, &MainWindow::updateScore);
 
     // gui interaction
-    connect(ui->cButton, &QAbstractButton::clicked,
+    connect(m_ui->cButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("letterTriggered.C");
             });
-    connect(ui->rButton, &QAbstractButton::clicked,
+    connect(m_ui->rButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("letterTriggered.R");
             });
-    connect(ui->aButton, &QAbstractButton::clicked,
+    connect(m_ui->aButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("letterTriggered.A");
             });
-    connect(ui->zButton, &QAbstractButton::clicked,
+    connect(m_ui->zButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("letterTriggered.Z");
             });
-    connect(ui->yButton, &QAbstractButton::clicked,
+    connect(m_ui->yButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("letterTriggered.Y");
             });
-    connect(ui->startButton, &QAbstractButton::clicked,
+    connect(m_ui->startButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("startTriggered");
             });
-    connect(ui->ballOutButton, &QAbstractButton::clicked,
+    connect(m_ui->ballOutButton, &QAbstractButton::clicked,
             [this] { m_machine->submitEvent("ballOutTriggered");
             });
-
-    // datamodel update
-    connect(m_machine, &Pinball::event_updateScore,
-            this, &MainWindow::updateScore);
 }
 
 MainWindow::~MainWindow()
 {
-    delete ui;
+    delete m_ui;
 }
 
 void MainWindow::initAndConnect(const QString &state, QWidget *widget)
@@ -121,8 +121,8 @@ void MainWindow::initAndConnect(const QString &state, QWidget *widget)
 void MainWindow::updateScore(const QVariant &data)
 {
     const QString highScore = data.toMap().value("highScore").toString();
-    ui->highScoreLabel->setText(highScore);
+    m_ui->highScoreLabel->setText(highScore);
     const QString score = data.toMap().value("score").toString();
-    ui->scoreLabel->setText(score);
+    m_ui->scoreLabel->setText(score);
 }
 
diff --git a/examples/pinball-ecmascript-common/mainwindow.h b/examples/pinball-ecmascript-common/mainwindow.h
index b8f8c02..26a24a5 100644
--- a/examples/pinball-ecmascript-common/mainwindow.h
+++ b/examples/pinball-ecmascript-common/mainwindow.h
@@ -62,7 +62,7 @@ public:
 private:
     void initAndConnect(const QString &state, QWidget *widget);
     void updateScore(const QVariant &data);
-    QT_PREPEND_NAMESPACE(Ui::MainWindow) *ui;
+    QT_PREPEND_NAMESPACE(Ui::MainWindow) *m_ui;
     Pinball *m_machine;
 };
 
diff --git a/examples/pinball-ecmascript-widgets-static/doc/src/pinball-ecmascript-widgets-static.qdoc b/examples/pinball-ecmascript-widgets-static/doc/src/pinball-ecmascript-widgets-static.qdoc
index f44f6d4..e831744 100644
--- a/examples/pinball-ecmascript-widgets-static/doc/src/pinball-ecmascript-widgets-static.qdoc
+++ b/examples/pinball-ecmascript-widgets-static/doc/src/pinball-ecmascript-widgets-static.qdoc
@@ -26,6 +26,13 @@
     \brief Demonstrates how the internal
     logic of the application can be encapsulated in a scxml file.
 
+    This example demonstrates a clear separation
+    between chosen user interface, which may be easily replaced,
+    and internal logic encapsulated in the scxml file,
+    which may stay the same for different user interface.
+
+    \section1 Pinball Features
+
     \image pinball-ecmascript-widgets-static.png Screenshot of the Pinball example
 
     \e {Pinball EcmaScript Widgets Static Example} mimics a pinball game.
@@ -41,8 +48,6 @@
     pressing a target's button can mimic hitting a real pinball
     target with a ball.
 
-    \section1 Pinball Features
-
     Our pinball contains the following features:
     \list
     \li Initially and when the game ends the pinball table
@@ -78,11 +83,7 @@
     \li When jackpot gets collected the \uicontrol JACKPOT light should stay on.
     \endlist
 
-    This example also demonstrates a clear separation
-    between chosen user interface (which may be easily replaced) and internal logic
-    (which should stay the same for different user interface).
-
-    \section1 Internal Logic Description
+    \section1 SCXML Part: Internal Logic Description
 
     The pinball.scxml file describes the internal logic implemented for
     pinball game.
@@ -482,6 +483,62 @@
     is active we turn on or off all the lights accordingly
     to the description of the pinball table.
 
-    \target cpp
+    \section1 GUI Part: User Interface Description
 
+    The GUI part of the application consists of a mainwindow.ui
+    file which describes the static user interface of the game.
+
+    \target cpp
+    \section1 CPP Part: Glue GUI with SCXML
+
+    The CPP part of the application consists of a
+    MainWindow class which glues the GUI part with the SCXML part.
+    The class is declared in mainwindow.h.
+
+    \quotefromfile pinball-ecmascript-common/mainwindow.h
+    \skipto Pinball
+    \printuntil };
+
+    The MainWindow class holds the pointer to the
+    \c {Pinball *m_machine} which is the state machine
+    class automatically generated by Qt out of SCMXL file
+    and the pointer to the \c {Ui::MainWindow *m_ui} which
+    describes the GUI part. It also declares two helper methods.
+
+    \quotefromfile pinball-ecmascript-common/mainwindow.cpp
+    \skipto #include
+    \printuntil /}$/
+
+    The constructor of the MainWindow class
+    instantiates the GUI part of the application
+    and stores the pointer to the passed \c Pinball state machine.
+    It also initializes the GUI part and glues the
+    GUI part with the state machine by connecting
+    their communication interfaces together.
+
+    The \c initAndConnect() method connects
+    the state with the corresponding GUI widget by
+    binding its activity with the enablement of the widget,
+    so that whenever the state is active its corresponding
+    widget is enabled and whenever the state is inactive
+    the widget is disabled. We do that for all lights, targets
+    and description lables.
+
+    We also connect to the \c event_updateScore propagated
+    by the state machine and update the score displays
+    with the values passed with the event.
+
+    The info about hitting any GUI target needs to be passed
+    to the state machine and we do that by connecting
+    all target buttons' \c clicked signals to the lambda expressions
+    which submit corresponding event into the state machine.
+
+    \quotefromfile pinball-ecmascript-widgets-static/pinball-ecmascript-widgets-static.cpp
+    \skipto #include
+    \printuntil /}$/
+
+    Finally, inside the main() function we instantiate the
+    \c app application object, \c Pinball state machine
+    and \c MainWindow GUI class. We initialize and start the state machine,
+    show the main window and execute the application.
 */