[clutter] docs: Document the states of a GestureAction

[Emmanuele Bassi <ebassi src gnome org>]

commit 8d53bbd34f597aac29782bbe78cd664bf33cbe6d
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Sep 6 13:03:05 2012 +0100

    docs: Document the states of a GestureAction
    
    Useful notes for developers writing gesture recognizers.

 clutter/clutter-gesture-action.c |   31 +++++++++++++++++++++++++++++++
 1 files changed, 31 insertions(+), 0 deletions(-)
---
diff --git a/clutter/clutter-gesture-action.c b/clutter/clutter-gesture-action.c
index 953a946..1781bb4 100644
--- a/clutter/clutter-gesture-action.c
+++ b/clutter/clutter-gesture-action.c
@@ -48,6 +48,37 @@
  *   g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);
  * ]|
  *
+ * <refsect2 id="creating-gesture-action">
+ *   <title>Creating Gesture actions</title>
+ *   <para>A #ClutterGestureAction provides four separate states that can be
+ *   used to recognize or ignore gestures when writing a new action class:</para>
+ *   <informalexample><programlisting><![CDATA[
+  Prepare -> Cancel
+  Prepare -> Begin -> Cancel
+  Prepare -> Begin -> End
+  Prepare -> Begin -> Progress -> Cancel
+  Prepare -> Begin -> Progress -> End
+ * ]]>
+ *   <para>Each #ClutterGestureAction starts in the "prepare" state, and calls
+ *   the #ClutterGestureActionClass.gesture_prepare() virtual function; this
+ *   state can be used to reset the internal state of a #ClutterGestureAction
+ *   subclass, but it can also immediately cancel a gesture without going
+ *   through the rest of the states.</para>
+ *   <para>The "begin" state follows the "prepare" state, and calls the
+ *   #ClutterGestureActionClass.gesture_begin() virtual function. This state
+ *   signals the start of a gesture recognizing process. From the "begin" state
+ *   the gesture recognition process can successfully end, by going to the
+ *   "end" state; it can continue in the "progress" state, in case of a
+ *   continuous gesture; or it can be terminated, by moving to the "cancel"
+ *   state.</para>
+ *   <para>In case of continuous gestures, the #ClutterGestureAction will use
+ *   the "progress" state, calling the #ClutterGestureActionClass.gesture_progress()
+ *   virtual function; the "progress" state will continue until the end of the
+ *   gesture, in which case the "end" state will be reached, or until the
+ *   gesture is cancelled, in which case the "cancel" gesture will be used
+ *   instead.</para>
+ * </refsects2>
+ *
  * Since: 1.8
  */