From 3bdd49dc191b9c037027349a5175dfa4a7692b66 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 31 Aug 2011 12:22:07 +0100 Subject: [PATCH] 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 | 23 ++-- doc/cookbook/examples/script-signals.c | 5 +- doc/cookbook/examples/script-states.c | 44 ++++++++ doc/cookbook/examples/script-states.json | 92 ++++++++++++++++ doc/cookbook/script.xml | 127 +++++++++++++++++++++++ 5 files changed, 284 insertions(+), 7 deletions(-) create mode 100644 doc/cookbook/examples/script-states.c create mode 100644 doc/cookbook/examples/script-states.json diff --git a/doc/cookbook/examples/Makefile.am b/doc/cookbook/examples/Makefile.am index 52fec52f7..46368dbde 100644 --- a/doc/cookbook/examples/Makefile.am +++ b/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 \ @@ -11,15 +13,15 @@ noinst_PROGRAMS = \ animations-moving-animator \ animations-moving-implicit \ animations-moving-state \ - animations-path \ + animations-path \ animations-path-circle \ animations-path-easing \ animations-reuse \ animations-rotating \ animations-scaling \ animations-scaling-zoom \ - effects-basic \ - effects-built-in \ + effects-basic \ + effects-built-in \ effects-custom-deform \ text-shadow \ textures-reflection \ @@ -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 diff --git a/doc/cookbook/examples/script-signals.c b/doc/cookbook/examples/script-signals.c index 03811d10e..da177176b 100644 --- a/doc/cookbook/examples/script-signals.c +++ b/doc/cookbook/examples/script-signals.c @@ -42,7 +42,10 @@ foo_button_clicked_cb (ClutterClickAction *action, CLUTTER_Z_AXIS, NULL, NULL, NULL); - z_angle += 90.0; + 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, diff --git a/doc/cookbook/examples/script-states.c b/doc/cookbook/examples/script-states.c new file mode 100644 index 000000000..d82f09b21 --- /dev/null +++ b/doc/cookbook/examples/script-states.c @@ -0,0 +1,44 @@ +#include +#include + +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; +} diff --git a/doc/cookbook/examples/script-states.json b/doc/cookbook/examples/script-states.json new file mode 100644 index 000000000..aa69299b1 --- /dev/null +++ b/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" + } + ] + } + ] + } +] diff --git a/doc/cookbook/script.xml b/doc/cookbook/script.xml index 96a652210..f22d5b364 100644 --- a/doc/cookbook/script.xml +++ b/doc/cookbook/script.xml @@ -727,4 +727,131 @@ g_signal_connect (button, +
+ Connecting <type>ClutterState</type> states in <type>ClutterScript</type> + +
+ Problem + + You have declared an actor using JSON, and want to connect + signals to ClutterState transitions. +
+ +
+ Solution + + Connect the ClutterState states to the signals + using the states and target-state + keys of the signals definition, and call + clutter_script_connect_signals(); for instance, + the following JSON declares that the enter-event + signal should transition to the hover state + and the leave-event should transition to the + base state: + + + +{ + "id" : "rectangle", + "type" : "ClutterRectangle", + "width" : 200, + "height" : 200, + "reactive" : true, + + "signals" : [ + { "name" : "enter-event", "states" : "rectangle-states", "target-state" : "hover" }, + { "name" : "leave-event", "states" : "rectangle-states", "target-state" : "base" } + ] +} + + + + The rectangle-states state machine holds + the various states. + +
+ +
+ Discussion + + Connecting a ClutterState state transition to + a signal defined inside a ClutterScript JSON without + requiring a real function to wrap clutter_state_set_state() + allows to minimize the amount of code that has to be written, and + ties the state to the UI element being defined. + + The connection between a signal and a ClutterState + 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 ClutterState object that is used to + store the target state definition; and the target state of the + transition. + + The states key can also contain a full + definition of the ClutterState. + + The target-state key works exactly like + the argument of clutter_state_set_state(): it + will transition the ClutterState from the current state + to the desired state. + + The ClutterState 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 ClutterState + in code, and associate it to a ClutterScript instance + prior to parsing the signal connection JSON, through the + clutter_script_add_states() function of + ClutterScript. + + The warp boolean key can be used to + perform a transition to the target state without an animation, + similarly to what clutter_state_warp_to_state() + does, for instance: + + + +{ + "signals" : [ + { + "name" : "enter-event", + "states" : "rectangle-states", + "target-state" : "hover", + "warp" : true + } + ] +} + + + + will not animate the transition between the current state + and the target hover state when the signal + is emitted. + +
+ +
+ Full examples + + + <type>ClutterScript</type> JSON with state definitions + + + a code sample should be here... but isn't + + + + + + Loading a JSON file into a <type>ClutterScript</type> and connecting states + + + a code sample should be here... but isn't + + + + +
+ +
+