hi everyone;
in this second email about the new features in Clutter 0.6, I'll expose
the ClutterScript API and the UI definition file format employed by
Clutter to describe the scene graph and its elements (be them actors,
timelines or behaviours) using external files loaded at run-time.
the UI definition language chosen for Clutter was JSON, the JavaScript
object notation as defined in RFC 4627. it was chosen for its ease of
parsing and for its human-friendliness when writing and reading it[1].
a JSON declaration is quite easy to grok:
{
"object-member" : "string-value",
"foo" : 42,
"bar" : true,
"baz" : [ 3.14, false, null ],
"blah" : { "inner-object" : "data" }
}
curly braces describe objects, with named object members; square braces
describe arrays; values of object members and array elements can be
integers, boolean values (true, false), empty values (null), floating
point values, strings, arrays and objects.
the syntax employed by ClutterScript restricts the JSON notation to fit
the GObject type system; a GObject instance is declared as:
{
"type" : "GObjectType",
"id" : "clutter-script-unique-id",
...
}
where "type" must contain the name of the class (as returned by
g_type_name()) and "id" is the unique id of the instance, used to
reference the object from within the UI definition or later when
retrieving the object instance itself.
after the type and id, every other object member must either be a
GObject property, like: "width"; "color"; "x"; or "rotation-x-angle". or
it can be a special property name, like "rotation" or "knots".
Clutter also defines special object members:
* "children" : [ child, ... ]
a list of actors or object ids that must be set as children of a
container actor; this only works for actors implementing the
ClutterContainer interface.
* "behaviours" : [ behaviour, ... ]
a list of behaviour declarations or ids to be applied to an actor
* "signals" : [ signal, ... ]
a list of signal names and handlers (and optionally flags) to be
connected to an object
once an UI is defined, it can be loaded using the ClutterScript object:
ClutterScript *script = clutter_script_new ();
GError *error = NULL;
clutter_script_load_from_file (script, file_path, &error);
if (error)
g_error ("Unable to load UI: %s", error->message);
and then each object can be retrieved using its id:
GObject *stage = clutter_script_get_object (script, "main-stage");
multiple UI definitions can be merged together, and objects can be
referenced and declared before other UI definitions have been loaded
(whenever possible). UI definitions can also be unmerged, using the
unique id returned by the clutter_script_load_from_*() functions.
signals can be auto-connected using the signals declarations, like:
"signals" : [
{ "name" : "button-press-event", "handler" : "on_button_press" },
{
"name" : "key-press-event",
"handler" : "on_key_press",
"after" : true,
"swapped" : true
}
]
and the clutter_script_connect_signals() function.
behaviours and timelines can be defined as well:
{
"type" : "ClutterBehaviourPath,
"id" : "path",
"knots" : [ [ 0, 0 ], [ 0, 100 ], [ 100, 100 ], [ 100, 0 ] ],
"alpha" : {
"timeline" : { "duration" : 500, "loop" : true },
"function" : "sine-inc"
}
}
in the example above, the timeline is implicitly created and its
ownership transferred to the implicit alpha object. timelines can also
be created explicitly and referenced with their id:
[
{
"type" : "ClutterTimeline", "id" : "main-line", "duration" : 500
},
{
"type" : "ClutterBehaviourDepth",
"id" : "depth",
"depth-start" : -400,
"depth-end" : 0,
"alpha" : { "timeline" : "main-line", "function" : "ramp" }
}
{
"type" : "ClutterBehaviourOpacity",
"id" : "opacity",
"opacity-start" : 0,
"opacity-end" : 255,
"alpha" : { "timeline" : "main-line", "function" : "sine" }
}
]
as of trunk there is no way to define explicit alpha objects, but
support for them will be added.
the objects loaded from ClutterScript will exist as long as the
ClutterScript instance is valid, along with the usual lifetime
management of the object themselves. for instance, actors added to a
container have their ownership transferred from the ClutterScript to the
container itself; objects like timelines and behaviours, instead, will
have to be referenced if you want them to survive the finalization of a
ClutterScript instance holding them.
ciao,
Emmanuele.
+++
[1] also because there are no legacy applications forcing us to use XML,
and finally because writing an XML document from the JSON equivalent is
always possible, while the reverse is not.
--
Emmanuele Bassi, OpenedHand Ltd.
Unit R, Homesdale Business Centre
216-218 Homesdale Rd., Bromley - BR12QZ
http://www.o-hand.com
--
To unsubscribe send a mail to [EMAIL PROTECTED]
