Clutter.Script
Description: Reference for Clutter.Script

### Class

# ClutterScript

since: 13

#### Description [src]

    class Clutter.Script : GObject.Object
    {
      /* No available fields */
    }

Loads a scene from UI definition data

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

    {
      "id"     : "red-button",
      "type"   : "ClutterActor",
      "width"  : 100,
      "height" : 100,
      "background-color" : "&num;ff0000ff"
    }

This will produce a red `ClutterActor`, 100x100 pixels wide, and with a ClutterScript id of “red-button”; it can be retrieved by calling:

    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_scriptable_get_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).

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:

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

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
      "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

Available since: 13

#### Ancestors

- GObject

#### Constructors

###### clutter_script_new

Creates a new `ClutterScript` instance. `ClutterScript` can be used to load objects definitions for scenegraph elements, like actors, or behavioural elements, like timelines. The definitions must be encoded using the JavaScript Object Notation (JSON) language.

since: 13

#### Instance methods

###### clutter_script_add_search_paths

Adds `paths` to the list of search paths held by `script`.

since: 13

###### clutter_script_connect_signals

Connects all the signals defined into a UI definition file to their handlers.

since: 13

###### clutter_script_connect_signals_full

Connects all the signals defined into a UI definition file to their handlers.

since: 13

###### clutter_script_ensure_objects

Ensure that every object defined inside `script` is correctly constructed. You should rarely need to use this function.

since: 13

###### clutter_script_get_object

Retrieves the object bound to `name`. This function does not increment the reference count of the returned object.

since: 13

###### clutter_script_get_objects

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:

since: 13

###### clutter_script_get_translation_domain

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

since: 13

###### clutter_script_get_type_from_name

Looks up a type by name, using the virtual function that `ClutterScript` has for that purpose. This function should rarely be used.

since: 13

###### clutter_script_list_objects

Retrieves all the objects created by `script`.

since: 13

###### clutter_script_load_from_data

Loads the definitions from `data` into `script` and merges with the currently loaded ones, if any.

since: 13

###### clutter_script_load_from_file

Loads the definitions from `filename` into `script` and merges with the currently loaded ones, if any.

since: 13

###### clutter_script_load_from_resource

Loads the definitions from a resource file into `script` and merges with the currently loaded ones, if any.

since: 13

###### clutter_script_lookup_filename

Looks up `filename` inside the search paths of `script`. If `filename` is found, its full path will be returned .

since: 13

###### clutter_script_set_translation_domain

Sets the translation domain for `script`.

since: 13

###### clutter_script_unmerge_objects

Unmerges the objects identified by `merge_id`.

since: 13

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

###### Clutter.Script:filename

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

since: 13

###### Clutter.Script:filename-set

Whether the `ClutterScript: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 `ClutterScript:filename` property.

since: 13

###### Clutter.Script:translation-domain

The translation domain, used to localize strings marked as translatable inside a UI definition.

since: 13

#### Signals

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

since: 2.0

#### Class structure

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

    }

The `ClutterScriptClass` structure contains only private data.

###### Class members

`get_type_from_name: GType (* get_type_from_name) ( ClutterScript* script, const gchar* type_name )`
  No description available.

#### Virtual methods

###### Clutter.ScriptClass.get_type_from_name

Looks up a type by name, using the virtual function that `ClutterScript` has for that purpose. This function should rarely be used.

since: 13