Clutter Reference Manual: ClutterScript

## ClutterScript ClutterScript — Loads a scene from UI definition data |

## Functions

ClutterScript * | clutter_script_new ()
guint | clutter_script_load_from_data ()
guint | clutter_script_load_from_file ()
guint | clutter_script_load_from_resource ()
void | clutter_script_add_search_paths ()
gchar * | clutter_script_lookup_filename ()
GObject * | clutter_script_get_object ()
gint | clutter_script_get_objects ()
void | clutter_script_unmerge_objects ()
void | clutter_script_ensure_objects ()
GList * | clutter_script_list_objects ()
void | (*ClutterScriptConnectFunc) ()
void | clutter_script_connect_signals ()
void | clutter_script_connect_signals_full ()
void | clutter_script_add_states ()
ClutterState * | clutter_script_get_states ()
GType | clutter_script_get_type_from_name ()
const gchar * | clutter_get_script_id ()
const gchar * | clutter_script_get_translation_domain ()
void | clutter_script_set_translation_domain ()

## Properties

gchar * | filename | Read
gboolean | filename-set | Read
gchar * | translation-domain | Read / Write

## Types and Values

struct | ClutterScript
struct | ClutterScriptClass
enum | ClutterScriptError

## Object Hierarchy

        GObject
        ╰── ClutterScript

## Description

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. 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:

<informalexample><programlisting><![CDATA[ { "id" : "red-button", "type" : "ClutterRectangle", "width" : 100, "height" : 100, "color" : "#ff0000ff" } ]]></programlisting></informalexample>

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()`.

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:

<informalexample><programlisting><![CDATA[ { "id" : "rotate-behaviour", "type" : "ClutterBehaviourRotate", "angle-start" : 0.0, "angle-end" : 360.0, "axis" : "z-axis", "alpha" : { "timeline" : { "duration" : 4000, "loop" : true }, "mode" : "easeInSine" } } ]]></programlisting></informalexample>

And then to apply a defined behaviour to an actor defined inside the definition of an actor, the "behaviour" member can be used:

<informalexample><programlisting><![CDATA[ { "id" : "my-rotating-actor", "type" : "ClutterTexture", ... "behaviours" : [ "rotate-behaviour" ] } ]]></programlisting></informalexample>

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.:

<informalexample><programlisting><![CDATA[ { "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" } } ]]></programlisting></informalexample>

Implicitely defined ClutterAlpha<!-- -->s and ClutterTimeline<!-- -->s can omit the <varname>id</varname> member, as well as the <varname>type</varname> member, 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:

<informalexample><programlisting><![CDATA[ ... "signals" : [ { "name" : "button-press-event", "handler" : "on_button_press" }, { "name" : "foo-signal", "handler" : "after_foo", "after" : true }, ], ... ]]></programlisting></informalexample>

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.

Clutter reserves the following names, so classes defining properties through the usual GObject registration process should avoid using these names to avoid collisions:

<programlisting><![CDATA[ "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 ]]></programlisting>

ClutterScript is available since Clutter 0.6

## Functions

### clutter_script_new ()

    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.

#### Returns

the newly created ClutterScript instance. Use `g_object_unref()` when done.

Since 0.6

### clutter_script_load_from_data ()

    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.

#### Parameters

script | a ClutterScript |
data | a buffer containing the definitions |
length | the length of the buffer, or -1 if `data` is a NUL-terminated buffer |
error | return location for a GError, or `NULL` |

#### Returns

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

### clutter_script_load_from_file ()

    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.

#### Parameters

script | a ClutterScript |
filename | the full path to the definition file |
error | return location for a GError, or `NULL` |

#### Returns

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

### clutter_script_load_from_resource ()

    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.

#### Parameters

script | a ClutterScript |
resource_path | the resource path of the file to parse |
error | return location for a GError, or `NULL` |

#### Returns

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

### clutter_script_add_search_paths ()

    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.

#### Parameters

script | a ClutterScript |
paths | an array of strings containing different search paths. | [array length=n_paths]
n_paths | the length of the passed array |

Since 0.8

### clutter_script_lookup_filename ()

    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 .

#### Parameters

script | a ClutterScript |
filename | the name of the file to lookup |

#### Returns

the full path of `filename` or `NULL` if no path was found.

Since 0.8

### clutter_script_get_object ()

    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.

#### Parameters

script | a ClutterScript |
name | the name of the object to retrieve |

#### Returns

the named object, or `NULL` if no object with the given name was available.

[transfer none]

Since 0.6

### clutter_script_get_objects ()

    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.

#### Parameters

script | a ClutterScript |
first_name | the name of the first object to retrieve |
... | return location for a GObject, then additional names, ending with `NULL` |

#### Returns

the number of objects returned.

Since 0.6

### clutter_script_unmerge_objects ()

    void
    clutter_script_unmerge_objects (ClutterScript *script,
                                    guint merge_id);

Unmerges the objects identified by `merge_id` .

#### Parameters

script | a ClutterScript |
merge_id | merge id returned when loading a UI definition |

Since 0.6

### clutter_script_ensure_objects ()

    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.

#### Parameters

script | a ClutterScript |

Since 0.6

### clutter_script_list_objects ()

    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.

#### Parameters

script | a ClutterScript |

#### Returns

a list of GObject<!-- -->s, 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.2

### ClutterScriptConnectFunc ()

    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.

#### Parameters

script | a ClutterScript |
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 `NULL` |
flags | signal connection flags |
user_data | user data to pass to the signal handler |

Since 0.6

### clutter_script_connect_signals ()

    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.

#### Parameters

script | a ClutterScript |
user_data | data to be passed to the signal handlers, or `NULL` |

Since 0.6

### clutter_script_connect_signals_full ()

    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()`.

#### Parameters

script | a ClutterScript |
func | signal connection function. | [scope call]
user_data | data to be passed to the signal handlers, or `NULL` |

Since 0.6

### clutter_script_add_states ()

    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.

#### Parameters

script | a ClutterScript |
name | a name for the `state` , or `NULL` to set the default ClutterState. | [allow-none]
state | a ClutterState |

Since 1.8

### clutter_script_get_states ()

    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.

#### Parameters

script | a ClutterScript |
name | the name of the ClutterState, or `NULL`. | [allow-none]

#### Returns

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

### clutter_script_get_type_from_name ()

    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.

#### Parameters

script | a ClutterScript |
type_name | name of the type to look up |

#### Returns

the type for the requested type name, or `G_TYPE_INVALID` if not corresponding type was found.

Since 0.6

### clutter_get_script_id ()

    const gchar *
    clutter_get_script_id (GObject *gobject);

Retrieves the Clutter script id, if any.

#### Parameters

gobject | a GObject |

#### Returns

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

### clutter_script_get_translation_domain ()

    const gchar *
    clutter_script_get_translation_domain (ClutterScript *script);

Retrieves the translation domain set using `clutter_script_set_translation_domain()`.

#### Parameters

script | a ClutterScript |

#### Returns

the translation domain, if any is set, or `NULL`.

[transfer none]

Since 1.10

### clutter_script_set_translation_domain ()

    void
    clutter_script_set_translation_domain (ClutterScript *script,
                                           const gchar *domain);

Sets the translation domain for `script` .

#### Parameters

script | a ClutterScript |
domain | the translation domain, or `NULL`. | [allow-none]

Since 1.10

## Types and Values

### struct ClutterScript

    struct ClutterScript;

The ClutterScript structure contains only private data and should be accessed using the provided API

Since 0.6

### struct ClutterScriptClass

    struct ClutterScriptClass {
      GType (* get_type_from_name) (ClutterScript *script,
                                    const gchar   *type_name);
    };

The ClutterScriptClass structure contains only private data

#### Members

`get_type_from_name` () | 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 `g_type_from_name()` |

Since 0.6

### enum ClutterScriptError

ClutterScript error enumeration.

#### Members

CLUTTER_SCRIPT_ERROR_INVALID_TYPE_FUNCTION | Type function not found or invalid |
CLUTTER_SCRIPT_ERROR_INVALID_PROPERTY | Property not found or invalid |
CLUTTER_SCRIPT_ERROR_INVALID_VALUE | Invalid value |

Since 0.6

## Property Details

### The `“filename”` property

      “filename”                 gchar *

The path of the currently parsed file. If “filename-set” is `FALSE` then the value of this property is undefined.

Flags: Read

Default value: NULL

Since 0.6

### The `“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.

Flags: Read

Default value: FALSE

Since 0.6

### The `“translation-domain”` property

      “translation-domain”       gchar *

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.

Flags: Read / Write

Default value: NULL

Since 1.10