/****************************************************************************
**
** 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/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.

*/