Merge branch 'kinetic-animations' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

Conflicts:
	src/corelib/animation/qanimationgroup.cpp
	src/corelib/animation/qvariantanimation.cpp
	src/gui/graphicsview/qgraphicsitem.cpp

26 files changed, 1334 insertions, 56 deletions

diff --git a/doc/src/animation.qdoc b/doc/src/animation.qdoc
index f8b6d4c..7a4e778 100644
--- a/doc/src/animation.qdoc
+++ b/doc/src/animation.qdoc
@@ -40,7 +40,7 @@
 ****************************************************************************/
 
 /*!
-    \page animation.html
+    \page animation-overview.html
     \title The Animation Framework
     \ingroup architecture
     \ingroup group_animation
@@ -64,7 +64,10 @@
 
     We will in this section take a high-level look at the animation
     framework's architecture and how it is used to animate Qt
-    properties.
+    properties. The following diagram shows the most important classes
+    in the animation framework.
+
+    \image animations-architecture.png
 
     The animation framework foundation consists of the base class
     QAbstractAnimation, and its two subclasses QVariantAnimation and
@@ -132,7 +135,7 @@
     \endcode
 
     This code will move \c button from the top left corner of the
-    screen to the position (250, 250).
+    screen to the position (250, 250) in 10 seconds (10000 milliseconds).
 
     The example above will do a linear interpolation between the
     start and end value. It is also possible to set values
@@ -162,7 +165,7 @@
     that is not declared as a Qt property. The only requirement is
     that this value has a setter. You can then subclass the class
     containing the value and declare a property that uses this setter.
-    Note that all Qt properties requires a getter, so you will need to
+    Note that each Qt property requires a getter, so you will need to
     provide a getter yourself if this is not defined.
 
     \code
@@ -184,9 +187,9 @@
     \section1 Animations and the Graphics View Framework
 
     When you want to animate \l{QGraphicsItem}s, you also use
-    QPropertyAnimation. But, unfortunetly, QGraphicsItem does not
-    inherit QObject. A good solution is to subclass the graphics item
-    you wish to animate. This class will then also inherit QObject.
+    QPropertyAnimation. However, QGraphicsItem does not inherit QObject.
+    A good solution is to subclass the graphics item you wish to animate.
+    This class will then also inherit QObject.
     This way, QPropertyAnimation can be used for \l{QGraphicsItem}s.
     The example below shows how this is done. Another possibility is
     to inherit QGraphicsWidget, which already is a QObject.
@@ -326,7 +329,7 @@
     When using a \l{The State Machine Framework}{state machine}, we
     have a special state, QAnimationState, that will play one or more
     animations.
-        
+
     The QState::addAnimatedTransition() convenience function lets you
     associate an animation to a state transition. The function will
     create the QAnimationState for you, and insert it into the state
diff --git a/doc/src/diagrams/animations-architecture.svg b/doc/src/diagrams/animations-architecture.svg
new file mode 100644
index 0000000..0246510
--- /dev/null
+++ b/doc/src/diagrams/animations-architecture.svg
@@ -0,0 +1,351 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="950.00006"
+   height="365.28983"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.46"
+   sodipodi:docname="animations-architecture.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   version="1.0">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend"
+       style="overflow:visible">
+      <path
+         id="path3736"
+         style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z"
+         transform="scale(-0.6,-0.6)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Lend"
+       style="overflow:visible">
+      <path
+         id="path3730"
+         style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z"
+         transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow1Lend"
+       style="overflow:visible">
+      <path
+         id="path3712"
+         d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+         transform="matrix(-0.8,0,0,-0.8,-10,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="TriangleOutL"
+       style="overflow:visible">
+      <path
+         id="path3852"
+         d="M 5.77,0 L -2.88,5 L -2.88,-5 L 5.77,0 z"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+         transform="scale(0.8,0.8)" />
+    </marker>
+    <linearGradient
+       id="linearGradient3165">
+      <stop
+         style="stop-color:#c8c8dc;stop-opacity:1;"
+         offset="0"
+         id="stop3167" />
+      <stop
+         style="stop-color:#b4b4c8;stop-opacity:0;"
+         offset="1"
+         id="stop3169" />
+    </linearGradient>
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective10" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient3171"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-257.93754,-842.42203)" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient3183"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-383.02298,-676.69717)"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient3191"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-382.93759,-1004.922)"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient7165"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-483.69907,-593.77419)"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient7195"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-571.87523,-1167.422)"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3165"
+       id="linearGradient7203"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.2195969,0,0,3.7006494,-572.46592,-841.2256)"
+       x1="249.25"
+       y1="89.862183"
+       x2="475.75"
+       y2="89.862183" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98994949"
+     inkscape:cx="276.75951"
+     inkscape:cy="155.06417"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="true"
+     inkscape:snap-bbox="true"
+     inkscape:window-width="1592"
+     inkscape:window-height="1124"
+     inkscape:window-x="0"
+     inkscape:window-y="0">
+    <inkscape:grid
+       type="xygrid"
+       id="grid2383"
+       visible="true"
+       enabled="true"
+       units="pt"
+       spacingx="2pt"
+       spacingy="2pt" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-121.77519,-152.95286)">
+    <rect
+       style="opacity:1;fill:url(#linearGradient3171);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect2385"
+       width="49.409317"
+       height="277.54871"
+       x="-203.03828"
+       y="-648.64777"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="380.311"
+       y="185.86879"
+       id="text3173"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan3175"
+         x="380.311"
+         y="185.86879">QAbstractAnimation</tspan></text>
+    <rect
+       style="opacity:1;fill:url(#linearGradient3183);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3177"
+       width="49.409317"
+       height="277.54871"
+       x="-328.12369"
+       y="-482.92297"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="221.80489"
+       y="310.95419"
+       id="text3179"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan3181"
+         x="221.80489"
+         y="310.95419">QVariantAnimation</tspan></text>
+    <rect
+       style="opacity:1;fill:url(#linearGradient3191);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3185"
+       width="49.409317"
+       height="277.54871"
+       x="-328.03827"
+       y="-811.14777"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="564.13324"
+       y="310.86877"
+       id="text3187"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan3189"
+         x="564.13324"
+         y="310.86877">QAnimationGroup</tspan></text>
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 346.77519,279.39048 L 346.77519,241.89048 L 509.27519,241.89048 L 509.27519,204.39048"
+       id="path3195"
+       sodipodi:nodetypes="cccc" />
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 671.77519,279.39048 L 671.77519,241.89048 L 509.27519,241.89048"
+       id="path7137"
+       sodipodi:nodetypes="ccc" />
+    <rect
+       style="opacity:1;fill:url(#linearGradient7165);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect7159"
+       width="49.409317"
+       height="277.54871"
+       x="-428.7998"
+       y="-400"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="131.66315"
+       y="411.63031"
+       id="text7161"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan7163"
+         x="131.66315"
+         y="411.63031">QPropertyAnimation</tspan></text>
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 309.27519,379.39048 L 309.27519,329.39048"
+       id="path7167"
+       sodipodi:nodetypes="cc" />
+    <rect
+       style="opacity:1;fill:url(#linearGradient7195);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect7189"
+       width="49.409317"
+       height="375"
+       x="-516.97589"
+       y="-1071.0991"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="703.17139"
+       y="499.8064"
+       id="text7191"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan7193"
+         x="703.17139"
+         y="499.8064">QSequentialAnimationGroup</tspan></text>
+    <rect
+       style="opacity:1;fill:url(#linearGradient7203);fill-opacity:1;stroke:#202020;stroke-width:1.35220754;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect7197"
+       width="50"
+       height="350"
+       x="-517.56659"
+       y="-647.45129"
+       ry="12.582828"
+       rx="10.562523"
+       transform="matrix(0,-1,-1,0,0,0)" />
+    <text
+       xml:space="preserve"
+       style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:DejaVu Sans Mono;-inkscape-font-specification:DejaVu Sans Mono"
+       x="306.46109"
+       y="500.39709"
+       id="text7199"
+       sodipodi:linespacing="100%"><tspan
+         sodipodi:role="line"
+         id="tspan7201"
+         x="306.46109"
+         y="500.39709">QParallelAnimationGroup</tspan></text>
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 859.27519,466.89048 L 859.27519,391.89048 L 671.77519,391.89048"
+       id="path7205"
+       sodipodi:nodetypes="ccc" />
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 496.77519,466.89048 L 496.77519,391.89048 L 671.77519,391.89048 L 671.77519,329.39048"
+       id="path7207"
+       sodipodi:nodetypes="cccc" />
+  </g>
+</svg>
diff --git a/doc/src/examples-overview.qdoc b/doc/src/examples-overview.qdoc
index 549574d..92ccd4e 100644
--- a/doc/src/examples-overview.qdoc
+++ b/doc/src/examples-overview.qdoc
@@ -319,6 +319,14 @@
   from displaying Web pages within a Qt user interface to an implementation of
   a basic function Web browser.
 
+  \section1 \l{Qt Examples#State Machine}{State Machine}
+
+  Qt provides a powerful hierchical finite state machine through the Qt State
+  Machine classes.
+
+  These examples demonstrate the fundamental aspects of implementing
+  Statecharts with Qt.
+
   \section1 \l{Qt Examples#Qt for Embedded Linux}{Qt for Embedded Linux}
 
   \l{Qt Examples#Qt for Embedded Linux}{\inlineimage qt-embedded-examples.png
diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc
index 06d7727..6603390 100644
--- a/doc/src/examples.qdoc
+++ b/doc/src/examples.qdoc
@@ -311,7 +311,12 @@
     \section1 State Machine
 
     \list
+    \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster
+    \o \l{statemachine/factorial}{Factorial States}\raisedaster
+    \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster
     \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster
+    \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster
+    \o \l{statemachine/tankgame}{Tank Game}\raisedaster
     \endlist
 
     \section1 Threads
diff --git a/doc/src/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc
new file mode 100644
index 0000000..3b956bb
--- /dev/null
+++ b/doc/src/examples/eventtransitions.qdoc
@@ -0,0 +1,86 @@
+/****************************************************************************
+**
+** 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/eventtransitions
+    \title Event Transitions Example
+
+    The Event Transitions example shows how to use event transitions, a
+    feature of \l{The State Machine Framework}.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 0
+
+    The \c Window class's constructors begins by creating a button.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 1
+
+    Two states, \c s1 and \c s2, are created; upon entry they will assign
+    "Outside" and "Inside" to the button's text, respectively.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 2
+
+    When the button receives an event of type QEvent::Enter and the state
+    machine is in state \c s1, the machine will transition to state \c s2.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 3
+
+    When the button receives an event of type QEvent::Leave and the state
+    machine is in state \c s2, the machine will transition back to state \c
+    s1.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 4
+
+    Next, the state \c s3 is created. \c s3 will be entered when the button
+    receives an event of type QEvent::MouseButtonPress and the state machine
+    is in state \c s2. When the button receives an event of type
+    QEvent::MouseButtonRelease and the state machine is in state \c s3, the
+    machine will transition back to state \c s2.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 5
+
+    Finally, the states are added to the machine as top-level states, the
+    initial state is set to be \c s1 ("Outside"), and the machine is started.
+
+    \snippet examples/statemachine/eventtransitions/main.cpp 6
+
+    The main() function constructs a Window object and shows it.
+
+*/
diff --git a/doc/src/examples/factorial.qdoc b/doc/src/examples/factorial.qdoc
new file mode 100644
index 0000000..2a72e0a
--- /dev/null
+++ b/doc/src/examples/factorial.qdoc
@@ -0,0 +1,102 @@
+/****************************************************************************
+**
+** 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/factorial
+    \title Factorial States Example
+
+    The Factorial States example shows how to use \l{The State Machine
+    Framework} to calculate the factorial of an integer.
+
+    The statechart for calculating the factorial looks as follows:
+
+    \img factorial-example.png
+    \omit
+    \caption This is a caption
+    \endomit
+
+    In other words, the state machine calculates the factorial of 6 and prints
+    the result.
+
+    \snippet examples/statemachine/factorial/main.cpp 0
+
+    The Factorial class is used to hold the data of the computation, \c x and
+    \c fac. It also provides a signal that's emitted whenever the value of \c
+    x changes.
+
+    \snippet examples/statemachine/factorial/main.cpp 1
+
+    The FactorialLoopTransition class implements the guard (\c x > 1) and
+    calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial
+    loop.
+
+    \snippet examples/statemachine/factorial/main.cpp 2
+
+    The FactorialDoneTransition class implements the guard (\c x <= 1) that
+    terminates the factorial computation. It also prints the final result to
+    standard output.
+
+    \snippet examples/statemachine/factorial/main.cpp 3
+
+    The application's main() function first creates the application object, a
+    Factorial object and a state machine.
+
+    \snippet examples/statemachine/factorial/main.cpp 4
+
+    The \c compute state is created, and the initial values of \c x and \c fac
+    are defined. A FactorialLoopTransition object is created and added to the
+    state.
+
+    \snippet examples/statemachine/factorial/main.cpp 5
+
+    A final state, \c done, is created, and a FactorialDoneTransition object
+    is created with \c done as its target state. The transition is then added
+    to the \c compute state.
+
+    \snippet examples/statemachine/factorial/main.cpp 6
+
+    The machine's initial state is set to be the \c compute state. We connect
+    the QStateMachine::finished() signal to the QCoreApplication::quit() slot,
+    so the application will quit when the state machine's work is
+    done. Finally, the state machine is started, and the application's event
+    loop is entered.
+
+ */
diff --git a/doc/src/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc
new file mode 100644
index 0000000..040e429
--- /dev/null
+++ b/doc/src/examples/pingpong.qdoc
@@ -0,0 +1,107 @@
+/****************************************************************************
+**
+** 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/pingpong
+    \title Ping Pong States Example
+
+    The Ping Pong States example shows how to use parallel states together
+    with custom events and transitions in \l{The State Machine Framework}.
+
+    This example implements a statechart where two states communicate by
+    posting events to the state machine. The state chart looks as follows:
+
+    \img pingpong-example.png
+    \omit
+    \caption This is a caption
+    \endomit
+
+    The \c pinger and \c ponger states are parallel states, i.e. they are
+    entered simultaneously and will take transitions independently of
+    eachother.
+
+    The \c pinger state will post the first \c ping event upon entry; the \c
+    ponger state will respond by posting a \c pong event; this will cause the
+    \c pinger state to post a new \c ping event; and so on.
+
+    \snippet examples/statemachine/pingpong/main.cpp 0
+
+    Two custom events are defined, \c PingEvent and \c PongEvent.
+
+    \snippet examples/statemachine/pingpong/main.cpp 1
+
+    The \c Pinger class defines a state that posts a \c PingEvent to the state
+    machine when the state is entered.
+
+    \snippet examples/statemachine/pingpong/main.cpp 2
+
+    The \c PingTransition class defines a transition that is triggered by
+    events of type \c PingEvent, and that posts a \c PongEvent (with a delay
+    of 500 milliseconds) to the state machine when the transition is
+    triggered.
+
+    \snippet examples/statemachine/pingpong/main.cpp 3
+
+    The \c PongTransition class defines a transition that is triggered by
+    events of type \c PongEvent, and that posts a \c PingEvent (with a delay
+    of 500 milliseconds) to the state machine when the transition is
+    triggered.
+
+    \snippet examples/statemachine/pingpong/main.cpp 4
+
+    The main() function begins by creating a state machine and a parallel
+    state group.
+
+    \snippet examples/statemachine/pingpong/main.cpp 5
+
+    Next, the \c pinger and \c ponger states are created, with the parallel
+    state group as their parent state. Note that the transitions are \e
+    targetless. When such a transition is triggered, the source state won't be
+    exited and re-entered; only the transition's onTransition() function will
+    be called, and the state machine's configuration will remain the same,
+    which is precisely what we want in this case.
+
+    \snippet examples/statemachine/pingpong/main.cpp 6
+
+    Finally, the group is added to the state machine, the machine is started,
+    and the application event loop is entered.
+
+  */
diff --git a/doc/src/examples/tankgame.qdoc b/doc/src/examples/tankgame.qdoc
new file mode 100644
index 0000000..ab3e0f4
--- /dev/null
+++ b/doc/src/examples/tankgame.qdoc
@@ -0,0 +1,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.
+
+*/
diff --git a/doc/src/examples/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc
index 16ee8ad..ae62127 100644
--- a/doc/src/examples/trafficlight.qdoc
+++ b/doc/src/examples/trafficlight.qdoc
@@ -1,11 +1,41 @@
 /****************************************************************************
 **
-** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 ** Contact: Qt Software Information (qt-info@nokia.com)
 **
-** This file is part of the $MODULE$ of the Qt Toolkit.
+** This file is part of the documentation of the Qt Toolkit.
 **
-** $TROLLTECH_DUAL_LICENSE$
+** $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$
 **
 ****************************************************************************/
 
@@ -26,30 +56,41 @@
     \snippet examples/statemachine/trafficlight/main.cpp 0
 
     The LightWidget class represents a single light of the traffic light. It
-    provides a setOn() function to turn the light on or off. It paints itself
-    in the color that's passed to the constructor.
+    provides an \c on property and two slots, turnOn() and turnOff(), to turn
+    the light on and off, respectively. The widget paints itself in the color
+    that's passed to the constructor.
 
-    \snippet examples/statemachine/trafficlight/main.cpp 2
+    \snippet examples/statemachine/trafficlight/main.cpp 1
 
     The TrafficLightWidget class represents the visual part of the traffic
-    light; it's a widget that contains three lights, and provides accessor
-    functions for these.
+    light; it's a widget that contains three lights arranged vertically, and
+    provides accessor functions for these.
 
-    \snippet examples/statemachine/trafficlight/main.cpp 1
+    \snippet examples/statemachine/trafficlight/main.cpp 2
 
-    The LightState class represents a state that turns a light on when the
-    state is entered, and off when the state is exited. The class is a timer,
-    and as we shall see the timeout is used to transition from one LightState
-    to another.
+    The createLightState() function creates a state that turns a light on when
+    the state is entered, and off when the state is exited. The state uses a
+    timer, and as we shall see the timeout is used to transition from one
+    LightState to another. Here is the statechart for the light state:
+
+    \img trafficlight-example1.png
+    \omit
+    \caption This is a caption
+    \endomit
 
     \snippet examples/statemachine/trafficlight/main.cpp 3
 
-    The TrafficLight class combines the TrafficLightWidget with control flow
-    based on the LightState class. The state graph has four states:
-    red-to-yellow, yellow-to-green, green-to-yellow and yellow-to-red. The
-    initial state is red-to-yellow; when the state's timer times out, the
-    state machine transitions to yellow-to-green. The same process repeats
-    through the other states.
+    The TrafficLight class combines the TrafficLightWidget with a state
+    machine.  The state graph has four states: red-to-yellow, yellow-to-green,
+    green-to-yellow and yellow-to-red. The initial state is red-to-yellow;
+    when the state's timer times out, the state machine transitions to
+    yellow-to-green. The same process repeats through the other states.
+    This is what the statechart looks like:
+
+    \img trafficlight-example2.png
+    \omit
+    \caption This is a caption
+    \endomit
 
     \snippet examples/statemachine/trafficlight/main.cpp 4
 
diff --git a/doc/src/examples/twowaybutton.qdoc b/doc/src/examples/twowaybutton.qdoc
new file mode 100644
index 0000000..87de2e8
--- /dev/null
+++ b/doc/src/examples/twowaybutton.qdoc
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** 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/twowaybutton
+    \title Two-way Button Example
+
+    The Two-way button example shows how to use \l{The State Machine
+    Framework} to implement a simple state machine that toggles the current
+    state when a button is clicked.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 0
+
+    The application's main() function begins by constructing the application
+    object, a button and a state machine.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 1
+
+    The state machine has two states; \c on and \c off. When either state is
+    entered, the text of the button will be set accordingly.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 2
+
+    When the state machine is in the \c off state and the button is clicked,
+    it will transition to the \c on state; when the state machine is in the \c
+    on state and the button is clicked, it will transition to the \c off
+    state.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 3
+
+    The states are added to the state machine; they become top-level (sibling)
+    states.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 4
+
+    The initial state is \c off; this is the state the state machine will
+    immediately transition to once the state machine is started.
+
+    \snippet examples/statemachine/twowaybutton/main.cpp 5
+
+    Finally, the button is resized and made visible, and the application event
+    loop is entered.
+
+*/
diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc
index 0411c3a..3c4da53 100644
--- a/doc/src/groups.qdoc
+++ b/doc/src/groups.qdoc
@@ -69,14 +69,14 @@
 */
 
 /*!
-    \group animations
+    \group animation
     \ingroup groups
 
     \title Animation Framework
     \brief Classes for animations, states and transitions.
 
     These classes provide a framework for creating both simple and complex
-    animations. The Animation Framework also provides states and animated
+    animations. \l{The Animation Framework} also provides states and animated
     transitions, making it easy to create animated stateful forms.
 */
 
diff --git a/doc/src/images/animations-architecture.png b/doc/src/images/animations-architecture.png
new file mode 100644
index 0000000..9b581af
--- /dev/null
+++ b/doc/src/images/animations-architecture.png
diff --git a/doc/src/images/factorial-example.png b/doc/src/images/factorial-example.png
new file mode 100644
index 0000000..8fb1cc6
--- /dev/null
+++ b/doc/src/images/factorial-example.png
diff --git a/doc/src/images/pingpong-example.png b/doc/src/images/pingpong-example.png
new file mode 100644
index 0000000..af707e4
--- /dev/null
+++ b/doc/src/images/pingpong-example.png
diff --git a/doc/src/images/statemachine-button-history.png b/doc/src/images/statemachine-button-history.png
index cd66478..7f51cae 100644
--- a/doc/src/images/statemachine-button-history.png
+++ b/doc/src/images/statemachine-button-history.png
diff --git a/doc/src/images/statemachine-button-nested.png b/doc/src/images/statemachine-button-nested.png
index 60360d1..762ac14 100644
--- a/doc/src/images/statemachine-button-nested.png
+++ b/doc/src/images/statemachine-button-nested.png
diff --git a/doc/src/images/statemachine-button.png b/doc/src/images/statemachine-button.png
index 75d9e53..10102bd 100644
--- a/doc/src/images/statemachine-button.png
+++ b/doc/src/images/statemachine-button.png
diff --git a/doc/src/images/statemachine-customevents.png b/doc/src/images/statemachine-customevents.png
new file mode 100644
index 0000000..62a4222
--- /dev/null
+++ b/doc/src/images/statemachine-customevents.png
diff --git a/doc/src/images/statemachine-customevents2.png b/doc/src/images/statemachine-customevents2.png
new file mode 100644
index 0000000..57b37ef
--- /dev/null
+++ b/doc/src/images/statemachine-customevents2.png
diff --git a/doc/src/images/statemachine-finished.png b/doc/src/images/statemachine-finished.png
index 802621e..0ac081d 100644
--- a/doc/src/images/statemachine-finished.png
+++ b/doc/src/images/statemachine-finished.png
diff --git a/doc/src/images/statemachine-nonparallel.png b/doc/src/images/statemachine-nonparallel.png
index 1fe60d8..f9850a7 100644
--- a/doc/src/images/statemachine-nonparallel.png
+++ b/doc/src/images/statemachine-nonparallel.png
diff --git a/doc/src/images/statemachine-parallel.png b/doc/src/images/statemachine-parallel.png
index 1868792..a65c297 100644
--- a/doc/src/images/statemachine-parallel.png
+++ b/doc/src/images/statemachine-parallel.png
diff --git a/doc/src/images/tankgame-example.png b/doc/src/images/tankgame-example.png
new file mode 100644
index 0000000..9e17e30
--- /dev/null
+++ b/doc/src/images/tankgame-example.png
diff --git a/doc/src/images/trafficlight-example1.png b/doc/src/images/trafficlight-example1.png
new file mode 100644
index 0000000..ec8c7ff
--- /dev/null
+++ b/doc/src/images/trafficlight-example1.png
diff --git a/doc/src/images/trafficlight-example2.png b/doc/src/images/trafficlight-example2.png
new file mode 100644
index 0000000..a12e4db
--- /dev/null
+++ b/doc/src/images/trafficlight-example2.png
diff --git a/doc/src/statemachine.qdoc b/doc/src/statemachine.qdoc
index 60ae815..5a89f4d 100644
--- a/doc/src/statemachine.qdoc
+++ b/doc/src/statemachine.qdoc
@@ -1,11 +1,41 @@
 /****************************************************************************
 **
-** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 ** Contact: Qt Software Information (qt-info@nokia.com)
 **
-** This file is part of the $MODULE$ of the Qt Toolkit.
+** This file is part of the documentation of the Qt Toolkit.
 **
-** $TROLLTECH_DUAL_LICENSE$
+** $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$
 **
 ****************************************************************************/
 
@@ -13,6 +43,7 @@
   \page statemachine-api.html
   \title The State Machine Framework
   \brief An overview of the State Machine framework for constructing and executing state graphs.
+  \ingroup architecture
 
   \tableofcontents
 
@@ -33,10 +64,10 @@
 
   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 existing event
-  system and 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.
+  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.
 
   \section1 A Simple State Machine
 
@@ -52,34 +83,49 @@
     \endomit
 
   The following snippet shows the code needed to create such a state machine.
+  First, we create the state machine and states:
 
   \code
     QStateMachine machine;
     QState *s1 = new QState();
     QState *s2 = new QState();
     QState *s3 = new QState();
+  \endcode
+
+  Then, we create the transitions by using the QState::addTransition()
+  function:
 
+  \code
     s1->addTransition(button, SIGNAL(clicked()), s2);
     s2->addTransition(button, SIGNAL(clicked()), s3);
     s3->addTransition(button, SIGNAL(clicked()), s1);
+  \endcode
+
+  Next, we add the states to the machine and set the machine's initial state:
 
+  \code
     machine.addState(s1);
     machine.addState(s2);
     machine.addState(s3);
     machine.setInitialState(s1);
+  \endcode
+
+  Finally, we start the state machine:
 
+  \code
     machine.start();
   \endcode
 
-  Once the state machine has been set up, you need to start it by calling
-  QStateMachine::start(). The state machine executes asynchronously, i.e. it
-  becomes part of your application's event loop.
+  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 is perfectly fine, but it doesn't \e do anything; it
-  merely transitions from one state to another. 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:
+  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:
 
   \code
     s1->assignProperty(label, "text", "In state s1");
@@ -90,20 +136,32 @@
   When any of the states is entered, the label's text will be changed
   accordingly.
 
-  The QActionState::entered() signal is emitted when the state is entered. In the
+  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:
+  state \c s3 is entered, and the button's showMinimized() slot will be called
+  when \c s3 is exited:
 
   \code
     QObject::connect(s3, SIGNAL(entered()), button, SLOT(showMaximized()));
+    QObject::connect(s3, SIGNAL(exited()), button, SLOT(showMinimized()));
   \endcode
 
-  \section1 Sharing Transitions By Grouping States
+  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. When the state machine enters a top-level final state, the
-  machine will emit the finished() signal and halt.
+  final state (QFinalState object). When the state machine enters a top-level
+  final state, the machine will emit the QStateMachine::finished() signal and
+  halt.
+
+  All you need to do to introduce a final state in the graph is create a
+  QFinalState object and use it as the target of one or more transitions.
+
+  \section1 Sharing Transitions By Grouping States
 
   Assume we wanted the user to be able to quit the application at any time by
   clicking a Quit button. In order to achieve this, we need to create a final
@@ -165,6 +223,9 @@
     s12>addTransition(quitButton, SIGNAL(clicked()), s12);
   \endcode
 
+  A transition can have any state as its target, i.e. the target state does
+  not have to be on the same level in the state hierarchy as the source state.
+
   \section1 Using History States to Save and Restore the Current State
 
   Imagine that we wanted to add an "interrupt" mechanism to the example
@@ -251,19 +312,334 @@
     QState *s12 = new QState(s1);
   \endcode
 
+  When a parallel state group is entered, all its child states will be
+  simultaneously entered. Transitions within the individual child states
+  operate normally. However, any of the child states may take a transition
+  outside the parent state. When this happens, the parent state and all of its
+  child states are exited.
+
   \section1 Detecting that a Composite State has Finished
 
-  A child state can be final; when a final child state is entered, the parent
-  state emits the QState::finished() signal.
+  A child state can be final (a QFinalState object); when a final child state
+  is entered, the parent state emits the QState::finished() signal. The
+  following diagram shows a composite state \c s1 which does some processing
+  before entering a final state:
 
     \img statemachine-finished.png
     \omit
     \caption This is a caption
     \endomit
 
-  This is useful when you want to hide the internal details of a state;
-  i.e. the only thing the outside world should be able to do is enter the
-  state, and get a notification when the state has finished (i.e. when a final
-  child state has been entered).
+  When \c s1 's final state is entered, \c s1 will automatically emit
+  finished(). We use a signal transition to cause this event to trigger a
+  state change:
+
+  \code
+  s1->addTransition(s1, SIGNAL(finished()), s2);
+  \endcode
+
+  Using final states in composite states is useful when you want to hide the
+  internal details of a composite state; i.e. the only thing the outside world
+  should be able to do is enter the state, and get a notification when the
+  state has completed its work. This is a very powerful abstraction and
+  encapsulation mechanism when building complex (deeply nested) state
+  machines. (In the above example, you could of course create a transition
+  directly from \c s1 's \c done state rather than relying on \c s1 's
+  finished() signal, but with the consequence that implementation details of
+  \c s1 are exposed and depended on).
+
+  For parallel state groups, the QState::finished() signal is emitted when \e
+  all the child states have entered final states.
+
+  \section1 Events, Transitions and Guards
+
+  A QStateMachine runs its own event loop. For signal transitions
+  (QSignalTransition objects), QStateMachine automatically posts a
+  QSignalEvent to itself when it intercepts the corresponding signal;
+  similarly, for QObject event transitions (QEventTransition objects) a
+  QWrappedEvent is posted.
+
+  You can post your own events to the state machine using
+  QStateMachine::postEvent().
+
+  When posting a custom event to the state machine, you typically also have
+  one or more custom transitions that can be triggered from events of that
+  type. To create such a transition, you subclass QAbstractTransition and
+  reimplement QAbstractTransition::eventTest(), where you check if an event
+  matches your event type (and optionally other criteria, e.g. attributes of
+  the event object).
+
+  Here we define our own custom event type, \c StringEvent, for posting
+  strings to the state machine:
+
+  \code
+    struct StringEvent : public QEvent
+    {
+        StringEvent(const QString &val)
+        : QEvent(QEvent::Type(QEvent::User+1)),
+          value(val) {}
+
+        QString value;
+    };
+  \endcode
+
+  Next, we define a transition that only triggers when the event's string
+  matches a particular string (a \e guarded transition):
+
+  \code
+    class StringTransition : public QAbstractTransition
+    {
+    public:
+        StringTransition(const QString &value)
+            : m_value(value) {}
+
+    protected:
+        virtual bool eventTest(QEvent *e) const
+        {
+            if (e->type() != QEvent::Type(QEvent::User+1)) // StringEvent
+                return false;
+            StringEvent *se = static_cast<StringEvent*>(e);
+            return (m_value == se->value);
+        }
+    
+        virtual void onTransition(QEvent *) {}
+
+    private:
+        QString m_value;
+    };
+  \endcode
+
+  In the eventTest() reimplementation, we first check if the event type is the
+  desired one; if so, we cast the event to a StringEvent and perform the
+  string comparison.
+
+  The following is a statechart that uses the custom event and transition:
+
+    \img statemachine-customevents.png
+    \omit
+    \caption This is a caption
+    \endomit
+
+  Here's what the implementation of the statechart looks like:
+
+  \code
+    QStateMachine machine;
+    QState *s1 = new QState();
+    QState *s2 = new QState();
+    QFinalState *done = new QFinalState();
+
+    StringTransition *t1 = new StringTransition("Hello");
+    t1->setTargetState(s2);
+    s1->addTransition(t1);
+    StringTransition *t2 = new StringTransition("world");
+    t2->setTargetState(done);
+    s2->addTransition(t2);
+
+    machine.addState(s1);
+    machine.addState(s2);
+    machine.addState(done);
+    machine.setInitialState(s1);
+  \endcode
+
+  Once the machine is started, we can post events to it.
+
+  \code
+  machine.postEvent(new StringEvent("Hello"));
+  machine.postEvent(new StringEvent("world"));
+  \endcode
+
+  An event that is not handled by any relevant transition will be silently
+  consumed by the state machine. It can be useful to group states and provide
+  a default handling of such events; for example, as illustrated in the
+  following statechart:
+
+    \img statemachine-customevents2.png
+    \omit
+    \caption This is a caption
+    \endomit
 
-  */
+  For deeply nested statecharts, you can add such "fallback" transitions at
+  the level of granularity that's most appropriate.
+
+  \section1 Using Restore Policy To Automatically Restore Properties
+  
+  In some state machines it can be useful to focus the attention on assigning properties in states,
+  not on restoring them when the state is no longer active. If you know that a property should
+  always be restored to its initial value when the machine enters a state that does not explicitly 
+  give the property a value, you can set the global restore policy to 
+  QStateMachine::RestoreProperties. 
+  
+  \code
+    QStateMachine machine;
+    machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties);
+  \endcode
+  
+  When this restore policy is set, the machine will automatically restore all properties. If it
+  enters a state where a given property is not set, it will first search the hierarchy of ancestors
+  to see if the property is defined there. If it is, the property will be restored to the value
+  defined by the closest ancestor. If not, it will be restored to its initial value (i.e. the 
+  value of the property before any property assignments in states were executed.)
+  
+  Take the following code:
+  \code
+    QStateMachine machine;
+    machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties);
+      
+    QState *s1 = new QState();
+    s1->assignProperty(object, "fooBar", 1.0);
+    machine.addState(s1);
+    machine.setInitialState(s1);
+      
+    QState *s2 = new QState();  
+    machine.addState(s2);
+  \endcode
+  
+  Lets say the property \c fooBar is 0.0 when the machine starts. When the machine is in state 
+  \c s1, the property will be 1.0, since the state explicitly assigns this value to it. When the
+  machine is in state \c s2, no value is explicitly defined for the property, so it will implicitly
+  be restored to 0.0.
+  
+  If we are using nested states, the parent defines a value for the property which is inherited by 
+  all descendants that do not explicitly assign a value to the property.
+  \code
+    QStateMachine machine;
+    machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties);
+      
+    QState *s1 = new QState();
+    s1->assignProperty(object, "fooBar", 1.0);
+    machine.addState(s1);
+    machine.setInitialState(s1);
+      
+    QState *s2 = new QState(s1);  
+    s2->assignProperty(object, "fooBar", 2.0);
+    s1->setInitialState(s2);
+          
+    QState *s3 = new QState(s1);
+  \endcode
+  
+  Here \c s1 has two children: \c s2 and \c s3. When \c s2 is entered, the property \c fooBar 
+  will have the value 2.0, since this is explicitly defined for the state. When the machine is in
+  state \c s3, no value is defined for the state, but \c s1 defines the property to be 1.0, so this
+  is the value that will be assigned to \c fooBar. 
+  
+  \section1 Animating Property Assignments
+  
+  The State Machine API connects with the Animation API in Qt to allow automatically animating 
+  properties as they are assigned in states. 
+  
+  Say we have the following code:
+  \code 
+    QState *s1 = new QState();
+    QState *s2 = new QState();      
+    
+    s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50));
+    s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100));
+    
+    s1->addTransition(button, SIGNAL(clicked()), s2);
+  \endcode
+  
+  Here we define two states of a user interface. In \c s1 the \c button is small, and in \c s2
+  it is bigger. If we click the button to transition from \c s1 to \c s2, the geometry of the button 
+  will be set immediately when a given state has been entered. If we want the transition to be 
+  smooth, however, all we need to do is make a QPropertyAnimation and add this to the transition
+  object.
+  
+  \code 
+    QState *s1 = new QState();
+    QState *s2 = new QState();      
+    
+    s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50));
+    s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100));
+    
+    QSignalTransition *transition = s1->addTransition(button, SIGNAL(clicked()), s2);
+    transition->addAnimation(new QPropertyAnimation(button, "geometry"));
+  \endcode
+  
+  Adding an animation for the property in question means that the property assignment will no
+  longer take immediate effect when the state has been entered. Instead, the animation will start
+  playing when the state has been entered and smoothly animate the property assignment. Since we
+  do not set the start value or end value of the animation, these will be set implicitly. The 
+  start value of the animation will be the property's current value when the animation starts, and
+  the end value will be set based on the property assignments defined for the state.
+  
+  If the global restore policy of the state machine is set to QStateMachine::RestoreProperties,
+  it is possible to also add animations for the property restorations.
+      
+  \section1 Detecting That All Properties Have Been Set In A State
+  
+  When animations are used to assign properties, a state no longer defines the exact values that a 
+  property will have when the machine is in the given state. While the animation is running, the
+  property can potentially have any value, depending on the animation. 
+  
+  In some cases, it can be useful to be able to detect when the property has actually been assigned
+  the value defined by a state. For this, we can use the state's polished() signal.
+  \code
+    QState *s1 = new QState();
+    s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50));
+    
+    QState *s2 = new QState();
+    
+    s1->addTransition(s1, SIGNAL(polished()), s2);
+  \endcode
+  
+  The machine will be in state \c s1 until the \c geometry property has been set. Then it will 
+  immediately transition into \c s2. If the transition into \c s1 has an animation for the \c
+  geometry property, then the machine will stay in \c s1 until the animation has finished. If there
+  is no animation, it will simply set the property and immediately enter state \c s2.
+  
+  Either way, when the machine is in state \c s2, the property \c geometry has been assigned the 
+  defined value.
+  
+  If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit
+  the polished() signal until these have been executed as well.
+  
+  \section1 What happens if a state is exited before the animation has finished
+  
+  If a state has property assignments, and the transition into the state has animations for the 
+  properties, the state can potentially be exited before the properties have been assigned to the 
+  values defines by the state. This is true in particular when there are transitions out from the 
+  state that do not depend on the state being polished, as described in the previous section.
+  
+  The State Machine API guarantees that a property assigned by the state machine either: 
+  \list
+  \o Has a value explicitly assigned to the property.
+  \o Is currently being animated into a value explicitly assigned to the property.
+  \endlist
+  
+  When a state is exited prior to the animation finishing, the behavior of the state machine depends
+  on the target state of the transition. If the target state explicitly assigns a value to the 
+  property, no additional action will be taken. The property will be assigned the value defined by
+  the target state. 
+  
+  If the target state does not assign any value to the property, there are two
+  options: By default, the property will be assigned the value defined by the state it is leaving
+  (the value it would have been assigned if the animation had been permitted to finish playing.) If 
+  a global restore policy is set, however, this will take precedence, and the property will be 
+  restored as usual.
+  
+  \section1 Default Animations
+    
+  As described earlier, you can add animations to transitions to make sure property assignments
+  in the target state are animated. If you want a specific animation to be used for a given property
+  regardless of which transition is taken, you can add it as a default animation to the state 
+  machine. This is in particular useful when the properties assigned (or restored) by specific 
+  states is not known when the machine is constructed. 
+  
+  \code    
+    QState *s1 = new QState();
+    QState *s2 = new QState();
+    
+    s2->assignProperty(object, "fooBar", 2.0);
+    s1->addTransition(s2);    
+    
+    QStateMachine machine;
+    machine.setInitialState(s1);
+    machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar"));    
+  \endcode    
+  
+  When the machine is in state \c s2, the machine will play the default animation for the 
+  property \c fooBar since this property is assigned by \c s2. 
+  
+  Note that animations explicitly set on transitions will take precedence over any default 
+  animation for the given property.  
+*/