diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/examples.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/examples/rogue.qdoc | 222 | ||||
| -rw-r--r-- | doc/src/images/rogue-example.png | bin | 0 -> 10364 bytes | |||
| -rw-r--r-- | doc/src/images/rogue-statechart.png | bin | 0 -> 2490 bytes |
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 Binary files differnew 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 Binary files differnew file mode 100644 index 0000000..c5f4048 --- /dev/null +++ b/doc/src/images/rogue-statechart.png |
