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)

•: $func (scalar)

•: $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)

•: $data (string)

Loads all the object definitions from data.

May croak with a Glib::Error in $@ on failure.

integer = $script->load_from_file ($filename)

•: $filename (string)

Loads all the object definitions from filename.

May croak with a Glib::Error in $@ on failure.

objects = $script->get_object ($name, ...)

•: $name (string) first object's name

•: ... (list) list of object names

Returns a list of all the requested objects built by script

$script->unmerge_objects ($merge_id)

•: $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:

•: the GNU Lesser General Public Library version 2.1; or

•: the Artistic License, version 2.0.

See Clutter for the full copyright notice.