docs/cookbook: Add script->state connection recipe

Script definitions can connect a signal to a State transition; this is a
useful thing to document with a recipe in the cookbook.

doc/cookbook/examples/Makefile.am

@@ -2,6 +2,8 @@ include $(top_srcdir)/build/autotools/Makefile.am.silent
 
 NULL =
 
+EXTRA_DIST =
+
 noinst_PROGRAMS = \
 	actors-composite-main 			\
 	animations-complex			\
@@ -43,6 +45,7 @@ noinst_PROGRAMS = \
 	textures-crossfade-slideshow		\
 	script-ui				\
 	script-signals				\
+	script-states				\
 	events-buttons				\
 	events-buttons-click			\
 	events-buttons-lasso			\
@@ -51,10 +54,7 @@ noinst_PROGRAMS = \
 INCLUDES = \
 	-I$(top_srcdir)/ \
 	-I$(top_srcdir)/clutter \
-	-I$(top_srcdir)/clutter/cogl \
-	-I$(top_srcdir)/clutter/cogl/pango \
 	-I$(top_builddir)/clutter \
-	-I$(top_builddir)/clutter/cogl \
 	$(NULL)
 
 LDADD = $(top_builddir)/clutter/libclutter-@CLUTTER_SONAME_INFIX@-@CLUTTER_API_VERSION@.la
@@ -113,8 +113,19 @@ textures_crossfade_cogl_SOURCES            = textures-crossfade-cogl.c
 textures_crossfade_slideshow_SOURCES       = textures-crossfade-slideshow.c
 script_ui_SOURCES                          = script-ui.c
 script_signals_SOURCES                     = script-signals.c
+script_states_SOURCES			   = script-states.c
 events_buttons_SOURCES                     = events-buttons.c
 events_buttons_click_SOURCES               = events-buttons-click.c
 events_buttons_lasso_SOURCES               = events-buttons-lasso.c
 
+EXTRA_DIST += \
+	animations-complex.json			\
+	animations-complex-overlapping.json	\
+	animations-reuse-animation.json		\
+	animations-reuse-ui.json		\
+	script-signals.json			\
+	script-states.json			\
+	script-ui.json				\
+	$(NULL)
+
 -include $(top_srcdir)/build/autotools/Makefile.am.gitignore

doc/cookbook/examples/script-signals.c

@@ -42,7 +42,10 @@ foo_button_clicked_cb (ClutterClickAction *action,
                                         CLUTTER_Z_AXIS,
                                         NULL, NULL, NULL);
 
+  if (clutter_click_action_get_button (action) == 1)
     z_angle += 90.0;
+  else
+    z_angle -= 90.0;
 
   /* animate to new rotation angle */
   clutter_actor_animate (rectangle,

doc/cookbook/examples/script-states.c

@@ -0,0 +1,44 @@
+#include <stdlib.h>
+#include <clutter/clutter.h>
+
+int
+main (int argc, char *argv[])
+{
+  ClutterActor *stage;
+  ClutterScript *ui;
+
+  gchar *filename = "script-states.json";
+  GError *error = NULL;
+
+  if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
+    return 1;
+
+  ui = clutter_script_new ();
+
+  clutter_script_load_from_file (ui, filename, &error);
+
+  if (error != NULL)
+    {
+      g_critical ("Error loading ClutterScript file %s\n%s", filename, error->message);
+      g_error_free (error);
+      exit (EXIT_FAILURE);
+    }
+
+  clutter_script_get_objects (ui,
+                              "stage", &stage,
+                              NULL);
+
+  /* make the objects in the script available to all signals
+   * by passing the script as the second argument
+   * to clutter_script_connect_signals()
+   */
+  clutter_script_connect_signals (ui, ui);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  g_object_unref (ui);
+
+  return EXIT_SUCCESS;
+}

doc/cookbook/examples/script-states.json

@@ -0,0 +1,92 @@
+[
+  {
+    "id" : "stage",
+    "type" : "ClutterStage",
+    "width" : 300,
+    "height" : 300,
+    "color" : "#335",
+
+    "signals" : [
+      { "name" : "destroy", "handler" : "clutter_main_quit" }
+    ],
+
+    "children" : [ "rectangle" ]
+  },
+
+  {
+    "id" : "rectangle-states",
+    "type" : "ClutterState",
+    "duration" : 1000,
+
+    "transitions" : [
+      {
+        "source" : null,
+        "target" : "base",
+
+        "keys" : [
+          [ "rectangle", "scale-x", "ease-in-cubic", 0.7 ],
+          [ "rectangle", "scale-y", "ease-in-cubic", 0.7 ],
+          [ "rectangle", "rotation-angle-z", "ease-out-cubic", 0.0 ]
+        ]
+      },
+      {
+        "source" : null,
+        "target" : "hover",
+
+        "keys" : [
+          [ "rectangle", "scale-x", "ease-in-cubic", 1.2 ],
+          [ "rectangle", "scale-y", "ease-in-cubic", 1.2 ]
+        ]
+      },
+      {
+        "source" : null,
+        "target" : "clicked",
+
+        "keys" : [
+          [ "rectangle", "rotation-angle-z", "ease-out-bounce", 90.0 ]
+        ]
+      }
+    ]
+  },
+
+  {
+    "id" : "rectangle",
+    "type" : "ClutterRectangle",
+    "width" : 200,
+    "height" : 200,
+    "x" : 50,
+    "y" : 50,
+    "color" : "#a90",
+    "rotation-center-z-gravity" : "center",
+    "scale-gravity" : "center",
+    "scale-x" : 0.7,
+    "scale-y" : 0.7,
+    "reactive" : true,
+
+    "signals" : [
+      {
+        "name" : "enter-event",
+        "states" : "rectangle-states",
+        "target-state" : "hover"
+      },
+      {
+        "name" : "leave-event",
+        "states" : "rectangle-states",
+        "target-state" : "base"
+      }
+    ],
+
+    "actions" : [
+      {
+        "type" : "ClutterClickAction",
+        "signals" : [
+          {
+            "name" : "clicked",
+            "states" : "rectangle-states",
+            "target-state" : "clicked"
+          }
+        ]
+      }
+    ]
+  }
+]

doc/cookbook/script.xml

@@ -727,4 +727,131 @@ g_signal_connect (button,
 
   </section>
 
+  <section id="script-state">
+    <title>Connecting <type>ClutterState</type> states in <type>ClutterScript</type></title>
+
+    <section>
+      <title>Problem</title>
+
+      <para>You have declared an actor using JSON, and want to connect
+      signals to <type>ClutterState</type> transitions.</para>
+    </section>
+
+    <section>
+      <title>Solution</title>
+
+      <para>Connect the <type>ClutterState</type> states to the signals
+      using the <varname>states</varname> and <varname>target-state</varname>
+      keys of the <varname>signals</varname> definition, and call
+      <function>clutter_script_connect_signals()</function>; for instance,
+      the following JSON declares that the <emphasis>enter-event</emphasis>
+      signal should transition to the <emphasis>hover</emphasis> state
+      and the <emphasis>leave-event</emphasis> should transition to the
+      <emphasis>base</emphasis> state:</para>
+
+      <informalexample>
+        <programlisting>
+{
+  "id" : "rectangle",
+  "type" : "ClutterRectangle",
+  "width" : 200,
+  "height" : 200,
+  "reactive" : true,
+
+  <emphasis>"signals" : [
+    { "name" : "enter-event", "states" : "rectangle-states", "target-state" : "hover" },
+    { "name" : "leave-event", "states" : "rectangle-states", "target-state" : "base" }
+  ]</emphasis>
+}
+        </programlisting>
+      </informalexample>
+
+      <para>The <emphasis>rectangle-states</emphasis> state machine holds
+      the various states.</para>
+
+    </section>
+
+    <section>
+      <title>Discussion</title>
+
+      <para>Connecting a <type>ClutterState</type> state transition to
+      a signal defined inside a <type>ClutterScript</type> JSON without
+      requiring a real function to wrap <function>clutter_state_set_state()</function>
+      allows to minimize the amount of code that has to be written, and
+      ties the state to the UI element being defined.</para>
+
+      <para>The connection between a signal and a <type>ClutterState</type>
+      state is similar to the connection between a signal and a handler
+      function. Each definition must contain the name of the signal; the
+      script id of the <type>ClutterState</type> object that is used to
+      store the target state definition; and the target state of the
+      transition.</para>
+
+      <para>The <emphasis>states</emphasis> key can also contain a full
+      definition of the <type>ClutterState</type>.</para>
+
+      <para>The <emphasis>target-state</emphasis> key works exactly like
+      the argument of <function>clutter_state_set_state()</function>: it
+      will transition the <type>ClutterState</type> from the current state
+      to the desired state.</para>
+
+      <para>The <type>ClutterState</type> instance that will be used to
+      resolve the target state can be defined in JSON like any other
+      object, but it is also possible to create a <type>ClutterState</type>
+      in code, and associate it to a <type>ClutterScript</type> instance
+      prior to parsing the signal connection JSON, through the
+      <function>clutter_script_add_states()</function> function of
+      <type>ClutterScript</type>.</para>
+
+      <para>The <emphasis>warp</emphasis> boolean key can be used to
+      perform a transition to the target state without an animation,
+      similarly to what <function>clutter_state_warp_to_state()</function>
+      does, for instance:</para>
+
+      <informalexample>
+        <programlisting>
+{
+  <emphasis>"signals" : [
+    {
+      "name" : "enter-event",
+      "states" : "rectangle-states",
+      "target-state" : "hover",
+      "warp" : true
+    }
+  ]</emphasis>
+}
+        </programlisting>
+      </informalexample>
+
+      <para>will not animate the transition between the current state
+      and the target <emphasis>hover</emphasis> state when the signal
+      is emitted.</para>
+
+    </section>
+
+    <section>
+      <title>Full examples</title>
+
+      <example id="script-states-example-1">
+        <title><type>ClutterScript</type> JSON with state definitions</title>
+        <programlisting>
+<xi:include href="examples/script-states.json" parse="text">
+  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
+
+      <example id="script-states-examples-2">
+        <title>Loading a JSON file into a <type>ClutterScript</type> and connecting states</title>
+        <programlisting>
+<xi:include href="examples/script-states.c" parse="text">
+  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
+
+    </section>
+
+  </section>
+
 </chapter>