Clutter::Script(3pm)

NAME

Clutter::Script - Loads a scene from UI definition data

SYNOPSIS

my $ui =<<END_UI;
{
  "id"     : "red-button",
  "type"   : "ClutterRectangle",
  "width"  : 100,
  "height" : 100,
  "color"  : "#ff0000ff"
}
END_UI

my $script = Clutter::Script->new();

$script->load_from_file('scene.json');
$script->load_from_data($ui);

my $stage = $script->get_object('stage');

$stage->show();

DESCRIPTION

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 by a variable outside of the
scope in order for them to survive.

A simple object might be defined as:: {
"id" : "red-button",
"type" : "ClutterRectangle",
"width" : 100,
"height" : 100,
"color" : "#ff0000ff"; }
This will produce a red Clutter::Rectangle, 100x100 pixels wide, and with a Clutter::Script id of "red-button"; it can be retrieved by calling:: my $red_button = $script->get_object('red-button');
and then manipulated with the Clutter API. For every object created using Clutter::Script 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 string:: {
"id" : "rotate-behaviour",
"type" : "ClutterBehaviourRotate",
"angle-start" : 0.0,
"angle-end" : 360.0,
"axis" : "z-axis",
"alpha" : {
"timeline" : { "duration" : 4000, "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::Alphas and Clutter::Timelines 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 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 tespectively) and the "object" string member for calling Glib::Signal::connect_object() instead of Glib::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; "is-default" := a boolean flag used when defining the stage;
if set to "true" the default stage will be used
instead of creating a new Clutter::Stage instance

HIERARCHY

Glib::Object
+----Clutter::Script

METHODS

script = Clutter::Script->new: Creates a new Clutter::Script
$script->connect_signals ($user_data) $script->connect_signals ($user_data, $package) $script->connect_signals ($user_data, %handlers): There are four ways to let Clutter::Script do the signal connecting
work for you:; "$script->connect_signals ($user_data)"
When invoked like this, Clutter::Script will connect signals to
functions in the calling package. The callback names are specified in the UI description.; "$script->connect_signals ($user_data, $package)"
When invoked like this, Clutter::Script will connect signals to
functions in the package $package.; "$script->connect_signals ($user_data, $object)"
When invoked like this, Clutter::Script will connect signals to
method calls against the object $object.; "$script->connect_signals ($user_data, %handlers)"
When invoked like this, %handlers is used as a mapping from handler names to code references.
$script->connect_signals_full ($func, $user_data=undef): o $func (scalar); o $user_data (scalar)
$script->ensure_objects
objects = $script->list_objects(): Returns a list of all the objects built by script
integer = $script->load_from_data ($data): o $data (string); Loads all the object definitions from data.; May croak with a Glib::Error in $@ on failure.
integer = $script->load_from_file ($filename): o $filename (string); Loads all the object definitions from filename.; May croak with a Glib::Error in $@ on failure.
objects = $script->get_object ($name, ...): o $name (string) first object's name; o ... (list) list of object names; Returns a list of all the requested objects built by script
$script->unmerge_objects ($merge_id): o $merge_id (integer)

PROPERTIES

'filename' (string : readable / private): The path of the currently parsed file
'filename-set' (boolean : readable / private): Whether the :filename property is set

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the terms of either:

o the GNU Lesser General Public Library version 2.1; or

o the Artistic License, version 2.0.

docs.sk

comprehensive documentation repository

Most Viewed