ClutterScript

ClutterScript — Loads a scene from UI definition data

Synopsis




                    ClutterScript;
                    ClutterScriptClass;
ClutterScript*      clutter_script_new                  (void);
enum                ClutterScriptError;
guint               clutter_script_load_from_data       (ClutterScript *script,
                                                         const gchar *data,
                                                         gssize length,
                                                         GError **error);
guint               clutter_script_load_from_file       (ClutterScript *script,
                                                         const gchar *filename,
                                                         GError **error);

GObject*            clutter_script_get_object           (ClutterScript *script,
                                                         const gchar *name);
gint                clutter_script_get_objects          (ClutterScript *script,
                                                         const gchar *first_name,
                                                         ...);
void                clutter_script_unmerge_objects      (ClutterScript *script,
                                                         guint merge_id);
void                clutter_script_ensure_objects       (ClutterScript *script);

void                (*ClutterScriptConnectFunc)         (ClutterScript *script,
                                                         GObject *object,
                                                         const gchar *signal_name,
                                                         const gchar *handler_name,
                                                         GObject *connect_object,
                                                         GConnectFlags flags,
                                                         gpointer user_data);
void                clutter_script_connect_signals      (ClutterScript *script,
                                                         gpointer user_data);
void                clutter_script_connect_signals_full (ClutterScript *script,
                                                         ClutterScriptConnectFunc func,
                                                         gpointer user_data);

GType               clutter_script_get_type_from_name   (ClutterScript *script,
                                                         const gchar *type_name);
const gchar*        clutter_get_script_id               (GObject *gobject);


Object Hierarchy


  GObject
   +----ClutterScript

Properties


  "filename"                 gchararray            : Read
  "filename-set"             gboolean              : Read

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:

{
  "id"     : "red-button",
  "type"   : "ClutterRectangle",
  "width"  : 100,
  "height" : 100,
  "color"  : "0xff0000ff"
}

This will produce a red ClutterRectangle, 100x100 pixels wide, and with a name 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.

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 ClutterAlpha belonging to a ClutterBehaviour can only be defined implicitely. A ClutterTimeline belonging to a ClutterAlpha can be either defined implicitely or explicitely. Implicitely defined ClutterAlphas and ClutterTimelines can omit the id member, as well as the type 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:

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

ClutterScript is available since Clutter 0.6

Details

ClutterScript

typedef struct _ClutterScript ClutterScript;


ClutterScriptClass

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


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


enum ClutterScriptError

typedef enum {
  CLUTTER_SCRIPT_ERROR_INVALID_TYPE_FUNCTION,
  CLUTTER_SCRIPT_ERROR_INVALID_PROPERTY,
  CLUTTER_SCRIPT_ERROR_INVALID_VALUE
} ClutterScriptError;

ClutterScript error enumeration.

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


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.

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

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.

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

Since 0.6


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.

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

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:

  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.

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.

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.

script : a ClutterScript

Since 0.6


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.

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 is a simpler variation of clutter_script_connect_signals_full(). It uses GModule's introspective features (by opening the module NULL) to look at the application's symbol table. From here it tries to match the signal handler names given in the interface description with symbols in the application and connects the signals.

Note that this function will not work correctly if GModule is not supported on the platform.

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 is similar to clutter_script_connect_signals() but it does not require GModule to be supported. It is mainly targeted at interpreted languages for controlling the signal connection.

script : a ClutterScript
func : signal connection function
user_data : data to be passed to the signal handlers, or NULL

Since 0.6


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.

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.

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

Property Details

The "filename" property

  "filename"                 gchararray            : Read

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

Default value: NULL

Since 0.6


The "filename-set" property

  "filename-set"             gboolean              : Read

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.

Default value: FALSE

Since 0.6