--- name: "Clutter::Script" section: "3pm" platform: "linux" package: "libclutter-perl" version: "1.002-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/Clutter::Script" --- # Clutter::Script(3pm) Loads a scene from UI definition data ## NAME Clutter::Script - Loads a scene from UI definition data ## SYNOPSIS ``` my $ui =<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 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.