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

Hierarchy

hierarchy this ClutterScript ancestor_0 GObject ancestor_0--this

Ancestors

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