1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (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 qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example statemachine/tankgame
\title Tank Game Example
The Tank Game example is part of the in \l{The State Machine Framework}. It shows how to use
parallel states to implement artificial intelligence controllers that run in parallel, and error
states to handle run-time errors in parts of the state graph created by external plugins.
\image tankgame-example.png
In this example we write a simple game. The application runs a state machine with two main
states: A "stopped" state and a "running" state. The user can load plugins from the disk by
selecting the "Add tank" menu item.
When the "Add tank" menu item is selected, the "plugins" subdirectory in the example's
directory is searched for compatible plugins. If any are found, they will be listed in a
dialog box created using QInputDialog::getItem().
\snippet examples/statemachine/tankgame/mainwindow.cpp 1
If the user selects a plugin, the application will construct a TankItem object, which inherits
from QGraphicsItem and QObject, and which implements an agreed-upon interface using the
meta-object mechanism.
\snippet examples/statemachine/tankgame/tankitem.h 0
The tank item will be passed to the plugin's create() function. This will in turn return a
QState object which is expected to implement an artificial intelligence which controls the
tank and attempts to destroy other tanks it detects.
\snippet examples/statemachine/tankgame/mainwindow.cpp 2
Each returned QState object becomes a descendant of a \c region in the "running" state, which is
defined as a parallel state. This means that entering the "running" state will cause each of the
plugged-in QState objects to be entered simultaneously, allowing the tanks to run independently
of each other.
\snippet examples/statemachine/tankgame/mainwindow.cpp 0
The maximum number of tanks on the map is four, and when this number is reached, the
"Add tank" menu item should be disabled. This is implemented by giving the "stopped" state two
children which define whether the map is full or not.
\snippet examples/statemachine/tankgame/mainwindow.cpp 5
To make sure that we go into the correct child state when returning from the "running" state
(if the "Stop game" menu item is selected while the game is running) we also give the "stopped"
state a history state which we make the initial state of "stopped" state.
\snippet examples/statemachine/tankgame/mainwindow.cpp 3
Since part of the state graph is defined by external plugins, we have no way of controlling
whether they contain errors. By default, run-time errors are handled in the state machine by
entering a top level state which prints out an error message and never exits. If we were to
use this default behavior, a run-time error in any of the plugins would cause the "running"
state to exit, and thus all the other tanks to stop running as well. A better solution would
be if the broken plugin was disabled and the rest of the tanks allowed to continue as before.
This is done by setting the error state of the plugin's top-most state to a special error state
defined specifically for the plugin in question.
\snippet examples/statemachine/tankgame/mainwindow.cpp 4
If a run-time error occurs in \c pluginState or any of its descendants, the state machine will
search the hierarchy of ancestors until it finds a state whose error state is different from
\c null. (Note that if we are worried that a plugin could inadvertedly be overriding our
error state, we could search the descendants of \c pluginState and verify that their error
states are set to \c null before accepting the plugin.)
The specialized \c errorState sets the "enabled" property of the tank item in question to false,
causing it to be painted with a red cross over it to indicate that it is no longer running.
Since the error state is a child of the same region in the parallel "running" state as
\c pluginState, it will not exit the "running" state, and the other tanks will continue running
without disruption.
*/
|
