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.
This commit is contained in:
Emmanuele Bassi
parent
b428c3981b
commit
3bdd49dc19
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
44
doc/cookbook/examples/script-states.c
Normal file
44
doc/cookbook/examples/script-states.c
Normal file
@ -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;
|
||||
}
|
||||
92
doc/cookbook/examples/script-states.json
Normal file
92
doc/cookbook/examples/script-states.json
Normal file
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
@ -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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user