
@c %start of fragment

@node ClutterScript
@chapter ClutterScript
Loads a scene from UI definition data

@section Overview
@code{<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. @code{<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 @code{<clutter-script>} with
@code{clutter-script-get-object}, and the class type to be instanciated.
Every other attribute will be mapped to the class properties.

A @code{<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 @code{<clutter-script>} instance holding it
will be finalized, so they need to be referenced using
@code{g-object-ref} in order for them to survive.

A simple object might be defined as:

@example 

@{
  "id"     : "red-button",
  "type"   : "ClutterRectangle",
  "width"  : 100,
  "height" : 100,
  "color"  : "&num;ff0000ff"
@}
@end example

This will produce a red @code{<clutter-rectangle>}, 100x100 pixels wide,
and with a ClutterScript id of "red-button"; it can be retrieved by
calling:

@example 

ClutterActor *red_button;

red_button = CLUTTER_ACTOR (clutter_script_get_object (script, "red-button"));
@end example

and then manipulated with the Clutter API. For every object created
using ClutterScript it is possible to check the id by calling
@code{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
buffer:

@example 

@{
  "id"          : "rotate-behaviour",
  "type"        : "ClutterBehaviourRotate",
  "angle-start" : 0.0,
  "angle-end"   : 360.0,
  "axis"        : "z-axis",
  "alpha"       : @{
    "timeline" : @{ "duration" : 4000, "loop" : true @},
    "mode"     : "easeInSine"
  @}
@}
@end example

And then to apply a defined behaviour to an actor defined inside the
definition of an actor, the "behaviour" member can be used:

@example 

@{
  "id" : "my-rotating-actor",
  "type" : "ClutterTexture",
  ...
  "behaviours" : [ "rotate-behaviour" ]
@}
@end example

A @code{<clutter-alpha>} belonging to a @code{<clutter-behaviour>} can
only be defined implicitly like in the example above, or explicitly by
setting the "alpha" property to point to a previously defined
@code{<clutter-alpha>}, e.g.:

@example 

@{
  "id"          : "rotate-behaviour",
  "type"        : "ClutterBehaviourRotate",
  "angle-start" : 0.0,
  "angle-end"   : 360.0,
  "axis"        : "z-axis",
  "alpha"       : @{
    "id"       : "rotate-alpha",
    "type"     : "ClutterAlpha",
    "timeline" : @{
      "id"       : "rotate-timeline",
      "type      : "ClutterTimeline",
      "duration" : 4000,
      "loop"     : true
    @},
    "function" : "custom_sine_alpha"
  @}
@}
@end example

Implicitely defined @code{<clutter-alpha>}s and
@code{<clutter-timeline>}s can omit the @c (varname "id") member, as
well as the @c (varname "type") member, but will not be available using
@code{clutter-script-get-object} (they can, however, be extracted using
the @code{<clutter-behaviour>} and @code{<clutter-alpha>} API
respectively).

Signal handlers can be defined inside a Clutter UI definition file and
then autoconnected to their respective signals using the
@code{clutter-script-connect-signals} function:

@example 

  ...
  "signals" : [
    @{ "name" : "button-press-event", "handler" : "on_button_press" @},
    @{
      "name" : "foo-signal",
      "handler" : "after_foo",
      "after" : true
    @},
  ],
  ...
@end example

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 @samp{G_CONNECT_AFTER} and
@samp{G_CONNECT_SWAPPED} respectively) and the "object" string member
for calling @code{g-signal-connect-object} instead of
@code{g-signal-connect}.

Signals can also be directly attached to a specific state defined inside
a @code{<clutter-state>} instance, for instance:

@example 

  ...
  "signals" : [
    @{
      "name" : "enter-event",
      "states" : "button-states",
      "target-state" : "hover"
    @},
    @{
      "name" : "leave-event",
      "states" : "button-states",
      "target-state" : "base"
    @},
    @{
      "name" : "button-press-event",
      "states" : "button-states",
      "target-state" : "active",
    @},
    @{
      "name" : "key-press-event",
      "states" : "button-states",
      "target-state" : "key-focus",
      "warp" : true
    @}
  ],
  ...
@end example

The "states" key defines the @code{<clutter-state>} instance to be used
to resolve the "target-state" key; it can be either a script id for a
@code{<clutter-state>} built by the same @code{<clutter-script>}
instance, or to a @code{<clutter-state>} built in code and associated to
the @code{<clutter-script>} instance through the
@code{clutter-script-add-states} function. If no "states" key is
present, then the default @code{<clutter-state>} associated to the
@code{<clutter-script>} instance will be used; the default
@code{<clutter-state>} can be set using @code{clutter-script-add-states}
using a @samp{@code{#f}} name. The "warp" key can be used to warp to a
specific state instead of animating to it. State changes on signal
emission will not affect the signal emission chain.

Clutter reserves the following names, so classes defining properties
through the usual GObject registration process should avoid using these
names to avoid collisions:

@example 

  "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 #ClutterStage;
                  if set to "true" the default stage will be used instead
                  of creating a new #ClutterStage instance
@end example

@code{<clutter-script>} is available since Clutter 0.6

@section Usage
@include defuns-clutter-script.xml.texi

@c %end of fragment
