Doc: Integrated the Rogue (state machine) example.

Reviewed-by: Kent Hansen

4 files changed, 223 insertions, 0 deletions

diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc
index 74a9bd8..7f9264b 100644
--- a/doc/src/examples.qdoc
+++ b/doc/src/examples.qdoc
@@ -330,6 +330,7 @@
     \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster
     \o \l{statemachine/factorial}{Factorial States}\raisedaster
     \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster
+    \o \l{statemachine/rogue}{Rogue}\raisedaster
     \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster
     \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster
     \endlist
diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc
new file mode 100644
index 0000000..8fa2c69
--- /dev/null
+++ b/doc/src/examples/rogue.qdoc
@@ -0,0 +1,222 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example statemachine/rogue
+    \title Rogue Example
+
+    The Rogue example shows how to use the Qt state machine for event
+    handling.
+
+    \image rogue-example.png
+
+    This example implements a simple text based game. Do you see the
+    \c{@} in the screenshot? That's you, the rogue. The \c{#}
+    characters are walls, and the dots represent floor. In a real
+    game, other ASCII characters would represent all kinds of objects
+    and creatures. For instance, ancient dragons (\c{D}'s) or food
+    rations (\c{%}'s). But let's not get carried away. In this game,
+    the rogue is simply running around in an empty room.
+
+    The rogue is moved with the keypad (2, 4, 8, 6). That aside, we
+    have implemented a \c quit command that triggers if the player
+    types \c {q}. The player is then asked if he/she really wants to
+    quit.
+
+    Most games have commands that need more than one key press and
+    that may require a different sequence of keys based on questions
+    asked the user. In this game, only the \c quit command falls under
+    this category, but for the sake of argument, let's imagine a
+    fully-fledged game with a rich set of commands. If we were to
+    implement these by catching key events in
+    \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of
+    class member variables to track the sequence of keys already typed
+    (or find some other way of deducing the current state of a
+    command). This can easily lead to spaghetti, which is--as we all
+    well know, I'm sure--unpleasant. With a state machine, on the
+    other hand, separate states can wait for a single key press, and
+    that makes our lives a lot simpler.
+
+    The example consists of two classes:
+
+    \list
+        \o \c Window draws the text display of the game and sets
+            up the state machine. The window also has a status bar
+            above the area in which the rouge moves.
+        \o \c MovementTransition is a transition that carries out
+            a single move of the rogue.
+    \endlist
+
+    Before we embark on a code walkthrough, it is necessary to take a
+    closer look at the design of the machine. Here is a state chart
+    that shows what we want to achieve:
+
+    \image rogue-statechart.png
+
+    The input state waits for a key press to start a new command.
+    When receiving a key it recognizes, it transitions to one of the
+    two commands of the game; though, as we will see, movement is
+    handled by the transition itself. The quit state waits for the
+    player to answer yes or no (by typing \c y or \c n) when asked
+    whether he/she really wants to quit the game.
+
+    The chart demonstrates how we use one state to wait for a single
+    key press. The press received may trigger one of the transitions
+    connected to the state.
+
+    \section1 Window Class Definition
+
+    The \c Window class is a widget that draws the text display of the
+    game. It also sets up the state machine, i.e., creates and
+    connects the states in the machine. It is the key events from this
+    widget that are used by the machine.
+
+    \snippet examples/statemachine/rogue/window.h 0
+
+    \c Direction specifies the direction in which the rogue is to
+    move. We use this in \c movePlayer(), which moves the rogue and
+    repaints the window. The game has a status line above the area in
+    which the rogue moves. The \c status property contains the text of
+    this line. We use a property because the QState class allows
+    setting any Qt \l{Qt's Property System}{property} when entered.
+    More on this later.
+
+    \snippet examples/statemachine/rogue/window.h 1
+
+    The \c map is an array with the characters that are currently
+    displayed. We set up the array in \c setupMap(), and update it
+    when the rogue is moved. \c pX and \c pY is the current position
+    of the rogue. \c WIDTH and \c HEIGHT are macros specifying the
+    dimensions of the map.
+
+    The \c paintEvent() function is left out of this walkthrough. We
+    also do not discuss other code that does not concern the state
+    machine (the \c setupMap(), \c status(), \c setStatus(), \c
+    movePlayer(), and \c sizeHint() functions). If you wish to take a
+    look at the code, click on the link for the \c window.cpp file at
+    the top of this page.
+
+    \section1 Window Class Implementation
+
+    Here is the constructor of \c Window:
+
+    \snippet examples/statemachine/rogue/window.cpp 0
+    \dots
+    \snippet examples/statemachine/rogue/window.cpp 1
+
+    The player starts off at position (5, 5). We then set up the map
+    and statemachine. Let's proceed with the \c buildMachine()
+    function:
+
+    \snippet examples/statemachine/rogue/window.cpp 2
+
+    We enter \c inputState when the machine is started and from the \c
+    quitState if the user wants to continue playing. We then set the
+    status to a helpful reminder of how to play the game.
+
+    First, the \c Movement transition is added to the input state.
+    This will enable the rogue to be moved with the keypad.  Notice
+    that we don't set a target state for the movement transition. This
+    will cause the transition to be triggered (and the
+    \l{QAbstractTransition::}{onTransition()} function to be invoked),
+    but the machine will not leave the \c inputState. If we had set \c
+    inputState as the target state, we would first have left and then
+    entered the \c inputState again.
+
+    \snippet examples/statemachine/rogue/window.cpp 3
+
+    When we enter \c quitState, we update the status bar of the
+    window.
+    
+    \c QKeyEventTransition is a utility class that removes the hassle
+    of implementing transitions for \l{QKeyEvent}s. We simply need to
+    specify the key on which the transition should trigger and the
+    target state of the transition.
+
+    \snippet examples/statemachine/rogue/window.cpp 4
+
+    The transition from \c inputState allows triggering the quit state
+    when the player types \c {q}.
+    
+    \snippet examples/statemachine/rogue/window.cpp 5
+
+    The machine is set up, so it's time to start it.
+
+    \section1 The MovementTransition Class
+
+    \c MovementTransition is triggered when the player request the
+    rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in
+    the \c inputState.
+
+    \snippet examples/statemachine/rogue/movementtransition.h 0
+
+    In the constructor, we tell QEventTransition to only send
+    \l{QEvent::}{KeyPress} events to the
+    \l{QAbstractTransition::}{eventTest()} function:
+
+    \snippet examples/statemachine/rogue/movementtransition.h 1
+
+    The KeyPress events come wrapped in \l{QWrappedEvent}s. \c event
+    must be confirmed to be a wrapped event because Qt uses other
+    events internally. After that, it is simply a matter of checking
+    which key has been pressed.
+
+    Let's move on to the \c onTransition() function:
+
+    \snippet examples/statemachine/rogue/movementtransition.h 2
+
+    When \c onTransition() is invoked, we know that we have a
+    \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, i.e., the event
+    is already unwrapped.
+
+    \section1 The Roguelike Tradition
+
+    You might have been wondering why the game features a rogue. Well,
+    these kinds of text based dungeon exploration games date back to a
+    game called, yes, "Rogue". Although outflanked by the technology
+    of modern 3D computer games, roguelikes have a solid community of
+    hard-core, devoted followers.
+
+    Playing these games can be surprisingly addictive (despite the
+    lack of graphics). Angband, the perhaps most well-known rougelike,
+    is found here: \l{http://rephial.org/}.
+*/
+
diff --git a/doc/src/images/rogue-example.png b/doc/src/images/rogue-example.png
new file mode 100644
index 0000000..7aeb0e5
--- /dev/null
+++ b/doc/src/images/rogue-example.png
diff --git a/doc/src/images/rogue-statechart.png b/doc/src/images/rogue-statechart.png
new file mode 100644
index 0000000..c5f4048
--- /dev/null
+++ b/doc/src/images/rogue-statechart.png