/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example animation/stickman
    \title Stickman Example

    \brief The Stickman example shows how to animate transitions in a state
    machine to implement key frame animations.

    \image stickman-example.png
    
    In this example, we will write a small application which animates the joints in a skeleton and
    projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the
    "alive" state, he can be performing different actions defined by key frame animations. 
    
    Animations are implemented as composite states. Each child state of the animation state 
    represents a frame in the animation by setting the position of each joint in the stickman's 
    skeleton to the positions defined for the particular frame. The frames are then bound together 
    with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus,
    the machine will enter the state representing the next frame in the animation immediately after
    it has finished animating into the previous frame.
    
    \image stickman-example1.png
        
    The states for an animation is constructed by reading a custom animation file format and 
    creating states that assign values to the the "position" properties of each of the nodes in the 
    skeleton graph. 
    
    \snippet animation/stickman/lifecycle.cpp 1
    
    The states are then bound together with signal transitions that listen to the
    propertiesAssigned() signal.
    
    \snippet animation/stickman/lifecycle.cpp 2
    
    The last frame state is given a transition to the first one, so that the animation will loop
    until it is interrupted when a transition out from the animation state is taken. To get smooth 
    animations between the different key frames, we set a default animation on the state machine. 
    This is a parallel animation group which contains animations for all the "position" properties 
    and will be selected by default when taking any transition that leads into a state that assigns 
    values to these properties.
    
    \snippet animation/stickman/lifecycle.cpp 3
    
    Several such animation states are constructed, and are placed together as children of a top 
    level "alive" state which represents the stickman life cycle. Transitions go from the parent
    state to the child state to ensure that each of the child states inherit them. 
    
    \image stickman-example2.png
    
    This saves us the effort of connect every state to every state with identical transitions. The 
    state machine  makes sure that transitions between the key frame animations are also smooth by 
    applying the default animation when interrupting one and starting another.
        
    Finally, there is a transition out from the "alive" state and into the "dead" state. This is 
    a custom transition type called LightningSrikesTransition which samples every second and 
    triggers at random (one out of fifty times on average.) 
    
    \snippet animation/stickman/lifecycle.cpp 4
    
    When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to 
    pause for a brief period of time while the background color of the scene is white. This gives us 
    a flash effect when the lightning strikes.
    
    \snippet animation/stickman/lifecycle.cpp 5
    
    We start and stop a QTimer object when entering and exiting the state. Then we transition into
    the "dead" state when the timer times out.
    
    \snippet animation/stickman/lifecycle.cpp 0
    
    When the machine is in the "dead" state, it will be unresponsive. This is because the "dead" 
    state has no transitions leading out.
    
    \image stickman-example3.png
    
*/