Clutter::Script.3pm

Langue: en

Version: 2010-08-25 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

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

SEE ALSO

Clutter, Glib::Object Copyright (C) 2006, 2007, 2008 OpenedHand Ltd

Copyright (C) 2009 Intel Corporation

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.