[clutter] script: Rename "state" → "states"

[Emmanuele Bassi <ebassi src gnome org>]

commit b33973f9f8ff87d2cb5d9083149b8bfd7f4130c0
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Sat Jun 11 13:30:02 2011 +0100

    script: Rename "state" â?? "states"
    
    Make it clear that the key used when defining a state-based signal is
    linked to the states of a ClutterState.

 clutter/clutter-script-parser.c     |    6 +-
 clutter/clutter-script.c            |   70 +++++++++++++++++++++++++---------
 clutter/clutter-script.h            |    8 ++--
 tests/data/test-script-signals.json |    8 ++--
 4 files changed, 62 insertions(+), 30 deletions(-)
---
diff --git a/clutter/clutter-script-parser.c b/clutter/clutter-script-parser.c
index 4477f5a..8e8acdd 100644
--- a/clutter/clutter-script-parser.c
+++ b/clutter/clutter-script-parser.c
@@ -607,11 +607,11 @@ parse_signals (ClutterScript *script,
               continue;
             }
 
-          if (json_object_has_member (object, "state"))
-            state = json_object_get_string_member (object, "state");
+          if (json_object_has_member (object, "states"))
+            state = json_object_get_string_member (object, "states");
 
           CLUTTER_NOTE (SCRIPT,
-                        "Added signal '%s' (state:%s, target:%s)",
+                        "Added signal '%s' (states:%s, target-state:%s)",
                         name,
                         state != NULL ? state : "<default>", target);
 
diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c
index 9a91f9d..65ec23e 100644
--- a/clutter/clutter-script.c
+++ b/clutter/clutter-script.c
@@ -158,6 +158,37 @@
  * respectively) and the "object" string member for calling
  * g_signal_connect_object() instead of g_signal_connect().
  *
+ * Signals can also be directly attached to a specific state defined
+ * inside a #ClutterState instance, for instance:
+ *
+ * |[
+ *   ...
+ *   "signals" : [
+ *     {
+ *       "name" : "enter-event",
+ *       "states" : "button-states",
+ *       "target-state" : "hover"
+ *     },
+ *     {
+ *       "name" : "leave-event",
+ *       "states" : "button-states",
+ *       "target-state" : "base"
+ *     }
+ *   ],
+ *   ...
+ * ]|
+ *
+ * The "states" key defines the #ClutterState instance to be used to
+ * resolve the "target-state" key; it can be either a script id for a
+ * #ClutterState built by the same #ClutterScript instance, or to a
+ * #ClutterState built in code and associated to the #ClutterScript
+ * instance through the clutter_script_add_states() function. If no
+ * "states" key is present, then the default #ClutterState associated to
+ * the #ClutterScript instance will be used; the default #ClutterState
+ * can be set using clutter_script_add_states() using a %NULL name.
+ * State changes on signal emission will not affect the signal emission
+ * chain.
+ *
  * Clutter reserves the following names, so classes defining properties
  * through the usual GObject registration process should avoid using these
  * names to avoid collisions:
@@ -1001,12 +1032,12 @@ connect_each_object (gpointer key,
           HookData *hook_data;
 
           if (sinfo->state == NULL)
-            state_object = (GObject *) clutter_script_get_state (script, NULL);
+            state_object = (GObject *) clutter_script_get_states (script, NULL);
           else
             {
               state_object = clutter_script_get_object (script, sinfo->state);
               if (state_object == NULL)
-                state_object = (GObject *) clutter_script_get_state (script, sinfo->state);
+                state_object = (GObject *) clutter_script_get_states (script, sinfo->state);
             }
 
           if (state_object == NULL)
@@ -1269,12 +1300,13 @@ clutter_script_list_objects (ClutterScript *script)
 }
 
 /**
- * clutter_script_add_state:
+ * clutter_script_add_states:
  * @script: a #ClutterScript
- * @state_name: (allow-none): a name for the @state, or %NULL to
+ * @name: (allow-none): a name for the @state, or %NULL to
  *   set the default #ClutterState
  *
- * Adds a #ClutterState using the given name to the #ClutterScript instance.
+ * Associates a #ClutterState to the #ClutterScript instance using the given
+ * name.
  *
  * The #ClutterScript instance will use @state to resolve target states when
  * connecting signal handlers.
@@ -1285,29 +1317,29 @@ clutter_script_list_objects (ClutterScript *script)
  * Since: 1.8
  */
 void
-clutter_script_add_state (ClutterScript *script,
-                          const gchar   *state_name,
-                          ClutterState  *state)
+clutter_script_add_states (ClutterScript *script,
+                           const gchar   *name,
+                           ClutterState  *state)
 {
   g_return_if_fail (CLUTTER_IS_SCRIPT (script));
   g_return_if_fail (CLUTTER_IS_STATE (state));
 
-  if (state_name == NULL || *state_name == '\0')
-    state_name = "__clutter_script_default_state";
+  if (name == NULL || *name == '\0')
+    name = "__clutter_script_default_state";
 
   g_hash_table_replace (script->priv->states,
-                        g_strdup (state_name),
+                        g_strdup (name),
                         g_object_ref (state));
 }
 
 /**
- * clutter_script_get_state:
+ * clutter_script_get_states:
  * @script: a #ClutterScript
- * @state_name: (allow-none): the name of the #ClutterState, or %NULL
+ * @name: (allow-none): the name of the #ClutterState, or %NULL
  *
  * Retrieves the #ClutterState for the given @state_name.
  *
- * If @state_name is %NULL, this function will return the default
+ * If @name is %NULL, this function will return the default
  * #ClutterState instance.
  *
  * Return value: (transfer none): a pointer to the #ClutterState for the
@@ -1317,15 +1349,15 @@ clutter_script_add_state (ClutterScript *script,
  * Since: 1.8
  */
 ClutterState *
-clutter_script_get_state (ClutterScript *script,
-                          const gchar   *state_name)
+clutter_script_get_states (ClutterScript *script,
+                           const gchar   *name)
 {
   g_return_val_if_fail (CLUTTER_IS_SCRIPT (script), NULL);
 
-  if (state_name == NULL || *state_name == '\0')
-    state_name = "__clutter_script_default_state";
+  if (name == NULL || *name == '\0')
+    name = "__clutter_script_default_state";
 
-  return g_hash_table_lookup (script->priv->states, state_name);
+  return g_hash_table_lookup (script->priv->states, name);
 }
 
 /*
diff --git a/clutter/clutter-script.h b/clutter/clutter-script.h
index a866b2d..68eb61d 100644
--- a/clutter/clutter-script.h
+++ b/clutter/clutter-script.h
@@ -165,11 +165,11 @@ void            clutter_script_unmerge_objects          (ClutterScript
                                                          guint                      merge_id);
 void            clutter_script_ensure_objects           (ClutterScript             *script);
 
-void            clutter_script_add_state                (ClutterScript             *script,
-                                                         const gchar               *state_name,
+void            clutter_script_add_states               (ClutterScript             *script,
+                                                         const gchar               *name,
                                                          ClutterState              *state);
-ClutterState *  clutter_script_get_state                (ClutterScript             *script,
-                                                         const gchar               *state_name);
+ClutterState *  clutter_script_get_states               (ClutterScript             *script,
+                                                         const gchar               *name);
 
 void            clutter_script_connect_signals          (ClutterScript             *script,
                                                          gpointer                   user_data);
diff --git a/tests/data/test-script-signals.json b/tests/data/test-script-signals.json
index b7c14be..ed0ab0e 100644
--- a/tests/data/test-script-signals.json
+++ b/tests/data/test-script-signals.json
@@ -18,10 +18,10 @@
         "name" : "button-press-event",
         "handler" : "on_button_press"
       },
-      { "name" : "enter-event", "state" : "button-states", "target-state" : "hover" },
-      { "name" : "leave-event", "state" : "button-states", "target-state" : "base" },
-      { "name" : "button-press-event", "state" : "button-states", "target-state" : "active" },
-      { "name" : "button-release-event", "state" : "button-states", "target-state" : "base" }
+      { "name" : "enter-event", "states" : "button-states", "target-state" : "hover" },
+      { "name" : "leave-event", "states" : "button-states", "target-state" : "base" },
+      { "name" : "button-press-event", "states" : "button-states", "target-state" : "active" },
+      { "name" : "button-release-event", "states" : "button-states", "target-state" : "base" }
     ]
   },