Next: , Previous: ClutterScriptable, Up: Top

32 ClutterScript

Loads a scene from UI definition data

32.1 Overview

<clutter-script> 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. <clutter-script> 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 <clutter-script> with clutter-script-get-object, and the class type to be instanciated. Every other attribute will be mapped to the class properties.

A <clutter-script> 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 <clutter-script> 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"   : "ClutterRectangle",
       "width"  : 100,
       "height" : 100,
       "color"  : "0xff0000ff"
     }

This will produce a red <clutter-rectangle>, 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-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: 

     
     {
       "id"          : "rotate-behaviour",
       "type"        : "ClutterBehaviourRotate",
       "angle-start" : 0.0,
       "angle-end"   : 360.0,
       "axis"        : "z-axis",
       "alpha"       : {
         "timeline" : { "num-frames" : 240, "fps" : 60, "loop" : true },
         "function" : "sine"
       }
     }

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

     
     {
       "id" : "my-rotating-actor",
       "type" : "ClutterTexture",
       ...
       "behaviours" : [ "rotate-behaviour" ]
     }

A <clutter-alpha> belonging to a <clutter-behaviour> can only be defined implicitely. A <clutter-timeline> belonging to a <clutter-alpha> can be either defined implicitely or explicitely. Implicitely defined <clutter-alpha>s and <clutter-timeline>s can omit the but will not be available using clutter-script-get-object (they can, however, be extracted using the <clutter-behaviour> and <clutter-alpha> 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: 

     
       ...
       "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
       "behaviours" := an array of names or objects to apply to an actor
       "signals"    := an array of signal definitions to connect to an object

<clutter-script> is available since Clutter 0.6

32.2 Usage

— Class: <clutter-script>

Derives from <gobject>.

This class defines the following slots:

filename-set
Whether the :filename property is set
filename
The path of the currently parsed file
— Function: clutter-script-new   (ret <clutter-script>)

Creates a new <clutter-script> instance. <clutter-script> 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.

ret
the newly created <clutter-script> instance. Use g-object-unref when done.

Since 0.6

— Function: clutter-script-load-from-data (self <clutter-script>) (data mchars) (length ssize_t)   (ret unsigned-int)
— Method: load-from-data

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

script
a <clutter-script>
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 <g-error>, or ‘#f’
ret
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.

Since 0.6

— Function: clutter-script-load-from-file (self <clutter-script>) (filename mchars)   (ret unsigned-int)
— Method: load-from-file

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

script
a <clutter-script>
filename
the full path to the definition file
error
return location for a <g-error>, or ‘#f’
ret
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.

Since 0.6

— Function: clutter-script-lookup-filename (self <clutter-script>) (filename mchars)   (ret mchars)
— Method: lookup-filename

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

script
a <clutter-script>
filename
the name of the file to lookup
ret
the full path of filename or ‘#f’ if no path was found.

Since 0.8

— Function: clutter-script-get-object (self <clutter-script>) (name mchars)   (ret <gobject>)
— Method: get-object

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

script
a <clutter-script>
name
the name of the object to retrieve
ret
the named object, or ‘#f’ if no object with the given name was available

Since 0.6

— Function: clutter-script-unmerge-objects (self <clutter-script>) (merge_id unsigned-int)
— Method: unmerge-objects

Unmerges the objects identified by merge-id.

script
a <clutter-script>
merge-id
merge id returned when loading a UI definition

Since 0.6

— Function: clutter-script-ensure-objects (self <clutter-script>)
— Method: ensure-objects

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

script
a <clutter-script>

Since 0.6

— Function: clutter-script-get-type-from-name (self <clutter-script>) (type_name mchars)   (ret <gtype>)
— Method: get-type-from-name

Looks up a type by name, using the virtual function that <clutter-script> has for that purpose. This function should rarely be used.

script
a <clutter-script>
type-name
name of the type to look up
ret
the type for the requested type name, or ‘G_TYPE_INVALID’ if not corresponding type was found.

Since 0.6

— Function: clutter-get-script-id (gobject <gobject>)   (ret mchars)

Retrieves the Clutter script id, if any.

gobject
a <gobject>
ret
the script id, or ‘#f’ 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