source: trunk/doc/src/frameworks-technologies/statemachine.qdoc@ 651

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.1, 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group statemachine
    \title State Machine Classes
*/

/*!
  \page statemachine-api.html
  \title The State Machine Framework
  \brief An overview of the State Machine framework for constructing and executing state graphs.

  \ingroup frameworks-technologies

  \tableofcontents

  The State Machine framework provides classes for creating and executing
  state graphs. The concepts and notation are based on those from Harel's
  \l{Statecharts: A visual formalism for complex systems}{Statecharts}, which
  is also the basis of UML state diagrams. The semantics of state machine
  execution are based on \l{State Chart XML: State Machine Notation for
  Control Abstraction}{State Chart XML (SCXML)}.

  Statecharts provide a graphical way of modeling how a system reacts to
  stimuli. This is done by defining the possible \e states that the system can
  be in, and how the system can move from one state to another (\e transitions
  between states). A key characteristic of event-driven systems (such as Qt
  applications) is that behavior often depends not only on the last or current
  event, but also the events that preceded it. With statecharts, this
  information is easy to express.

  The State Machine framework provides an API and execution model that can be
  used to effectively embed the elements and semantics of statecharts in Qt
  applications. The framework integrates tightly with Qt's meta-object system;
  for example, transitions between states can be triggered by signals, and
  states can be configured to set properties and invoke methods on QObjects.
  Qt's event system is used to drive the state machines.

  The state graph in the State Machine framework is hierarchical. States can be nested inside of
  other states, and the current configuration of the state machine consists of the set of states
  which are currently active. All the states in a valid configuration of the state machine will
  have a common ancestor.

  \section1 Classes in the State Machine Framework

  These classes are provided by qt for creating event-driven state machines.
  
  \annotatedlist statemachine

  \section1 A Simple State Machine

  To demonstrate the core functionality of the State Machine API, let's look
  at a small example: A state machine with three states, \c s1, \c s2 and \c
  s3. The state machine is controlled by a single QPushButton; when the button
  is clicked, the machine transitions to another state. Initially, the state
  machine is in state \c s1. The statechart for this machine is as follows:

    \img statemachine-button.png
    \omit
    \caption This is a caption
    \endomit

  The following snippet shows the code needed to create such a state machine.
  First, we create the state machine and states:

  \snippet doc/src/snippets/statemachine/main.cpp 0

  Then, we create the transitions by using the QState::addTransition()
  function:

  \snippet doc/src/snippets/statemachine/main.cpp 1

  Next, we add the states to the machine and set the machine's initial state:

  \snippet doc/src/snippets/statemachine/main.cpp 2

  Finally, we start the state machine:

  \snippet doc/src/snippets/statemachine/main.cpp 3

  The state machine executes asynchronously, i.e. it becomes part of your
  application's event loop.

  \section1 Doing Useful Work on State Entry and Exit

  The above state machine merely transitions from one state to another, it
  doesn't perform any operations. The QState::assignProperty() function can be
  used to have a state set a property of a QObject when the state is
  entered. In the following snippet, the value that should be assigned to a
  QLabel's text property is specified for each state:

  \snippet doc/src/snippets/statemachine/main.cpp 4

  When any of the states is entered, the label's text will be changed
  accordingly.

  The QState::entered() signal is emitted when the state is entered, and the
  QState::exited() signal is emitted when the state is exited. In the
  following snippet, the button's showMaximized() slot will be called when
  state \c s3 is entered, and the button's showMinimized() slot will be called
  when \c s3 is exited:

  \snippet doc/src/snippets/statemachine/main.cpp 5

  Custom states can reimplement QAbstractState::onEntry() and
  QAbstractState::onExit().

  \section1 State Machines That Finish

  The state machine defined in the previous section never finishes. In order
  for a state machine to be able to finish, it needs to have a top-level \e
  final state (QFinalState object). When the state machine enters a top-level
  final state, the machine will emit the QStateMachine::finished() signal and
  halt.