doc/src/examples/stickman.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example animation/stickman
  30     \title Stickman Example
  31
  32     \brief The Stickman example shows how to animate transitions in a state machine to implement key frame
  33     animations.
  34
  35     \image stickman-example.png
  36
  37     In this example, we will write a small application which animates the joints in a skeleton and
  38     projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the
  39     "alive" state, he can be performing different actions defined by key frame animations.
  40
  41     Animations are implemented as composite states. Each child state of the animation state
  42     represents a frame in the animation by setting the position of each joint in the stickman's
  43     skeleton to the positions defined for the particular frame. The frames are then bound together
  44     with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus,
  45     the machine will enter the state representing the next frame in the animation immediately after
  46     it has finished animating into the previous frame.
  47
  48     \image stickman-example1.png
  49
  50     The states for an animation is constructed by reading a custom animation file format and
  51     creating states that assign values to the the "position" properties of each of the nodes in the
  52     skeleton graph.
  53
  54     \snippet examples/animation/stickman/lifecycle.cpp 1
  55
  56     The states are then bound together with signal transitions that listen to the
  57     propertiesAssigned() signal.
  58
  59     \snippet examples/animation/stickman/lifecycle.cpp 2
  60
  61     The last frame state is given a transition to the first one, so that the animation will loop
  62     until it is interrupted when a transition out from the animation state is taken. To get smooth
  63     animations between the different key frames, we set a default animation on the state machine.
  64     This is a parallel animation group which contains animations for all the "position" properties
  65     and will be selected by default when taking any transition that leads into a state that assigns
  66     values to these properties.
  67
  68     \snippet examples/animation/stickman/lifecycle.cpp 3
  69
  70     Several such animation states are constructed, and are placed together as children of a top
  71     level "alive" state which represents the stickman life cycle. Transitions go from the parent
  72     state to the child state to ensure that each of the child states inherit them.
  73
  74     \image stickman-example2.png
  75
  76     This saves us the effort of connect every state to every state with identical transitions. The
  77     state machine  makes sure that transitions between the key frame animations are also smooth by
  78     applying the default animation when interrupting one and starting another.
  79
  80     Finally, there is a transition out from the "alive" state and into the "dead" state. This is
  81     a custom transition type called LightningSrikesTransition which samples every second and
  82     triggers at random (one out of fifty times on average.)
  83
  84     \snippet examples/animation/stickman/lifecycle.cpp 4
  85
  86     When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to
  87     pause for a brief period of time while the background color of the scene is white. This gives us
  88     a flash effect when the lightning strikes.
  89
  90     \snippet examples/animation/stickman/lifecycle.cpp 5
  91
  92     We start and stop a QTimer object when entering and exiting the state. Then we transition into
  93     the "dead" state when the timer times out.
  94
  95     \snippet examples/animation/stickman/lifecycle.cpp 0
  96
  97     When the machine is in the "dead" state, it will be unresponsive. This is because the "dead"
  98     state has no transitions leading out.
  99
 100     \image stickman-example3.png
 101
 102 */