| Top | |
|
|
|
ClutterScript is an object used for loading and building parts or a complete scenegraph from external definition data in forms of string buffers or files.
The UI definition format is JSON, the JavaScript Object Notation as
described by RFC 4627. ClutterScript can load a JSON data stream,
parse it and build all the objects defined into it. The top-level node
in the JSON file can be a single object or an array of objects. Each object
must have an "id" and a "type" properties defining the name to be used
to retrieve it from ClutterScript with clutter_script_get_object(),
and the class type to be instanciated. Every other attribute will
be mapped to the class properties.
A ClutterScript holds a reference on every object it creates from
the definition data, except for the stage. Every non-actor object
will be finalized when the ClutterScript instance holding it will
be finalized, so they need to be referenced using g_object_ref() in
order for them to survive.
A simple object might be defined as:
1 2 3 4 5 6 7 |
{ "id" : "red-button", "type" : "ClutterRectangle", "width" : 100, "height" : 100, "color" : "#ff0000ff" } |
This will produce a red ClutterRectangle, 100x100 pixels wide, and with a ClutterScript id of "red-button"; it can be retrieved by calling:
1 2 3 |
ClutterActor *red_button; red_button = CLUTTER_ACTOR (clutter_script_get_object (script, "red-button")); |
and then manipulated with the Clutter API. For every object created
using ClutterScript it is possible to check the id by calling
clutter_get_script_id().
Multiple objects can be defined using an array:
[
{
"id" : "red-button",
"type" : "ClutterRectangle",
"width" : 100,
"height" : 100,
"color" : "#ff0000ff"
},
{
"id" : "white-button",
"type" : "ClutterRectangle",
"width" : 100,
"height" : 100,
"color" : "#ffffffff"
}
]
Packing can be represented using the "children" member, and passing an array of objects or ids of objects already defined (but not packed: the packing rules of Clutter still apply, and an actor cannot be packed in multiple containers without unparenting it in between).
Behaviours and timelines can also be defined inside a UI definition buffer:
1 2 3 4 5 6 7 8 9 10 11 |
{ "id" : "rotate-behaviour", "type" : "ClutterBehaviourRotate", "angle-start" : 0.0, "angle-end" : 360.0, "axis" : "z-axis", "alpha" : { "timeline" : { "duration" : 4000, "loop" : true }, "mode" : "easeInSine" } } |
And then to apply a defined behaviour to an actor defined inside the definition of an actor, the "behaviour" member can be used:
1 2 3 4 5 6 |
{ "id" : "my-rotating-actor", "type" : "ClutterTexture", ... "behaviours" : [ "rotate-behaviour" ] } |
A ClutterAlpha belonging to a ClutterBehaviour can only be defined implicitly like in the example above, or explicitly by setting the "alpha" property to point to a previously defined ClutterAlpha, e.g.:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{ "id" : "rotate-behaviour", "type" : "ClutterBehaviourRotate", "angle-start" : 0.0, "angle-end" : 360.0, "axis" : "z-axis", "alpha" : { "id" : "rotate-alpha", "type" : "ClutterAlpha", "timeline" : { "id" : "rotate-timeline", "type : "ClutterTimeline", "duration" : 4000, "loop" : true }, "function" : "custom_sine_alpha" } } |
Implicitely defined ClutterAlphas and ClutterTimelines
can omit the id, as well as the type members, but will not be available
using clutter_script_get_object() (they can, however, be extracted using the
ClutterBehaviour and ClutterAlpha API respectively).
Signal handlers can be defined inside a Clutter UI definition file and
then autoconnected to their respective signals using the
clutter_script_connect_signals() function:
1 2 3 4 5 6 7 8 9 10 |
... "signals" : [ { "name" : "button-press-event", "handler" : "on_button_press" }, { "name" : "foo-signal", "handler" : "after_foo", "after" : true }, ], ... |
Signal handler definitions must have a "name" and a "handler" members;
they can also have the "after" and "swapped" boolean members (for the
signal connection flags G_CONNECT_AFTER and G_CONNECT_SWAPPED
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
... "signals" : [ { "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" : "key-press-event", "states" : "button-states", "target-state" : "key-focus", "warp" : true } ], ... |
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. The
"warp" key can be used to warp to a specific state instead of
animating to it. State changes on signal emission will not affect
the signal emission chain.
ClutterScript supports translation using gettext: if a "translatable" key is
added to a property value, it will be passed through g_dgettext() before
being set on the created object. For example, to mark the “text”
property as being translatable:
1 2 3 4 5 |
{ "id" : "label", "type" : "ClutterText", "text" : { "translatable" : true, "string" : "Clutter Script" } } |
In order for translation to work, the C runtime locale must have been set
using setlocale() before loading the ClutterScript, and the translation
domain must have been set using textdomain(). If the strings in the script
are in a different translation domain from the rest of the program, use
clutter_script_set_translation_domain() to set the domain for the
ClutterScript only.
As well as the "translatable" key, ClutterScript supports optional "domain" and "context" keys for specifying the message domain (if it is not the default) and context for disambiguating it from other equal message strings.
Clutter reserves the following names, so classes defining properties through the usual GObject registration process should avoid using these names to avoid collisions:
"id" := the unique name of a ClutterScript object
"type" := the class literal name, also used to infer the type
function
"type_func" := the GType function name, for non-standard classes
"children" := an array of names or objects to add as children
"behaviours" := an array of names or objects to apply to an actor
"signals" := an array of signal definitions to connect to an object
"is-default" := a boolean flag used when defining the #ClutterStage;
if set to "true" the default stage will be used instead
of creating a new #ClutterStage instance
ClutterScript is available since Clutter 0.6
ClutterScript *
clutter_script_new (void);
Creates a new ClutterScript instance. ClutterScript can be used to load objects definitions for scenegraph elements, like actors, or behavioural elements, like behaviours and timelines. The definitions must be encoded using the JavaScript Object Notation (JSON) language.
Since: 0.6
guint clutter_script_load_from_data (ClutterScript *script,const gchar *data,gssize length,GError **error);
Loads the definitions from data
into script
and merges with
the currently loaded ones, if any.
script |
||
data |
a buffer containing the definitions |
|
length |
the length of the buffer, or -1 if |
|
error |
on error, zero is returned and error
is set
accordingly. On success, the merge id for the UI definitions is
returned. You can use the merge id with clutter_script_unmerge_objects().
Since: 0.6
guint clutter_script_load_from_file (ClutterScript *script,const gchar *filename,GError **error);
Loads the definitions from filename
into script
and merges with
the currently loaded ones, if any.
on error, zero is returned and error
is set
accordingly. On success, the merge id for the UI definitions is
returned. You can use the merge id with clutter_script_unmerge_objects().
Since: 0.6
guint clutter_script_load_from_resource (ClutterScript *script,const gchar *resource_path,GError **error);
Loads the definitions from a resource file into script
and merges with
the currently loaded ones, if any.
on error, zero is returned and error
is set
accordingly. On success, the merge id for the UI definitions is
returned. You can use the merge id with clutter_script_unmerge_objects().
Since: 1.10
void clutter_script_add_search_paths (ClutterScript *script,const gchar * const paths[],gsize n_paths);
Adds paths
to the list of search paths held by script
.
The search paths are used by clutter_script_lookup_filename(), which
can be used to define search paths for the textures source file name
or other custom, file-based properties.
script |
||
paths |
an array of strings containing different search paths. |
[array length=n_paths] |
n_paths |
the length of the passed array |
Since: 0.8
gchar * clutter_script_lookup_filename (ClutterScript *script,const gchar *filename);
Looks up filename
inside the search paths of script
. If filename
is found, its full path will be returned .
Since: 0.8
GObject * clutter_script_get_object (ClutterScript *script,const gchar *name);
Retrieves the object bound to name
. This function does not increment
the reference count of the returned object.
Since: 0.6
gint clutter_script_get_objects (ClutterScript *script,const gchar *first_name,...);
Retrieves a list of objects for the given names. After script
, object
names/return location pairs should be listed, with a NULL pointer
ending the list, like:
1 2 3 4 5 6 7 |
GObject *my_label, *a_button, *main_timeline; clutter_script_get_objects (script, "my-label", &my_label, "a-button", &a_button, "main-timeline", &main_timeline, NULL); |
Note: This function does not increment the reference count of the returned objects.
Since: 0.6
void clutter_script_unmerge_objects (ClutterScript *script,guint merge_id);
Unmerges the objects identified by merge_id
.
Since: 0.6
void
clutter_script_ensure_objects (ClutterScript *script);
Ensure that every object defined inside script
is correctly
constructed. You should rarely need to use this function.
Since: 0.6
GList *
clutter_script_list_objects (ClutterScript *script);
Retrieves all the objects created by script
.
Note: this function does not increment the reference count of the objects it returns.
a list
of GObjects, or NULL. The objects are owned by the
ClutterScript instance. Use g_list_free() on the returned list when
done.
[transfer container][element-type GObject.Object]
Since: 0.8
void (*ClutterScriptConnectFunc) (ClutterScript *script,GObject *object,const gchar *signal_name,const gchar *handler_name,GObject *connect_object,GConnectFlags flags,gpointer user_data);
This is the signature of a function used to connect signals. It is used
by the clutter_script_connect_signals_full() function. It is mainly
intended for interpreted language bindings, but could be useful where the
programmer wants more control over the signal connection process.
script |
||
object |
the object to connect |
|
signal_name |
the name of the signal |
|
handler_name |
the name of the signal handler |
|
connect_object |
the object to connect the signal to, or |
|
flags |
signal connection flags |
|
user_data |
user data to pass to the signal handler |
Since: 0.6
void clutter_script_connect_signals (ClutterScript *script,gpointer user_data);
Connects all the signals defined into a UI definition file to their handlers.
This method invokes clutter_script_connect_signals_full() internally
and uses GModule's introspective features (by opening the current
module's scope) to look at the application's symbol table.
Note that this function will not work if GModule is not supported by the platform Clutter is running on.
Since: 0.6
void clutter_script_connect_signals_full (ClutterScript *script,ClutterScriptConnectFunc func,gpointer user_data);
Connects all the signals defined into a UI definition file to their handlers.
This function allows to control how the signal handlers are going to be connected to their respective signals. It is meant primarily for language bindings to allow resolving the function names using the native API, but it can also be used on platforms that do not support GModule.
Applications should use clutter_script_connect_signals().
script |
||
func |
signal connection function. |
[scope call] |
user_data |
data to be passed to the signal handlers, or |
Since: 0.6
void clutter_script_add_states (ClutterScript *script,const gchar *name,ClutterState *state);
clutter_script_add_states has been deprecated since version 1.12 and should not be used in newly-written code.
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.
The ClutterScript instance will take a reference on the ClutterState passed to this function.
script |
||
name |
a name for the |
[allow-none] |
state |
Since: 1.8
ClutterState * clutter_script_get_states (ClutterScript *script,const gchar *name);
clutter_script_get_states has been deprecated since version 1.12 and should not be used in newly-written code.
Retrieves the ClutterState for the given state_name
.
If name
is NULL, this function will return the default
ClutterState instance.
a pointer to the ClutterState for the given name. The ClutterState is owned by the ClutterScript instance and it should not be unreferenced.
[transfer none]
Since: 1.8
GType clutter_script_get_type_from_name (ClutterScript *script,const gchar *type_name);
Looks up a type by name, using the virtual function that ClutterScript has for that purpose. This function should rarely be used.
the type for the requested type name, or
G_TYPE_INVALID if not corresponding type was found.
Since: 0.6
const gchar *
clutter_get_script_id (GObject *gobject);
Retrieves the Clutter script id, if any.
the script id, or NULL if object
was not defined inside
a UI definition file. The returned string is owned by the object and
should never be modified or freed.
Since: 0.6
const gchar *
clutter_script_get_translation_domain (ClutterScript *script);
Retrieves the translation domain set using
clutter_script_set_translation_domain().
Since: 1.10
void clutter_script_set_translation_domain (ClutterScript *script,const gchar *domain);
Sets the translation domain for script
.
Since: 1.10
struct ClutterScript;
The ClutterScript structure contains only private data and should be accessed using the provided API
Since: 0.6
struct ClutterScriptClass {
GType (* get_type_from_name) (ClutterScript *script,
const gchar *type_name);
};
The ClutterScriptClass structure contains only private data
virtual function used to map a type name
to a GType. This function should only be overridden by
language bindings in order to map native types to GType.
The default implementation is equivalent to |
Since: 0.6
“filename” property “filename” char *
The path of the currently parsed file. If “filename-set”
is FALSE then the value of this property is undefined.
Owner: ClutterScript
Flags: Read
Default value: NULL
Since: 0.6
“filename-set” property“filename-set” gboolean
Whether the “filename” property is set. If this property
is TRUE then the currently parsed data comes from a file, and the
file name is stored inside the “filename” property.
Owner: ClutterScript
Flags: Read
Default value: FALSE
Since: 0.6
“translation-domain” property “translation-domain” char *
The translation domain, used to localize strings marked as translatable inside a UI definition.
If “translation-domain” is set to NULL, ClutterScript
will use gettext(), otherwise g_dgettext() will be used.
Owner: ClutterScript
Flags: Read / Write
Default value: NULL
Since: 1.10