This is guile-gnome-clutter.info, produced by makeinfo version 4.13
from guile-gnome-clutter.texi.

This manual is for `(gnome clutter)' (version 1.10.0, updated 9 May
2012)

   Copyright 2006,2007,2008 OpenedHand LTD

   Copyright 2009,2010,2011,2012 Intel Corporation

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts. You may obtain a copy of the GNU Free
     Documentation License from the Free Software Foundation by
     visiting their Web site or by writing to:

          The Free Software Foundation, Inc., 59 Temple Place - Suite
          330, Boston, MA 02111-1307, USA

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile-Clutter: (guile-gnome-clutter.info).  A fast graphical canvas toolkit.
END-INFO-DIR-ENTRY


File: guile-gnome-clutter.info,  Node: Top,  Next: Overview,  Up: (dir)

Guile-Clutter
*************

This manual is for `(gnome clutter)' (version 1.10.0, updated 9 May
2012)

   Copyright 2006,2007,2008 OpenedHand LTD

   Copyright 2009,2010,2011,2012 Intel Corporation

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts. You may obtain a copy of the GNU Free
     Documentation License from the Free Software Foundation by
     visiting their Web site or by writing to:

          The Free Software Foundation, Inc., 59 Temple Place - Suite
          330, Boston, MA 02111-1307, USA

* Menu:

* Overview::               About Clutter and its Guile bindings.

* ClutterAction:: Abstract class for event-related logic
* ClutterActorMeta:: Base class of actor modifiers
* ClutterActor:: Base abstract class for all visual stage actors.
* ClutterAlignConstraint:: A constraint aligning the position of an actor
* ClutterAnimatable:: Interface for animatable classes.
* ClutterAnimator:: Multi-actor tweener
* Implicit Animations:: Simple implicit animations.
* ClutterAlpha:: A class for calculating an alpha value as a function of time.
* ClutterBackend:: Backend abstraction
* ClutterBindConstraint:: A constraint binding the position or size of an actor
* ClutterBinLayout:: A simple layout manager
* ClutterBlurEffect:: A blur effect
* ClutterBrightnessContrastEffect:: Increase/decrease brightness and/or contrast of actor.
* ClutterBoxLayout:: A layout manager arranging children on a single line
* Key Bindings:: Pool for key bindings.
* ClutterCanvas:: Content for 2D painting
* ClutterChildMeta:: Wrapper for actors inside a container
* ClutterCairoTexture:: Texture with Cairo integration.
* ClutterClickAction:: Action for clickable actors
* ClutterClone:: An actor that displays a clone of a source actor.
* ClutterColorizeEffect:: A colorization effect
* Colors:: Color management and manipulation.
* ClutterConstraint:: Abstract class for constraints on position or size
* ClutterContainer:: An interface for implementing container actors
* ClutterContent:: Delegate for painting the content of an actor
* ClutterDeformEffect:: A base class for effects deforming the geometry of an actor
* ClutterDesaturateEffect:: A desaturation effect
* ClutterDeviceManager:: Maintains the list of input devices
* ClutterDragAction:: Action enabling dragging on actors
* ClutterDropAction:: An action for drop targets
* ClutterEffect:: Base class for actor effects
* Events:: User and window system events
* Features:: Query GL features at runtime
* ClutterFixedLayout:: A fixed layout manager
* ClutterFlowLayout:: A reflowing layout manager
* ClutterGestureAction:: Action for gesture gestures
* ClutterInputDevice:: An input device managed by Clutter
* ClutterImage:: Image data content
* Value intervals:: An object holding an interval of two values.
* ClutterLayoutManager:: Layout managers base class
* ClutterLayoutMeta:: Wrapper for actors inside a layout manager
* ClutterListModel:: List model implementation
* General:: Various 'global' clutter functions.
* ClutterMedia:: An interface for controlling playback of media data.
* ClutterModelIter:: Iterates through a model
* ClutterModel:: A generic model implementation
* ClutterOffscreenEffect:: Base class for effects using offscreen buffers
* ClutterPageTurnEffect:: A page turning effect
* Paint Nodes:: ClutterPaintNode implementations
* ClutterPaintNode:: Paint objects
* ClutterPathConstraint:: A constraint that follows a path
* ClutterPath:: Paths with straight lines and bezier curves.
* ClutterPropertyTransition:: Property transitions
* ClutterSettings:: Settings configuration
* ClutterScriptable:: Override the UI definition parsing
* ClutterScript:: Loads a scene from UI definition data
* ClutterShaderEffect:: Base class for shader effects
* Shaders:: Programmable pipeline abstraction
* Stage Manager:: Maintains the list of stages
* ClutterSnapConstraint:: A constraint snapping two actors together
* ClutterStage:: Top level visual element to which actors are placed.
* ClutterState:: State machine with animated transitions
* ClutterSwipeAction:: Action for swipe gestures
* ClutterTableLayout:: A layout manager arranging children in rows and columns
* ClutterText:: An actor for displaying and editing text.
* ClutterTextBuffer:: Text buffer for ClutterText
* ClutterTexture:: An actor for displaying and manipulating images.
* ClutterTimeline:: A class for time-based events
* ClutterTransition:: Transition between two values
* Unit conversion:: A logical distance unit.
* Utilities:: Misc utility functions.
* Versioning Macros:: Versioning utility macros


* Undocumented::           Undocumented functions.

* Type Index::
* Function Index::


File: guile-gnome-clutter.info,  Node: Overview,  Next: ClutterAction,  Prev: Top,  Up: Top

1 Overview
**********

`(gnome clutter)' wraps the Clutter graphical canvas toolkit for Guile.
It is a part of Guile-GNOME.

   See the documentation for `(gnome gobject)' for more information on
Guile-GNOME.


File: guile-gnome-clutter.info,  Node: ClutterAction,  Next: ClutterActorMeta,  Prev: Overview,  Up: Top

2 ClutterAction
***************

Abstract class for event-related logic

2.1 Overview
============

`<clutter-action>' is an abstract base class for event-related actions
that modify the user interaction of a `<clutter-actor>', just like
`<clutter-constraint>' is an abstract class for modifiers of an actor's
position or size.

   Implementations of `<clutter-action>' are associated to an actor and
can provide behavioral changes when dealing with user input - for
instance drag and drop capabilities, or scrolling, or panning - by using
the various event-related signals provided by `<clutter-actor>' itself.

   `<clutter-action>' is available since Clutter 1.4

2.2 Usage
=========


File: guile-gnome-clutter.info,  Node: ClutterActorMeta,  Next: ClutterActor,  Prev: ClutterAction,  Up: Top

3 ClutterActorMeta
******************

Base class of actor modifiers

3.1 Overview
============

`<clutter-actor-meta>' is an abstract class providing a common API for
modifiers of `<clutter-actor>' behaviour, appearance or layout.

   A `<clutter-actor-meta>' can only be owned by a single
`<clutter-actor>' at any time.

   Every sub-class of `<clutter-actor-meta>' should check if the
`<"enabled">' property is set to ``#t'' before applying any kind of
modification.

   `<clutter-actor-meta>' is available since Clutter 1.4

3.2 Usage
=========

 -- Function: clutter-actor-meta-set-name (self `<clutter-actor-meta>')
          (name `mchars')
 -- Method: set-name
     Sets the name of META

     The name can be used to identify the `<clutter-actor-meta>'
     instance

    META
          a `<clutter-actor-meta>'

    NAME
          the name of META


     Since 1.4


 -- Function: clutter-actor-meta-get-name (self `<clutter-actor-meta>')
          =>  (ret `mchars')
 -- Method: get-name
     Retrieves the name set using `clutter-actor-meta-set-name'

    META
          a `<clutter-actor-meta>'

    RET
          the name of the `<clutter-actor-meta>' instance, or ``#f'' if
          none was set. The returned string is owned by the
          `<clutter-actor-meta>' instance and it should not be modified
          or freed.


     Since 1.4


 -- Function: clutter-actor-meta-set-enabled
          (self `<clutter-actor-meta>') (is_enabled `bool')
 -- Method: set-enabled
     Sets whether META should be enabled or not

    META
          a `<clutter-actor-meta>'

    IS-ENABLED
          whether META is enabled


     Since 1.4


 -- Function: clutter-actor-meta-get-enabled
          (self `<clutter-actor-meta>') =>  (ret `bool')
 -- Method: get-enabled
     Retrieves whether META is enabled

    META
          a `<clutter-actor-meta>'

    RET
          ``#t'' if the `<clutter-actor-meta>' instance is enabled


     Since 1.4


 -- Function: clutter-actor-meta-get-actor
          (self `<clutter-actor-meta>') =>  (ret `<clutter-actor>')
 -- Method: get-actor
     Retrieves a pointer to the `<clutter-actor>' that owns META

    META
          a `<clutter-actor-meta>'

    RET
          a pointer to a `<clutter-actor>' or ``#f''.


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterActor,  Next: ClutterAlignConstraint,  Prev: ClutterActorMeta,  Up: Top

4 ClutterActor
**************

The basic element of the scene graph

4.1 Overview
============

The ClutterActor class is the basic element of the scene graph in
Clutter, and it encapsulates the position, size, and transformations of
a node in the graph.

4.2 Actor transformations
=========================

Each actor can be transformed using methods like
`clutter-actor-set-scale' or `clutter-actor-set-rotation'. The order in
which the transformations are applied is decided by Clutter and it is
the following:

  1.      2.              3.                              4.
     5.         6.                    7.
   translation by the origin of the `<"allocation">';

   translation by the actor's `<"depth">';

   scaling by the `<"scale-x">' and `<"scale-y">' factors;

   rotation around the `<"rotation-z-angle">' and
`<"rotation-z-center">';

   rotation around the `<"rotation-y-angle">' and
`<"rotation-y-center">';

   rotation around the `<"rotation-x-angle">' and
`<"rotation-x-center">';

   negative translation by the `<"anchor-x">' and `<"anchor-y">' point.

4.3 Modifying an actor's geometry
=================================

Each actor has a bounding box, called `<"allocation">' which is either
set by its parent or explicitly through the
`clutter-actor-set-position' and `clutter-actor-set-size' methods. Each
actor also has an implicit preferred size.

   An actor’s preferred size can be defined by any subclass by
overriding the `clutter-actor-class.get-preferred-width' and the
`clutter-actor-class.get-preferred-height' virtual functions, or it can
be explicitly set by using `clutter-actor-set-width' and
`clutter-actor-set-height'.

   An actor’s position can be set explicitly by using
`clutter-actor-set-x' and `clutter-actor-set-y'; the coordinates are
relative to the origin of the actor’s parent.

4.4 Managing actor children
===========================

Each actor can have multiple children, by calling
`clutter-actor-add-child' to add a new child actor, and
`clutter-actor-remove-child' to remove an existing child.
`<clutter-actor>' will hold a reference on each child actor, which will
be released when the child is removed from its parent, or destroyed
using `clutter-actor-destroy'.


      ClutterActor *actor = clutter_actor_new ();

      /&#x002A; set the bounding box of the actor &#x002A;/
      clutter_actor_set_position (actor, 0, 0);
      clutter_actor_set_size (actor, 480, 640);

      /&#x002A; set the background color of the actor &#x002A;/
      clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);

      /&#x002A; set the bounding box of the child, relative to the parent &#x002A;/
      ClutterActor *child = clutter_actor_new ();
      clutter_actor_set_position (child, 20, 20);
      clutter_actor_set_size (child, 80, 240);

      /&#x002A; set the background color of the child &#x002A;/
      clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);

      /&#x002A; add the child to the actor &#x002A;/
      clutter_actor_add_child (actor, child);

   Children can be inserted at a given index, or above and below another
child actor. The order of insertion determines the order of the children
when iterating over them. Iterating over children is performed by using
`clutter-actor-get-first-child', `clutter-actor-get-previous-sibling',
`clutter-actor-get-next-sibling', and `clutter-actor-get-last-child'.
It is also possible to retrieve a list of children by using
`clutter-actor-get-children', as well as retrieving a specific child at
a given index by using `clutter-actor-get-child-at-index'.

   If you need to track additions of children to a `<clutter-actor>',
use the `<"actor-added">' signal; similarly, to track removals of
children from a ClutterActor, use the `<"actor-removed">' signal.


4.5 Painting an actor
=====================

There are three ways to paint an actor:

   *   *   *
   set a delegate `<clutter-content>' as the value for the
`<"content">' property of the actor;

   subclass `<clutter-actor>' and override the
`clutter-actor-class.paint-node' virtual function;

   subclass `<clutter-actor>' and override the
`clutter-actor-class.paint' virtual function.

   A `<clutter-content>' is a delegate object that takes over the
painting operation of one, or more actors. The `<clutter-content>'
painting will be performed on top of the `<"background-color">' of the
actor, and before calling the `clutter-actor-class.paint-node' virtual
function.


     ClutterActor *actor = clutter_actor_new ();

     /&#x002A; set the bounding box &#x002A;/
     clutter_actor_set_position (actor, 50, 50);
     clutter_actor_set_size (actor, 100, 100);

     /&#x002A; set the content; the image_content variable is set elsewhere &#x002A;/
     clutter_actor_set_content (actor, image_content);

   The `clutter-actor-class.paint-node' virtual function is invoked
whenever an actor needs to be painted. The implementation of the virtual
function must only paint the contents of the actor itself, and not the
contents of its children, if the actor has any.

   The `<clutter-paint-node>' passed to the virtual function is the
local root of the render tree; any node added to it will be rendered at
the correct position, as defined by the actor's `<"allocation">'.


     static void
     my_actor_paint_node (ClutterActor     *actor,
                          ClutterPaintNode *root)
     {
       ClutterPaintNode *node;
       ClutterActorBox box;

       /&#x002A; where the content of the actor should be painted &#x002A;/
       clutter_actor_get_allocation_box (actor, &box);

       /&#x002A; the cogl_texture variable is set elsewhere &#x002A;/
       node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
                                        CLUTTER_SCALING_FILTER_TRILINEAR,
                                        CLUTTER_SCALING_FILTER_LINEAR);

       /&#x002A; paint the content of the node using the allocation &#x002A;/
       clutter_paint_node_add_rectangle (node, &box);

       /&#x002A; add the node, and transfer ownership &#x002A;/
       clutter_paint_node_add_child (root, node);
       clutter_paint_node_unref (node);
     }

   The `clutter-actor-class.paint' virtual function is invoked when the
`<"paint">' signal is emitted, and after the other signal handlers have
been invoked. Overriding the paint virtual function gives total control
to the paint sequence of the actor itself, including the children of
the actor, if any.

   It is strongly discouraged to override the
`clutter-actor-class.paint' virtual function, as well as connecting to
the `<"paint">' signal. These hooks into the paint sequence are
considered legacy, and will be removed when the Clutter API changes.

4.6 Handling events on an actor
===============================

A `<clutter-actor>' can receive and handle input device events, for
instance pointer events and key events, as long as its `<"reactive">'
property is set to ``#t''.

   Once an actor has been determined to be the source of an event,
Clutter will traverse the scene graph from the top-level actor towards
the event source, emitting the `<"captured-event">' signal on each
ancestor until it reaches the source; this phase is also called _the
capture phase_. If the event propagation was not stopped, the graph is
walked backwards, from the source actor to the top-level, and the
`<"event">' signal, along with other event signals if needed, is
emitted; this phase is also called _the bubble phase_. At any point of
the signal emission, signal handlers can stop the propagation through
the scene graph by returning `CLUTTER_EVENT_STOP'; otherwise, they can
continue the propagation by returning `CLUTTER_EVENT_PROPAGATE'.

4.7 Animation
=============

Animation is a core concept of modern user interfaces; Clutter provides
a complete and powerful animation framework that automatically tweens
the actor's state without requiring direct, frame by frame manipulation
from your application code.

   The implicit animation model of Clutter assumes that all the changes
in an actor state should be gradual and asynchronous; Clutter will
automatically transition an actor's property change between the current
state and the desired one without manual intervention.

   By default, in the 1.0 API series, the transition happens with a
duration of zero milliseconds, and the implicit animation is an opt in
feature to retain backwards compatibility. In order to enable implicit
animations, it is necessary to change the easing state of an actor by
using `clutter-actor-save-easing-state':


     /&#x002A; assume that the actor is currently positioned at (100, 100) &#x002A;/
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_position (actor, 500, 500);
     clutter_actor_restore_easing_state (actor);

   The example above will trigger an implicit animation of the actor
between its current position to a new position.

   It is possible to animate multiple properties of an actor at the same
time, and you can animate multiple actors at the same time as well, for
instance:


     /&#x002A; animate the actor's opacity and depth &#x002A;/
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_opacity (actor, 0);
     clutter_actor_set_depth (actor, -100);
     clutter_actor_restore_easing_state (actor);

     /&#x002A; animate another actor's opacity &#x002A;/
     clutter_actor_save_easing_state (another_actor);
     clutter_actor_set_opacity (another_actor, 255);
     clutter_actor_set_depth (another_actor, 100);
     clutter_actor_restore_easing_state (another_actor);

   Implicit animations use a default duration of 250 milliseconds, and a
default easing mode of `CLUTTER_EASE_OUT_CUBIC', unless you call
`clutter-actor-set-easing-mode' and `clutter-actor-set-easing-duration'
after changing the easing state of the actor.

   It is important to note that if you modify the state on an animatable
property while a transition is in flight, the transition's final value
will be updated, as well as its duration and progress mode by using the
current easing state; for instance, in the following example:


     clutter_actor_save_easing_state (actor);
     clutter_actor_set_x (actor, 200);
     clutter_actor_restore_easing_state (actor);

     clutter_actor_save_easing_state (actor);
     clutter_actor_set_x (actor, 100);
     clutter_actor_restore_easing_state (actor);

   the first call to `clutter-actor-set-x' will begin a transition of
the `<"x">' property to the value of 200; the second call to
`clutter-actor-set-x' will change the transition's final value to 100.

   It is possible to retrieve the `<clutter-transition>' used by the
animatable properties by using `clutter-actor-get-transition' and using
the property name as the transition name.

   The explicit animation model supported by Clutter requires that you
create a `<clutter-transition>' object, and set the initial and final
values. The transition will not start unless you add it to the
`<clutter-actor>'.


     ClutterTransition *transition;

     transition = clutter_property_transition_new ("opacity");
     clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
     clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2);
     clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
     clutter_transition_set_interval (transition, clutter_interval_new (G_TYPE_UINT, 255, 0));

     clutter_actor_add_transition (actor, "animate-opacity", transition);

   The example above will animate the `<"opacity">' property of an
actor between fully opaque and fully transparent, and back, over a span
of 3 seconds. The animation does not begin until it is added to the
actor.

   The explicit animation API should also be used when using custom
animatable properties for `<clutter-action>', `<clutter-constraint>',
and `<clutter-effect>' instances associated to an actor; see the
section on custom animatable properties below for an example.

   Finally, explicit animations are useful for creating animations that
run continuously, for instance:


     /&#x002A; this animation will pulse the actor's opacity continuously &#x002A;/
     ClutterTransition *transition;
     ClutterInterval *interval;

     transition = clutter_property_transition_new ("opacity");

     /&#x002A; we want to animate the opacity between 0 and 255 &#x002A;/
     internal = clutter_interval_new (G_TYPE_UINT, 0, 255);
     clutter_transition_set_interval (transition, interval);

     /&#x002A; over a one second duration, running an infinite amount of times &#x002A;/
     clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
     clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);

     /&#x002A; we want to fade in and out, so we need to auto-reverse the transition &#x002A;/
     clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);

     /&#x002A; and we want to use an easing function that eases both in and out &#x002A;/
     clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                         CLUTTER_EASE_IN_OUT_CUBIC);

     /&#x002A; add the transition to the desired actor; this will
      &#x002A; start the animation.
      &#x002A;/
     clutter_actor_add_transition (actor, "opacityAnimation", transition);

4.8 Implementing an actor
=========================

Careful consideration should be given when deciding to implement a
`<clutter-actor>' sub-class. It is generally recommended to implement a
sub-class of `<clutter-actor>' only for actors that should be used as
leaf nodes of a scene graph.

   If your actor should be painted in a custom way, you should override
the `<"paint">' signal class handler. You can either opt to chain up to
the parent class implementation or decide to fully override the default
paint implementation; Clutter will set up the transformations and clip
regions prior to emitting the `<"paint">' signal.

   By overriding the `clutter-actor-class.get-preferred-width' and
`clutter-actor-class.get-preferred-height' virtual functions it is
possible to change or provide the preferred size of an actor; similarly,
by overriding the `clutter-actor-class.allocate' virtual function it is
possible to control the layout of the children of an actor. Make sure
to always chain up to the parent implementation of the
`clutter-actor-class.allocate' virtual function.

   In general, it is strongly encouraged to use delegation and
composition instead of direct subclassing.

4.9 ClutterActor custom properties for `<clutter-script>'
=========================================================

`<clutter-actor>' defines a custom "rotation" property which allows a
short-hand description of the rotations to be applied to an actor.

   The syntax of the "rotation" property is the following:


     "rotation" : [
       { "<axis>" : [ <angle>, [ <center> ] ] }
     ]

   where the _axis_ is the name of an enumeration value of type
`<clutter-rotate-axis>' and _angle_ is a floating point value
representing the rotation angle on the given axis, in degrees.

   The _center_ array is optional, and if present it must contain the
center of rotation as described by two coordinates: Y and Z for
"x-axis"; X and Z for "y-axis"; and X and Y for "z-axis".

   `<clutter-actor>' will also parse every positional and dimensional
property defined as a string through `clutter-units-from-string'; you
should read the documentation for the `<clutter-units>' parser format
for the valid units and syntax.

4.10 Custom animatable properties
=================================

`<clutter-actor>' allows accessing properties of `<clutter-action>',
`<clutter-effect>', and `<clutter-constraint>' instances associated to
an actor instance for animation purposes.

   In order to access a specific `<clutter-action>' or a
`<clutter-constraint>' property it is necessary to set the `<"name">'
property on the given action or constraint.

   The property can be accessed using the following syntax:


     @<section>.<meta-name>.<property-name>

   The initial _@_ is mandatory.

   The _section_ fragment can be one between "actions", "constraints"
and "effects".

   The _meta-name_ fragment is the name of the action or constraint, as
specified by the `<"name">' property.

   The _property-name_ fragment is the name of the action or constraint
property to be animated.

   The example below animates a `<clutter-bind-constraint>' applied to
an actor using `clutter-actor-animate'. The _rect_ has a binding
constraint for the _origin_ actor, and in its initial state is
overlapping the actor to which is bound to.


     constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
     clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
     clutter_actor_add_constraint (rect, constraint);

     constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_Y, 0.0);
     clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y");
     clutter_actor_add_constraint (rect, constraint);

     clutter_actor_set_reactive (origin, TRUE);

     g_signal_connect (origin, "button-press-event",
                       G_CALLBACK (on_button_press),
                       rect);

   On button press, the rectangle "slides" from behind the actor to
which is bound to, using the `<"offset">' property to achieve the
effect:


     gboolean
     on_button_press (ClutterActor *origin,
                      ClutterEvent *event,
                      ClutterActor *rect)
     {
       ClutterTransition *transition;
       ClutterInterval *interval;

       /&#x002A; the offset that we want to apply; this will make the actor
        &#x002A; slide in from behind the origin and rest at the right of
        &#x002A; the origin, plus a padding value.
        &#x002A;/
       float new_offset = clutter_actor_get_width (origin) + h_padding;

       /&#x002A; the property we wish to animate; the "@constraints" section
        &#x002A; tells Clutter to check inside the constraints associated
        &#x002A; with the actor; the "bind-x" section is the name of the
        &#x002A; constraint; and the "offset" is the name of the property
        &#x002A; on the constraint.
        &#x002A;/
       const char *prop = "@constraints.bind-x.offset";

       /&#x002A; create a new transition for the given property &#x002A;/
       transition = clutter_property_transition_new (prop);

       /&#x002A; set the easing mode and duration &#x002A;/
       clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                           CLUTTER_EASE_OUT_CUBIC);
       clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);

       /&#x002A; create the interval with the initial and final values &#x002A;/
       interval = clutter_interval_new (G_TYPE_FLOAT, 0, new_offset);
       clutter_transition_set_interval (transition, interval);

       /&#x002A; add the transition to the actor; this causes the animation
        &#x002A; to start. the name "offsetAnimation" can be used to retrieve
        &#x002A; the transition later.
        &#x002A;/
       clutter_actor_add_transition (rect, "offsetAnimation", transition);

       /&#x002A; we handled the event &#x002A;/
       return CLUTTER_EVENT_STOP;
     }

4.11 Usage
==========

 -- Function: clutter-actor-new =>  (ret `<clutter-actor>')
     Creates a new `<clutter-actor>'.

     A newly created actor has a floating reference, which will be sunk
     when it is added to another actor.

    RET
          the newly created `<clutter-actor>'.


     Since 1.10


 -- Function: clutter-actor-set-flags (self `<clutter-actor>')
          (flags `<clutter-actor-flags>')
 -- Method: set-flags
     Sets FLAGS on SELF

     This function will emit notifications for the changed properties

    SELF
          a `<clutter-actor>'

    FLAGS
          the flags to set


     Since 1.0


 -- Function: clutter-actor-unset-flags (self `<clutter-actor>')
          (flags `<clutter-actor-flags>')
 -- Method: unset-flags
     Unsets FLAGS on SELF

     This function will emit notifications for the changed properties

    SELF
          a `<clutter-actor>'

    FLAGS
          the flags to unset


     Since 1.0


 -- Function: clutter-actor-get-flags (self `<clutter-actor>') => 
          (ret `<clutter-actor-flags>')
 -- Method: get-flags
     Retrieves the flags set on SELF

    SELF
          a `<clutter-actor>'

    RET
          a bitwise or of `<clutter-actor-flags>' or 0


     Since 1.0


 -- Function: clutter-actor-set-name (self `<clutter-actor>')
          (name `mchars')
 -- Method: set-name
     Sets the given name to SELF. The name can be used to identify a
     `<clutter-actor>'.

    SELF
          A `<clutter-actor>'

    NAME
          Textual tag to apply to actor



 -- Function: clutter-actor-get-name (self `<clutter-actor>') => 
          (ret `mchars')
 -- Method: get-name
     Retrieves the name of SELF.

    SELF
          A `<clutter-actor>'

    RET
          the name of the actor, or ``#f''. The returned string is owned
          by the actor and should not be modified or freed.



 -- Function: clutter-actor-show (self `<clutter-actor>')
 -- Method: show
     Flags an actor to be displayed. An actor that isn't shown will not
     be rendered on the stage.

     Actors are visible by default.

     If this function is called on an actor without a parent, the
     `<"show-on-set-parent">' will be set to ``#t'' as a side effect.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-hide (self `<clutter-actor>')
 -- Method: hide
     Flags an actor to be hidden. A hidden actor will not be rendered
     on the stage.

     Actors are visible by default.

     If this function is called on an actor without a parent, the
     `<"show-on-set-parent">' property will be set to ``#f'' as a
     side-effect.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-realize (self `<clutter-actor>')
 -- Method: realize
     Realization informs the actor that it is attached to a stage. It
     can use this to allocate resources if it wanted to delay
     allocation until it would be rendered. However it is perfectly
     acceptable for an actor to create resources before being realized
     because Clutter only ever has a single rendering context so that
     actor is free to be moved from one stage to another.

     This function does nothing if the actor is already realized.

     Because a realized actor must have realized parent actors, calling
     `clutter-actor-realize' will also realize all parents of the actor.

     This function does not realize child actors, except in the special
     case that realizing the stage, when the stage is visible, will
     suddenly map (and thus realize) the children of the stage.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-unrealize (self `<clutter-actor>')
 -- Method: unrealize
     Unrealization informs the actor that it may be being destroyed or
     moved to another stage. The actor may want to destroy any
     underlying graphics resources at this point. However it is
     perfectly acceptable for it to retain the resources until the
     actor is destroyed because Clutter only ever uses a single
     rendering context and all of the graphics resources are valid on
     any stage.

     Because mapped actors must be realized, actors may not be
     unrealized if they are mapped. This function hides the actor to be
     sure it isn't mapped, an application-visible side effect that you
     may not be expecting.

     This function should not be called by application code.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-paint (self `<clutter-actor>')
 -- Method: paint
     Renders the actor to display.

     This function should not be called directly by applications. Call
     `clutter-actor-queue-redraw' to queue paints, instead.

     This function is context-aware, and will either cause a regular
     paint or a pick paint.

     This function will emit the `<"paint">' signal or the `<"pick">'
     signal, depending on the context.

     This function does not paint the actor if the actor is set to 0,
     unless it is performing a pick paint.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-continue-paint (self `<clutter-actor>')
 -- Method: continue-paint
     Run the next stage of the paint sequence. This function should
     only be called within the implementation of the ‘run’ virtual of a
     `<clutter-effect>'. It will cause the run method of the next effect
     to be applied, or it will paint the actual actor if the current
     effect is the last effect in the chain.

    SELF
          A `<clutter-actor>'


     Since 1.8


 -- Function: clutter-actor-queue-redraw (self `<clutter-actor>')
 -- Method: queue-redraw
     Queues up a redraw of an actor and any children. The redraw occurs
     once the main loop becomes idle (after the current batch of events
     has been processed, roughly).

     Applications rarely need to call this, as redraws are handled
     automatically by modification functions.

     This function will not do anything if SELF is not visible, or if
     the actor is inside an invisible part of the scenegraph.

     Also be aware that painting is a NOP for actors with an opacity of
     0

     When you are implementing a custom actor you must queue a redraw
     whenever some private state changes that will affect painting or
     picking of your actor.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-queue-relayout (self `<clutter-actor>')
 -- Method: queue-relayout
     Indicates that the actor's size request or other layout-affecting
     properties may have changed. This function is used inside
     `<clutter-actor>' subclass implementations, not by applications
     directly.

     Queueing a new layout automatically queues a redraw as well.

    SELF
          A `<clutter-actor>'


     Since 0.8


 -- Function: clutter-actor-destroy (self `<clutter-actor>')
 -- Method: destroy
     Destroys an actor. When an actor is destroyed, it will break any
     references it holds to other objects. If the actor is inside a
     container, the actor will be removed.

     When you destroy a container, its children will be destroyed as
     well.

     Note: you cannot destroy the `<clutter-stage>' returned by
     `clutter-stage-get-default'.

    SELF
          a `<clutter-actor>'



 -- Function: clutter-actor-event (self `<clutter-actor>')
          (event `<clutter-event>') (capture `bool') =>  (ret `bool')
 -- Method: event
     This function is used to emit an event on the main stage. You
     should rarely need to use this function, except for synthetising
     events.

    ACTOR
          a `<clutter-actor>'

    EVENT
          a `<clutter-event>'

    CAPTURE
          TRUE if event in in capture phase, FALSE otherwise.

    RET
          the return value from the signal emission: ``#t'' if the actor
          handled the event, or ``#f'' if the event was not handled


     Since 0.6


 -- Function: clutter-actor-should-pick-paint (self `<clutter-actor>')
          =>  (ret `bool')
 -- Method: should-pick-paint
     Should be called inside the implementation of the `<"pick">'
     virtual function in order to check whether the actor should paint
     itself in pick mode or not.

     This function should never be called directly by applications.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor should paint its silhouette, ``#f''
          otherwise



 -- Function: clutter-actor-map (self `<clutter-actor>')
 -- Method: map
     Sets the `CLUTTER_ACTOR_MAPPED' flag on the actor and possibly maps
     and realizes its children if they are visible. Does nothing if the
     actor is not visible.

     Calling this function is strongly disencouraged: the default
     implementation of `clutter-actor-class.map' will map all the
     children of an actor when mapping its parent.

     When overriding map, it is mandatory to chain up to the parent
     implementation.

    SELF
          A `<clutter-actor>'


     Since 1.0


 -- Function: clutter-actor-unmap (self `<clutter-actor>')
 -- Method: unmap
     Unsets the `CLUTTER_ACTOR_MAPPED' flag on the actor and possibly
     unmaps its children if they were mapped.

     Calling this function is not encouraged: the default
     `<clutter-actor>' implementation of `clutter-actor-class.unmap'
     will also unmap any eventual children by default when their parent
     is unmapped.

     When overriding `clutter-actor-class.unmap', it is mandatory to
     chain up to the parent implementation.

     It is important to note that the implementation of the
     `clutter-actor-class.unmap' virtual function may be called after
     the `clutter-actor-class.destroy' or the `g-object-class.dispose'
     implementation, but it is guaranteed to be called before the
     `g-object-class.finalize' implementation.

    SELF
          A `<clutter-actor>'


     Since 1.0


 -- Function: clutter-actor-has-overlaps (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-overlaps
     Asks the actor's implementation whether it may contain overlapping
     primitives.

     For example; Clutter may use this to determine whether the painting
     should be redirected to an offscreen buffer to correctly implement
     the opacity property.

     Custom actors can override the default response by implementing the
     `<clutter-actor>'`has-overlaps' virtual function. See
     `clutter-actor-set-offscreen-redirect' for more information.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor may have overlapping primitives, and
          ``#f'' otherwise


     Since 1.8


 -- Function: clutter-actor-allocate (self `<clutter-actor>')
          (box `<clutter-actor-box>')
          (flags `<clutter-allocation-flags>')
 -- Method: allocate
     Called by the parent of an actor to assign the actor its size.
     Should never be called by applications (except when implementing a
     container or layout manager).

     Actors can know from their allocation box whether they have moved
     with respect to their parent actor. The FLAGS parameter describes
     additional information about the allocation, for instance whether
     the parent has moved with respect to the stage, for example
     because a grandparent's origin has moved.

    SELF
          A `<clutter-actor>'

    BOX
          new allocation of the actor, in parent-relative coordinates

    FLAGS
          flags that control the allocation


     Since 0.8


 -- Function: clutter-actor-allocate-align-fill
          (self `<clutter-actor>') (box `<clutter-actor-box>')
          (x_align `double') (y_align `double') (x_fill `bool')
          (y_fill `bool') (flags `<clutter-allocation-flags>')
 -- Method: allocate-align-fill
     Allocates SELF by taking into consideration the available
     allocation area; an alignment factor on either axis; and whether
     the actor should fill the allocation on either axis.

     The BOX should contain the available allocation width and height;
     if the x1 and y1 members of `<clutter-actor-box>' are not set to 0,
     the allocation will be offset by their value.

     This function takes into consideration the geometry request
     specified by the `<"request-mode">' property, and the text
     direction.

     This function is useful for fluid layout managers, like
     `<clutter-bin-layout>' or `<clutter-table-layout>'

    SELF
          a `<clutter-actor>'

    BOX
          a `<clutter-actor-box>', containing the available width and
          height

    X-ALIGN
          the horizontal alignment, between 0 and 1

    Y-ALIGN
          the vertical alignment, between 0 and 1

    X-FILL
          whether the actor should fill horizontally

    Y-FILL
          whether the actor should fill vertically

    FLAGS
          allocation flags to be passed to `clutter-actor-allocate'


     Since 1.4


 -- Function: clutter-actor-set-allocation (self `<clutter-actor>')
          (box `<clutter-actor-box>')
          (flags `<clutter-allocation-flags>')
 -- Method: set-allocation
     Stores the allocation of SELF as defined by BOX.

     This function can only be called from within the implementation of
     the `clutter-actor-class.allocate' virtual function.

     The allocation should have been adjusted to take into account
     constraints, alignment, and margin properties. If you are
     implementing a `<clutter-actor>' subclass that provides its own
     layout management policy for its children instead of using a
     `<clutter-layout-manager>' delegate, you should not call this
     function on the children of SELF; instead, you should call
     `clutter-actor-allocate', which will adjust the allocation box for
     you.

     This function should only be used by subclasses of
     `<clutter-actor>' that wish to store their allocation but cannot
     chain up to the parent's implementation; the default
     implementation of the `clutter-actor-class.allocate' virtual
     function will call this function.

     It is important to note that, while chaining up was the recommended
     behaviour for `<clutter-actor>' subclasses prior to the
     introduction of this function, it is recommended to call
     `clutter-actor-set-allocation' instead.

     If the `<clutter-actor>' is using a `<clutter-layout-manager>'
     delegate object to handle the allocation of its children, this
     function will call the `clutter-layout-manager-allocate' function
     only if the `CLUTTER_DELEGATE_LAYOUT' flag is set on FLAGS,
     otherwise it is expected that the subclass will call
     `clutter-layout-manager-allocate' by itself. For instance, the
     following code:


          static void
          my_actor_allocate (ClutterActor *actor,
                             const ClutterActorBox *allocation,
                             ClutterAllocationFlags flags)
          {
            ClutterActorBox new_alloc;
            ClutterAllocationFlags new_flags;

            adjust_allocation (allocation, &new_alloc);

            new_flags = flags | CLUTTER_DELEGATE_LAYOUT;

            /&#x002A; this will use the layout manager set on the actor &#x002A;/
            clutter_actor_set_allocation (actor, &new_alloc, new_flags);
          }

     is equivalent to this:


          static void
          my_actor_allocate (ClutterActor *actor,
                             const ClutterActorBox *allocation,
                             ClutterAllocationFlags flags)
          {
            ClutterLayoutManager *layout;
            ClutterActorBox new_alloc;

            adjust_allocation (allocation, &new_alloc);

            clutter_actor_set_allocation (actor, &new_alloc, flags);

            layout = clutter_actor_get_layout_manager (actor);
            clutter_layout_manager_allocate (layout,
                                             CLUTTER_CONTAINER (actor),
                                             &new_alloc,
                                             flags);
          }

    SELF
          a `<clutter-actor>'

    BOX
          a `<clutter-actor-box>'

    FLAGS
          allocation flags


     Since 1.10


 -- Function: clutter-actor-get-allocation-box (self `<clutter-actor>')
          (box `<clutter-actor-box>')
 -- Method: get-allocation-box
     Gets the layout box an actor has been assigned. The allocation can
     only be assumed valid inside a `paint' method; anywhere else, it
     may be out-of-date.

     An allocation does not incorporate the actor's scale or anchor
     point; those transformations do not affect layout, only rendering.

     Do not call any of the clutter_actor_get_allocation_*() family of
     functions inside the implementation of the `get-preferred-width'
     or `get-preferred-height' virtual functions.

    SELF
          A `<clutter-actor>'

    BOX
          the function fills this in with the actor's allocation.


     Since 0.8


 -- Function: clutter-actor-get-preferred-size (self `<clutter-actor>')
          =>  (min_width_p `float') (min_height_p `float')
          (natural_width_p `float') (natural_height_p `float')
 -- Method: get-preferred-size
     Computes the preferred minimum and natural size of an actor,
     taking into account the actor's geometry management (either
     height-for-width or width-for-height).

     The width and height used to compute the preferred height and
     preferred width are the actor's natural ones.

     If you need to control the height for the preferred width, or the
     width for the preferred height, you should use
     `clutter-actor-get-preferred-width' and
     `clutter-actor-get-preferred-height', and check the actor's
     preferred geometry management using the `<"request-mode">'
     property.

    SELF
          a `<clutter-actor>'

    MIN-WIDTH-P
          return location for the minimum width, or ``#f''.

    MIN-HEIGHT-P
          return location for the minimum height, or ``#f''.

    NATURAL-WIDTH-P
          return location for the natural width, or ``#f''.

    NATURAL-HEIGHT-P
          return location for the natural height, or ``#f''.


     Since 0.8


 -- Function: clutter-actor-get-preferred-width
          (self `<clutter-actor>') (for_height `float') => 
          (min_width_p `float') (natural_width_p `float')
 -- Method: get-preferred-width
     Computes the requested minimum and natural widths for an actor,
     optionally depending on the specified height, or if they are
     already computed, returns the cached values.

     An actor may not get its request - depending on the layout manager
     that's in effect.

     A request should not incorporate the actor's scale or anchor point;
     those transformations do not affect layout, only rendering.

    SELF
          A `<clutter-actor>'

    FOR-HEIGHT
          available height when computing the preferred width, or a
          negative value to indicate that no height is defined

    MIN-WIDTH-P
          return location for minimum width, or ``#f''.

    NATURAL-WIDTH-P
          return location for the natural width, or ``#f''.


     Since 0.8


 -- Function: clutter-actor-get-preferred-height
          (self `<clutter-actor>') (for_width `float') => 
          (min_height_p `float') (natural_height_p `float')
 -- Method: get-preferred-height
     Computes the requested minimum and natural heights for an actor,
     or if they are already computed, returns the cached values.

     An actor may not get its request - depending on the layout manager
     that's in effect.

     A request should not incorporate the actor's scale or anchor point;
     those transformations do not affect layout, only rendering.

    SELF
          A `<clutter-actor>'

    FOR-WIDTH
          available width to assume in computing desired height, or a
          negative value to indicate that no width is defined

    MIN-HEIGHT-P
          return location for minimum height, or ``#f''.

    NATURAL-HEIGHT-P
          return location for natural height, or ``#f''.


     Since 0.8


 -- Function: clutter-actor-set-request-mode (self `<clutter-actor>')
          (mode `<clutter-request-mode>')
 -- Method: set-request-mode
     Sets the geometry request mode of SELF.

     The MODE determines the order for invoking
     `clutter-actor-get-preferred-width' and
     `clutter-actor-get-preferred-height'

    SELF
          a `<clutter-actor>'

    MODE
          the request mode


     Since 1.2


 -- Function: clutter-actor-get-request-mode (self `<clutter-actor>')
          =>  (ret `<clutter-request-mode>')
 -- Method: get-request-mode
     Retrieves the geometry request mode of SELF

    SELF
          a `<clutter-actor>'

    RET
          the request mode for the actor


     Since 1.2


 -- Function: clutter-actor-has-allocation (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-allocation
     Checks if the actor has an up-to-date allocation assigned to it.
     This means that the actor should have an allocation: it's visible
     and has a parent. It also means that there is no outstanding
     relayout request in progress for the actor or its children (There
     might be other outstanding layout requests in progress that will
     cause the actor to get a new allocation when the stage is laid
     out, however).

     If this function returns ``#f'', then the actor will normally be
     allocated before it is next drawn on the screen.

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor has an up-to-date allocation


     Since 1.4


 -- Function: clutter-actor-set-x-align (self `<clutter-actor>')
          (x_align `<clutter-actor-align>')
 -- Method: set-x-align
     Sets the horizontal alignment policy of a `<clutter-actor>', in
     case the actor received extra horizontal space.

     See also the `<"x-align">' property.

    SELF
          a `<clutter-actor>'

    X-ALIGN
          the horizontal alignment policy


     Since 1.10


 -- Function: clutter-actor-get-x-align (self `<clutter-actor>') => 
          (ret `<clutter-actor-align>')
 -- Method: get-x-align
     Retrieves the horizontal alignment policy set using
     `clutter-actor-set-x-align'.

    SELF
          a `<clutter-actor>'

    RET
          the horizontal alignment policy.


     Since 1.10


 -- Function: clutter-actor-set-y-align (self `<clutter-actor>')
          (y_align `<clutter-actor-align>')
 -- Method: set-y-align
     Sets the vertical alignment policy of a `<clutter-actor>', in case
     the actor received extra vertical space.

     See also the `<"y-align">' property.

    SELF
          a `<clutter-actor>'

    Y-ALIGN
          the vertical alignment policy


     Since 1.10


 -- Function: clutter-actor-get-y-align (self `<clutter-actor>') => 
          (ret `<clutter-actor-align>')
 -- Method: get-y-align
     Retrieves the vertical alignment policy set using
     `clutter-actor-set-y-align'.

    SELF
          a `<clutter-actor>'

    RET
          the vertical alignment policy.


     Since 1.10


 -- Function: clutter-margin-new =>  (ret `<clutter-margin>')
     Creates a new `<clutter-margin>'.

    RET
          a newly allocated `<clutter-margin>'. Use
          `clutter-margin-free' to free the resources associated with
          it when done.


     Since 1.10


 -- Function: clutter-actor-set-margin (self `<clutter-actor>')
          (margin `<clutter-margin>')
 -- Method: set-margin
     Sets all the components of the margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          a `<clutter-margin>'


     Since 1.10


 -- Function: clutter-actor-get-margin (self `<clutter-actor>')
          (margin `<clutter-margin>')
 -- Method: get-margin
     Retrieves all the components of the margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          return location for a `<clutter-margin>'.


     Since 1.10


 -- Function: clutter-actor-set-margin-top (self `<clutter-actor>')
          (margin `float')
 -- Method: set-margin-top
     Sets the margin from the top of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          the top margin


     Since 1.10


 -- Function: clutter-actor-get-margin-top (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-margin-top
     Retrieves the top margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    RET
          the top margin


     Since 1.10


 -- Function: clutter-actor-set-margin-right (self `<clutter-actor>')
          (margin `float')
 -- Method: set-margin-right
     Sets the margin from the right of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          the right margin


     Since 1.10


 -- Function: clutter-actor-get-margin-right (self `<clutter-actor>')
          =>  (ret `float')
 -- Method: get-margin-right
     Retrieves the right margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    RET
          the right margin


     Since 1.10


 -- Function: clutter-actor-set-margin-bottom (self `<clutter-actor>')
          (margin `float')
 -- Method: set-margin-bottom
     Sets the margin from the bottom of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          the bottom margin


     Since 1.10


 -- Function: clutter-actor-get-margin-bottom (self `<clutter-actor>')
          =>  (ret `float')
 -- Method: get-margin-bottom
     Retrieves the bottom margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    RET
          the bottom margin


     Since 1.10


 -- Function: clutter-actor-set-margin-left (self `<clutter-actor>')
          (margin `float')
 -- Method: set-margin-left
     Sets the margin from the left of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    MARGIN
          the left margin


     Since 1.10


 -- Function: clutter-actor-get-margin-left (self `<clutter-actor>')
          =>  (ret `float')
 -- Method: get-margin-left
     Retrieves the left margin of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    RET
          the left margin


     Since 1.10


 -- Function: clutter-actor-set-layout-manager (self `<clutter-actor>')
          (manager `<clutter-layout-manager>')
 -- Method: set-layout-manager
     Sets the `<clutter-layout-manager>' delegate object that will be
     used to lay out the children of SELF.

     The `<clutter-actor>' will take a reference on the passed MANAGER
     which will be released either when the layout manager is removed,
     or when the actor is destroyed.

    SELF
          a `<clutter-actor>'

    MANAGER
          a `<clutter-layout-manager>', or ``#f'' to unset it.


     Since 1.10


 -- Function: clutter-actor-get-layout-manager (self `<clutter-actor>')
          =>  (ret `<clutter-layout-manager>')
 -- Method: get-layout-manager
     Retrieves the `<clutter-layout-manager>' used by SELF.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to the `<clutter-layout-manager>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-set-background-color
          (self `<clutter-actor>') (color `<clutter-color>')
 -- Method: set-background-color
     Sets the background color of a `<clutter-actor>'.

     The background color will be used to cover the whole allocation of
     the actor. The default background color of an actor is transparent.

     To check whether an actor has a background color, you can use the
     `<"background-color-set">' actor property.

     The `<"background-color">' property is animatable.

    SELF
          a `<clutter-actor>'

    COLOR
          a `<clutter-color>', or ``#f'' to unset a previously set
          color.


     Since 1.10


 -- Function: clutter-actor-get-background-color
          (self `<clutter-actor>') (color `<clutter-color>')
 -- Method: get-background-color
     Retrieves the color set using `clutter-actor-set-background-color'.

    SELF
          a `<clutter-actor>'

    COLOR
          return location for a `<clutter-color>'.


     Since 1.10


 -- Function: clutter-actor-set-size (self `<clutter-actor>')
          (width `float') (height `float')
 -- Method: set-size
     Sets the actor's size request in pixels. This overrides any
     "normal" size request the actor would have. For example a text
     actor might normally request the size of the text; this function
     would force a specific size instead.

     If WIDTH and/or HEIGHT are -1 the actor will use its "normal" size
     request instead of overriding it, i.e. you can "unset" the size
     with -1.

     This function sets or unsets both the minimum and natural size.

    SELF
          A `<clutter-actor>'

    WIDTH
          New width of actor in pixels, or -1

    HEIGHT
          New height of actor in pixels, or -1



 -- Function: clutter-actor-get-size (self `<clutter-actor>') => 
          (width `float') (height `float')
 -- Method: get-size
     This function tries to "do what you mean" and return the size an
     actor will have. If the actor has a valid allocation, the
     allocation will be returned; otherwise, the actors natural size
     request will be returned.

     If you care whether you get the request vs. the allocation, you
     should probably call a different function like
     `clutter-actor-get-allocation-box' or
     `clutter-actor-get-preferred-width'.

    SELF
          A `<clutter-actor>'

    WIDTH
          return location for the width, or ``#f''.

    HEIGHT
          return location for the height, or ``#f''.


     Since 0.2


 -- Function: clutter-actor-set-position (self `<clutter-actor>')
          (x `float') (y `float')
 -- Method: set-position
     Sets the actor's fixed position in pixels relative to any parent
     actor.

     If a layout manager is in use, this position will override the
     layout manager and force a fixed position.

    SELF
          A `<clutter-actor>'

    X
          New left position of actor in pixels.

    Y
          New top position of actor in pixels.



 -- Function: clutter-actor-get-position (self `<clutter-actor>') => 
          (x `float') (y `float')
 -- Method: get-position
     This function tries to "do what you mean" and tell you where the
     actor is, prior to any transformations. Retrieves the fixed
     position of an actor in pixels, if one has been set; otherwise, if
     the allocation is valid, returns the actor's allocated position;
     otherwise, returns 0,0.

     The returned position is in pixels.

    SELF
          a `<clutter-actor>'

    X
          return location for the X coordinate, or ``#f''.

    Y
          return location for the Y coordinate, or ``#f''.


     Since 0.6


 -- Function: clutter-actor-set-width (self `<clutter-actor>')
          (width `float')
 -- Method: set-width
     Forces a width on an actor, causing the actor's preferred width and
     height (if any) to be ignored.

     If WIDTH is -1 the actor will use its preferred width request
     instead of overriding it, i.e. you can "unset" the width with -1.

     This function sets both the minimum and natural size of the actor.

    SELF
          A `<clutter-actor>'

    WIDTH
          Requested new width for the actor, in pixels, or -1


     Since 0.2


 -- Function: clutter-actor-get-width (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-width
     Retrieves the width of a `<clutter-actor>'.

     If the actor has a valid allocation, this function will return the
     width of the allocated area given to the actor.

     If the actor does not have a valid allocation, this function will
     return the actor's natural width, that is the preferred width of
     the actor.

     If you care whether you get the preferred width or the width that
     has been assigned to the actor, you should probably call a
     different function like `clutter-actor-get-allocation-box' to
     retrieve the allocated size or `clutter-actor-get-preferred-width'
     to retrieve the preferred width.

     If an actor has a fixed width, for instance a width that has been
     assigned using `clutter-actor-set-width', the width returned will
     be the same value.

    SELF
          A `<clutter-actor>'

    RET
          the width of the actor, in pixels



 -- Function: clutter-actor-set-height (self `<clutter-actor>')
          (height `float')
 -- Method: set-height
     Forces a height on an actor, causing the actor's preferred width
     and height (if any) to be ignored.

     If HEIGHT is -1 the actor will use its preferred height instead of
     overriding it, i.e. you can "unset" the height with -1.

     This function sets both the minimum and natural size of the actor.

    SELF
          A `<clutter-actor>'

    HEIGHT
          Requested new height for the actor, in pixels, or -1


     Since 0.2


 -- Function: clutter-actor-get-height (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-height
     Retrieves the height of a `<clutter-actor>'.

     If the actor has a valid allocation, this function will return the
     height of the allocated area given to the actor.

     If the actor does not have a valid allocation, this function will
     return the actor's natural height, that is the preferred height of
     the actor.

     If you care whether you get the preferred height or the height
     that has been assigned to the actor, you should probably call a
     different function like `clutter-actor-get-allocation-box' to
     retrieve the allocated size or
     `clutter-actor-get-preferred-height' to retrieve the preferred
     height.

     If an actor has a fixed height, for instance a height that has been
     assigned using `clutter-actor-set-height', the height returned will
     be the same value.

    SELF
          A `<clutter-actor>'

    RET
          the height of the actor, in pixels



 -- Function: clutter-actor-set-x (self `<clutter-actor>') (x `float')
 -- Method: set-x
     Sets the actor's X coordinate, relative to its parent, in pixels.

     Overrides any layout manager and forces a fixed position for the
     actor.

     The `<"x">' property is animatable.

    SELF
          a `<clutter-actor>'

    X
          the actor's position on the X axis


     Since 0.6


 -- Function: clutter-actor-get-x (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-x
     Retrieves the X coordinate of a `<clutter-actor>'.

     This function tries to "do what you mean", by returning the correct
     value depending on the actor's state.

     If the actor has a valid allocation, this function will return the
     X coordinate of the origin of the allocation box.

     If the actor has any fixed coordinate set using
     `clutter-actor-set-x', `clutter-actor-set-position' or
     `clutter-actor-set-geometry', this function will return that
     coordinate.

     If both the allocation and a fixed position are missing, this
     function will return 0.

    SELF
          A `<clutter-actor>'

    RET
          the X coordinate, in pixels, ignoring any transformation
          (i.e. scaling, rotation)



 -- Function: clutter-actor-set-y (self `<clutter-actor>') (y `float')
 -- Method: set-y
     Sets the actor's Y coordinate, relative to its parent, in pixels.#

     Overrides any layout manager and forces a fixed position for the
     actor.

     The `<"y">' property is animatable.

    SELF
          a `<clutter-actor>'

    Y
          the actor's position on the Y axis


     Since 0.6


 -- Function: clutter-actor-get-y (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-y
     Retrieves the Y coordinate of a `<clutter-actor>'.

     This function tries to "do what you mean", by returning the correct
     value depending on the actor's state.

     If the actor has a valid allocation, this function will return the
     Y coordinate of the origin of the allocation box.

     If the actor has any fixed coordinate set using
     `clutter-actor-set-y', `clutter-actor-set-position' or
     `clutter-actor-set-geometry', this function will return that
     coordinate.

     If both the allocation and a fixed position are missing, this
     function will return 0.

    SELF
          A `<clutter-actor>'

    RET
          the Y coordinate, in pixels, ignoring any transformation
          (i.e. scaling, rotation)



 -- Function: clutter-actor-move-by (self `<clutter-actor>')
          (dx `float') (dy `float')
 -- Method: move-by
     Moves an actor by the specified distance relative to its current
     position in pixels.

     This function modifies the fixed position of an actor and thus
     removes it from any layout management. Another way to move an
     actor is with an anchor point, see
     `clutter-actor-set-anchor-point'.

    SELF
          A `<clutter-actor>'

    DX
          Distance to move Actor on X axis.

    DY
          Distance to move Actor on Y axis.


     Since 0.2


 -- Function: clutter-actor-set-depth (self `<clutter-actor>')
          (depth `float')
 -- Method: set-depth
     Sets the Z coordinate of SELF to DEPTH.

     The unit used by DEPTH is dependant on the perspective setup. See
     also `clutter-stage-set-perspective'.

    SELF
          a `<clutter-actor>'

    DEPTH
          Z co-ord



 -- Function: clutter-actor-get-depth (self `<clutter-actor>') => 
          (ret `float')
 -- Method: get-depth
     Retrieves the depth of SELF.

    SELF
          a `<clutter-actor>'

    RET
          the depth of the actor



 -- Function: clutter-actor-set-scale (self `<clutter-actor>')
          (scale_x `double') (scale_y `double')
 -- Method: set-scale
     Scales an actor with the given factors. The scaling is relative to
     the scale center and the anchor point. The scale center is
     unchanged by this function and defaults to 0,0.

     The `<"scale-x">' and `<"scale-y">' properties are animatable.

    SELF
          A `<clutter-actor>'

    SCALE-X
          double factor to scale actor by horizontally.

    SCALE-Y
          double factor to scale actor by vertically.


     Since 0.2


 -- Function: clutter-actor-set-scale-full (self `<clutter-actor>')
          (scale_x `double') (scale_y `double') (center_x `float')
          (center_y `float')
 -- Method: set-scale-full
     Scales an actor with the given factors around the given center
     point.  The center point is specified in pixels relative to the
     anchor point (usually the top left corner of the actor).

     The `<"scale-x">' and `<"scale-y">' properties are animatable.

    SELF
          A `<clutter-actor>'

    SCALE-X
          double factor to scale actor by horizontally.

    SCALE-Y
          double factor to scale actor by vertically.

    CENTER-X
          X coordinate of the center of the scale.

    CENTER-Y
          Y coordinate of the center of the scale


     Since 1.0


 -- Function: clutter-actor-get-scale (self `<clutter-actor>') => 
          (scale_x `double') (scale_y `double')
 -- Method: get-scale
     Retrieves an actors scale factors.

    SELF
          A `<clutter-actor>'

    SCALE-X
          Location to store horizonal scale factor, or ``#f''.

    SCALE-Y
          Location to store vertical scale factor, or ``#f''.


     Since 0.2


 -- Function: clutter-actor-get-scale-center (self `<clutter-actor>')
          =>  (center_x `float') (center_y `float')
 -- Method: get-scale-center
     Retrieves the scale center coordinate in pixels relative to the
     top left corner of the actor. If the scale center was specified
     using a `<clutter-gravity>' this will calculate the pixel offset
     using the current size of the actor.

    SELF
          A `<clutter-actor>'

    CENTER-X
          Location to store the X position of the scale center, or
          ``#f''.

    CENTER-Y
          Location to store the Y position of the scale center, or
          ``#f''.


     Since 1.0


 -- Function: clutter-actor-get-scale-gravity (self `<clutter-actor>')
          =>  (ret `<clutter-gravity>')
 -- Method: get-scale-gravity
     Retrieves the scale center as a compass direction. If the scale
     center was specified in pixels or units this will return
     `CLUTTER_GRAVITY_NONE'.

    SELF
          A `<clutter-actor>'

    RET
          the scale gravity


     Since 1.0


 -- Function: clutter-actor-is-scaled (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: is-scaled
     Checks whether the actor is scaled in either dimension.

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor is scaled.


     Since 0.6


 -- Function: clutter-actor-set-rotation (self `<clutter-actor>')
          (axis `<clutter-rotate-axis>') (angle `double') (x `float')
          (y `float') (z `float')
 -- Method: set-rotation
     Sets the rotation angle of SELF around the given axis.

     The rotation center coordinates used depend on the value of AXIS:

        *        *        *
     `CLUTTER_X_AXIS' requires Y and Z

     `CLUTTER_Y_AXIS' requires X and Z

     `CLUTTER_Z_AXIS' requires X and Y

     The rotation coordinates are relative to the anchor point of the
     actor, set using `clutter-actor-set-anchor-point'. If no anchor
     point is set, the upper left corner is assumed as the origin.

    SELF
          a `<clutter-actor>'

    AXIS
          the axis of rotation

    ANGLE
          the angle of rotation

    X
          X coordinate of the rotation center

    Y
          Y coordinate of the rotation center

    Z
          Z coordinate of the rotation center


     Since 0.8


 -- Function: clutter-actor-get-rotation (self `<clutter-actor>')
          (axis `<clutter-rotate-axis>') =>  (ret `double') (x `float')
          (y `float') (z `float')
 -- Method: get-rotation
     Retrieves the angle and center of rotation on the given axis, set
     using `clutter-actor-set-rotation'.

    SELF
          a `<clutter-actor>'

    AXIS
          the axis of rotation

    X
          return value for the X coordinate of the center of rotation.

    Y
          return value for the Y coordinate of the center of rotation.

    Z
          return value for the Z coordinate of the center of rotation.

    RET
          the angle of rotation


     Since 0.8


 -- Function: clutter-actor-is-rotated (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: is-rotated
     Checks whether any rotation is applied to the actor.

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor is rotated.


     Since 0.6


 -- Function: clutter-actor-set-anchor-point (self `<clutter-actor>')
          (anchor_x `float') (anchor_y `float')
 -- Method: set-anchor-point
     Sets an anchor point for SELF. The anchor point is a point in the
     coordinate space of an actor to which the actor position within its
     parent is relative; the default is (0, 0), i.e. the top-left
     corner of the actor.

    SELF
          a `<clutter-actor>'

    ANCHOR-X
          X coordinate of the anchor point

    ANCHOR-Y
          Y coordinate of the anchor point


     Since 0.6


 -- Function: clutter-actor-get-anchor-point (self `<clutter-actor>')
          =>  (anchor_x `float') (anchor_y `float')
 -- Method: get-anchor-point
     Gets the current anchor point of the ACTOR in pixels.

    SELF
          a `<clutter-actor>'

    ANCHOR-X
          return location for the X coordinate of the anchor point.

    ANCHOR-Y
          return location for the Y coordinate of the anchor point.


     Since 0.6


 -- Function: clutter-actor-move-anchor-point (self `<clutter-actor>')
          (anchor_x `float') (anchor_y `float')
 -- Method: move-anchor-point
     Sets an anchor point for the actor, and adjusts the actor postion
     so that the relative position of the actor toward its parent
     remains the same.

    SELF
          a `<clutter-actor>'

    ANCHOR-X
          X coordinate of the anchor point

    ANCHOR-Y
          Y coordinate of the anchor point


     Since 0.6


 -- Function: clutter-actor-transform-stage-point
          (self `<clutter-actor>') (x `float') (y `float') => 
          (ret `bool') (x_out `float') (y_out `float')
 -- Method: transform-stage-point
     This function translates screen coordinates (X, Y) to coordinates
     relative to the actor. For example, it can be used to translate
     screen events from global screen coordinates into actor-local
     coordinates.

     The conversion can fail, notably if the transform stack results in
     the actor being projected on the screen as a mere line.

     The conversion should not be expected to be pixel-perfect due to
     the nature of the operation. In general the error grows when the
     skewing of the actor rectangle on screen increases.

     This function can be computationally intensive.

     This function only works when the allocation is up-to-date, i.e.
     inside of `paint'.

    SELF
          A `<clutter-actor>'

    X
          x screen coordinate of the point to unproject.

    Y
          y screen coordinate of the point to unproject.

    X-OUT
          return location for the unprojected x coordinance.

    Y-OUT
          return location for the unprojected y coordinance.

    RET
          ``#t'' if conversion was successful.


     Since 0.6


 -- Function: clutter-actor-get-transformed-size
          (self `<clutter-actor>') =>  (width `float') (height `float')
 -- Method: get-transformed-size
     Gets the absolute size of an actor in pixels, taking into account
     the scaling factors.

     If the actor has a valid allocation, the allocated size will be
     used. If the actor has not a valid allocation then the preferred
     size will be transformed and returned.

     If you want the transformed allocation, see
     `clutter-actor-get-abs-allocation-vertices' instead.

     When the actor (or one of its ancestors) is rotated around the X
     or Y axis, it no longer appears as on the stage as a rectangle, but
     as a generic quadrangle; in that case this function returns the
     size of the smallest rectangle that encapsulates the entire quad.
     Please note that in this case no assumptions can be made about the
     relative position of this envelope to the absolute position of the
     actor, as returned by `clutter-actor-get-transformed-position'; if
     you need this information, you need to use
     `clutter-actor-get-abs-allocation-vertices' to get the coords of
     the actual quadrangle.

    SELF
          A `<clutter-actor>'

    WIDTH
          return location for the width, or ``#f''.

    HEIGHT
          return location for the height, or ``#f''.


     Since 0.8


 -- Function: clutter-actor-get-paint-opacity (self `<clutter-actor>')
          =>  (ret `unsigned-int8')
 -- Method: get-paint-opacity
     Retrieves the absolute opacity of the actor, as it appears on the
     stage.

     This function traverses the hierarchy chain and composites the
     opacity of the actor with that of its parents.

     This function is intended for subclasses to use in the paint
     virtual function, to paint themselves with the correct opacity.

    SELF
          A `<clutter-actor>'

    RET
          The actor opacity value.


     Since 0.8


 -- Function: clutter-actor-get-paint-visibility
          (self `<clutter-actor>') =>  (ret `bool')
 -- Method: get-paint-visibility
     Retrieves the 'paint' visibility of an actor recursively checking
     for non visible parents.

     This is by definition the same as `CLUTTER_ACTOR_IS_MAPPED'.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor is visibile and will be painted.


     Since 0.8.4


 -- Function: clutter-actor-get-paint-box (self `<clutter-actor>')
          (box `<clutter-actor-box>') =>  (ret `bool')
 -- Method: get-paint-box
     Retrieves the paint volume of the passed `<clutter-actor>', and
     transforms it into a 2D bounding box in stage coordinates.

     This function is useful to determine the on screen area occupied
     by the actor. The box is only an approximation and may often be
     considerably larger due to the optimizations used to calculate the
     box. The box is never smaller though, so it can reliably be used
     for culling.

     There are times when a 2D paint box can't be determined, e.g.
     because the actor isn't yet parented under a stage or because the
     actor is unable to determine a paint volume.

    SELF
          a `<clutter-actor>'

    BOX
          return location for a `<clutter-actor-box>'.

    RET
          ``#t'' if a 2D paint box could be determined, else ``#f''.


     Since 1.6


 -- Function: clutter-actor-set-content (self `<clutter-actor>')
          (content `<clutter-content>')
 -- Method: set-content
     Sets the contents of a `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    CONTENT
          a `<clutter-content>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-content (self `<clutter-actor>') => 
          (ret `<clutter-content>')
 -- Method: get-content
     Retrieves the contents of SELF.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to the `<clutter-content>' instance, or ``#f'' if
          none was set.


     Since 1.10


 -- Function: clutter-actor-set-content-gravity
          (self `<clutter-actor>') (gravity `<clutter-content-gravity>')
 -- Method: set-content-gravity
     Sets the gravity of the `<clutter-content>' used by SELF.

     See the description of the `<"content-gravity">' property for more
     information.

     The `<"content-gravity">' property is animatable.

    SELF
          a `<clutter-actor>'

    GRAVITY
          the `<clutter-content-gravity>'


     Since 1.10


 -- Function: clutter-actor-get-content-gravity
          (self `<clutter-actor>') =>  (ret `<clutter-content-gravity>')
 -- Method: get-content-gravity
     Retrieves the content gravity as set using
     `clutter-actor-get-content-gravity'.

    SELF
          a `<clutter-actor>'

    RET
          the content gravity


     Since 1.10


 -- Function: clutter-actor-get-content-box (self `<clutter-actor>')
          (box `<clutter-actor-box>')
 -- Method: get-content-box
     Retrieves the bounding box for the `<clutter-content>' of SELF.

     The bounding box is relative to the actor's allocation.

     If no `<clutter-content>' is set for SELF, or if SELF has not been
     allocated yet, then the result is undefined.

     The content box is guaranteed to be, at most, as big as the
     allocation of the `<clutter-actor>'.

     If the `<clutter-content>' used by the actor has a preferred size,
     then it is possible to modify the content box by using the
     `<"content-gravity">' property.

    SELF
          a `<clutter-actor>'

    BOX
          the return location for the bounding box for the
          `<clutter-content>'.


     Since 1.10


 -- Function: clutter-actor-set-clip (self `<clutter-actor>')
          (xoff `float') (yoff `float') (width `float') (height `float')
 -- Method: set-clip
     Sets clip area for SELF. The clip area is always computed from the
     upper left corner of the actor, even if the anchor point is set
     otherwise.

    SELF
          A `<clutter-actor>'

    XOFF
          X offset of the clip rectangle

    YOFF
          Y offset of the clip rectangle

    WIDTH
          Width of the clip rectangle

    HEIGHT
          Height of the clip rectangle


     Since 0.6


 -- Function: clutter-actor-remove-clip (self `<clutter-actor>')
 -- Method: remove-clip
     Removes clip area from SELF.

    SELF
          A `<clutter-actor>'



 -- Function: clutter-actor-has-clip (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-clip
     Determines whether the actor has a clip area set or not.

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor has a clip area set.


     Since 0.1.1


 -- Function: clutter-actor-get-clip (self `<clutter-actor>') => 
          (xoff `float') (yoff `float') (width `float') (height `float')
 -- Method: get-clip
     Gets the clip area for SELF, if any is set

    SELF
          a `<clutter-actor>'

    XOFF
          return location for the X offset of the clip rectangle, or
          ``#f''.

    YOFF
          return location for the Y offset of the clip rectangle, or
          ``#f''.

    WIDTH
          return location for the width of the clip rectangle, or
          ``#f''.

    HEIGHT
          return location for the height of the clip rectangle, or
          ``#f''.


     Since 0.6


 -- Function: clutter-actor-set-opacity (self `<clutter-actor>')
          (opacity `unsigned-int8')
 -- Method: set-opacity
     Sets the actor's opacity, with zero being completely transparent
     and 255 (0xff) being fully opaque.

     The `<"opacity">' property is animatable.

    SELF
          A `<clutter-actor>'

    OPACITY
          New opacity value for the actor.



 -- Function: clutter-actor-get-opacity (self `<clutter-actor>') => 
          (ret `unsigned-int8')
 -- Method: get-opacity
     Retrieves the opacity value of an actor, as set by
     `clutter-actor-set-opacity'.

     For retrieving the absolute opacity of the actor inside a paint
     virtual function, see `clutter-actor-get-paint-opacity'.

    SELF
          a `<clutter-actor>'

    RET
          the opacity of the actor



 -- Function: clutter-actor-is-in-clone-paint (self `<clutter-actor>')
          =>  (ret `bool')
 -- Method: is-in-clone-paint
     Checks whether SELF is being currently painted by a
     `<clutter-clone>'

     This function is useful only inside the ::paint virtual function
     implementations or within handlers for the `<"paint">' signal

     This function should not be used by applications

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the `<clutter-actor>' is currently being painted by
          a `<clutter-clone>', and ``#f'' otherwise


     Since 1.0


 -- Function: clutter-actor-add-child (self `<clutter-actor>')
          (child `<clutter-actor>')
 -- Method: add-child
     Adds CHILD to the children of SELF.

     This function will acquire a reference on CHILD that will only be
     released when calling `clutter-actor-remove-child'.

     This function will take into consideration the `<"depth">' of
     CHILD, and will keep the list of children sorted.

     This function will emit the `<"actor-added">' signal on SELF.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-insert-child-above (self `<clutter-actor>')
          (child `<clutter-actor>') (sibling `<clutter-actor>')
 -- Method: insert-child-above
     Inserts CHILD into the list of children of SELF, above another
     child of SELF or, if SIBLING is ``#f'', above all the children of
     SELF.

     This function will acquire a reference on CHILD that will only be
     released when calling `clutter-actor-remove-child'.

     This function will not take into consideration the `<"depth">' of
     CHILD.

     This function will emit the `<"actor-added">' signal on SELF.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>'

    SIBLING
          a child of SELF, or ``#f''.


     Since 1.10


 -- Function: clutter-actor-insert-child-at-index
          (self `<clutter-actor>') (child `<clutter-actor>')
          (index_ `int')
 -- Method: insert-child-at-index
     Inserts CHILD into the list of children of SELF, using the given
     INDEX. If INDEX is greater than the number of children in SELF, or
     is less than 0, then the new child is added at the end.

     This function will acquire a reference on CHILD that will only be
     released when calling `clutter-actor-remove-child'.

     This function will not take into consideration the `<"depth">' of
     CHILD.

     This function will emit the `<"actor-added">' signal on SELF.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>'

    INDEX
          the index


     Since 1.10


 -- Function: clutter-actor-insert-child-below (self `<clutter-actor>')
          (child `<clutter-actor>') (sibling `<clutter-actor>')
 -- Method: insert-child-below
     Inserts CHILD into the list of children of SELF, below another
     child of SELF or, if SIBLING is ``#f'', below all the children of
     SELF.

     This function will acquire a reference on CHILD that will only be
     released when calling `clutter-actor-remove-child'.

     This function will not take into consideration the `<"depth">' of
     CHILD.

     This function will emit the `<"actor-added">' signal on SELF.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>'

    SIBLING
          a child of SELF, or ``#f''.


     Since 1.10


 -- Function: clutter-actor-replace-child (self `<clutter-actor>')
          (old_child `<clutter-actor>') (new_child `<clutter-actor>')
 -- Method: replace-child
     Replaces OLD-CHILD with NEW-CHILD in the list of children of SELF.

    SELF
          a `<clutter-actor>'

    OLD-CHILD
          the child of SELF to replace

    NEW-CHILD
          the `<clutter-actor>' to replace OLD-CHILD


     Since 1.10


 -- Function: clutter-actor-remove-child (self `<clutter-actor>')
          (child `<clutter-actor>')
 -- Method: remove-child
     Removes CHILD from the children of SELF.

     This function will release the reference added by
     `clutter-actor-add-child', so if you want to keep using CHILD you
     will have to acquire a referenced on it before calling this
     function.

     This function will emit the `<"actor-removed">' signal on SELF.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-remove-all-children (self `<clutter-actor>')
 -- Method: remove-all-children
     Removes all children of SELF.

     This function releases the reference added by inserting a child
     actor in the list of children of SELF.

     If the reference count of a child drops to zero, the child will be
     destroyed. If you want to ensure the destruction of all the
     children of SELF, use `clutter-actor-destroy-all-children'.

    SELF
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-destroy-all-children
          (self `<clutter-actor>')
 -- Method: destroy-all-children
     Destroys all children of SELF.

     This function releases the reference added by inserting a child
     actor in the list of children of SELF, and ensures that the
     `<"destroy">' signal is emitted on each child of the actor.

     By default, `<clutter-actor>' will emit the `<"destroy">' signal
     when its reference count drops to 0; the default handler of the
     `<"destroy">' signal will destroy all the children of an actor.
     This function ensures that all children are destroyed, instead of
     just removed from SELF, unlike `clutter-actor-remove-all-children'
     which will merely release the reference and remove each child.

     Unless you acquired an additional reference on each child of SELF
     prior to calling `clutter-actor-remove-all-children' and want to
     reuse the actors, you should use
     `clutter-actor-destroy-all-children' in order to make sure that
     children are destroyed and signal handlers are disconnected even in
     cases where circular references prevent this from automatically
     happening through reference counting alone.

    SELF
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-get-first-child (self `<clutter-actor>')
          =>  (ret `<clutter-actor>')
 -- Method: get-first-child
     Retrieves the first child of SELF.

     The returned pointer is only valid until the scene graph changes;
     it is not safe to modify the list of children of SELF while
     iterating it.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to a `<clutter-actor>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-next-sibling (self `<clutter-actor>')
          =>  (ret `<clutter-actor>')
 -- Method: get-next-sibling
     Retrieves the sibling of SELF that comes after it in the list of
     children of SELF's parent.

     The returned pointer is only valid until the scene graph changes;
     it is not safe to modify the list of children of SELF while
     iterating it.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to a `<clutter-actor>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-previous-sibling
          (self `<clutter-actor>') =>  (ret `<clutter-actor>')
 -- Method: get-previous-sibling
     Retrieves the sibling of SELF that comes before it in the list of
     children of SELF's parent.

     The returned pointer is only valid until the scene graph changes;
     it is not safe to modify the list of children of SELF while
     iterating it.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to a `<clutter-actor>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-last-child (self `<clutter-actor>') => 
          (ret `<clutter-actor>')
 -- Method: get-last-child
     Retrieves the last child of SELF.

     The returned pointer is only valid until the scene graph changes;
     it is not safe to modify the list of children of SELF while
     iterating it.

    SELF
          a `<clutter-actor>'

    RET
          a pointer to a `<clutter-actor>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-child-at-index (self `<clutter-actor>')
          (index_ `int') =>  (ret `<clutter-actor>')
 -- Method: get-child-at-index
     Retrieves the actor at the given INDEX inside the list of children
     of SELF.

    SELF
          a `<clutter-actor>'

    INDEX
          the position in the list of children

    RET
          a pointer to a `<clutter-actor>', or ``#f''.


     Since 1.10


 -- Function: clutter-actor-get-children (self `<clutter-actor>') => 
          (ret `glist-of')
 -- Method: get-children
     Retrieves the list of children of SELF.

    SELF
          a `<clutter-actor>'

    RET
          A newly allocated `<g-list>' of `<clutter-actor>'s. Use
          `g-list-free' when done.


     Since 1.10


 -- Function: clutter-actor-get-n-children (self `<clutter-actor>') => 
          (ret `int')
 -- Method: get-n-children
     Retrieves the number of children of SELF.

    SELF
          a `<clutter-actor>'

    RET
          the number of children of an actor


     Since 1.10


 -- Function: clutter-actor-get-parent (self `<clutter-actor>') => 
          (ret `<clutter-actor>')
 -- Method: get-parent
     Retrieves the parent of SELF.

    SELF
          A `<clutter-actor>'

    RET
          The `<clutter-actor>' parent, or ``#f'' if no parent is set.



 -- Function: clutter-actor-set-child-at-index (self `<clutter-actor>')
          (child `<clutter-actor>') (index_ `int')
 -- Method: set-child-at-index
     Changes the index of CHILD in the list of children of SELF.

     This function is logically equivalent to removing CHILD and
     calling `clutter-actor-insert-child-at-index', but it will not emit
     signals or change state on CHILD.

    SELF
          a `<clutter-actor>'

    CHILD
          a `<clutter-actor>' child of SELF

    INDEX
          the new index for CHILD


     Since 1.10


 -- Function: clutter-actor-contains (self `<clutter-actor>')
          (descendant `<clutter-actor>') =>  (ret `bool')
 -- Method: contains
     Determines if DESCENDANT is contained inside SELF (either as an
     immediate child, or as a deeper descendant). If SELF and
     DESCENDANT point to the same actor then it will also return ``#t''.

    SELF
          A `<clutter-actor>'

    DESCENDANT
          A `<clutter-actor>', possibly contained in SELF

    RET
          whether DESCENDENT is contained within SELF


     Since 1.4


 -- Function: clutter-actor-get-stage (self `<clutter-actor>') => 
          (ret `<clutter-actor>')
 -- Method: get-stage
     Retrieves the `<clutter-stage>' where ACTOR is contained.

    ACTOR
          a `<clutter-actor>'

    RET
          the stage containing the actor, or ``#f''.


     Since 0.8


 -- Function: clutter-actor-save-easing-state (self `<clutter-actor>')
 -- Method: save-easing-state
     Saves the current easing state for animatable properties, and
     creates a new state with the default values for easing mode and
     duration.

    SELF
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-restore-easing-state
          (self `<clutter-actor>')
 -- Method: restore-easing-state
     Restores the easing state as it was prior to a call to
     `clutter-actor-save-easing-state'.

    SELF
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-actor-set-easing-duration
          (self `<clutter-actor>') (msecs `unsigned-int')
 -- Method: set-easing-duration
     Sets the duration of the tweening for animatable properties of
     SELF for the current easing state.

    SELF
          a `<clutter-actor>'

    MSECS
          the duration of the easing, or ``#f''


     Since 1.10


 -- Function: clutter-actor-get-easing-duration
          (self `<clutter-actor>') =>  (ret `unsigned-int')
 -- Method: get-easing-duration
     Retrieves the duration of the tweening for animatable properties of
     SELF for the current easing state.

    SELF
          a `<clutter-actor>'

    RET
          the duration of the tweening, in milliseconds


     Since 1.10


 -- Function: clutter-actor-set-easing-mode (self `<clutter-actor>')
          (mode `<clutter-animation-mode>')
 -- Method: set-easing-mode
     Sets the easing mode for the tweening of animatable properties of
     SELF.

    SELF
          a `<clutter-actor>'

    MODE
          an easing mode, excluding `CLUTTER_CUSTOM_MODE'


     Since 1.10


 -- Function: clutter-actor-get-easing-mode (self `<clutter-actor>')
          =>  (ret `<clutter-animation-mode>')
 -- Method: get-easing-mode
     Retrieves the easing mode for the tweening of animatable
     properties of SELF for the current easing state.

    SELF
          a `<clutter-actor>'

    RET
          an easing mode


     Since 1.10


 -- Function: clutter-actor-set-easing-delay (self `<clutter-actor>')
          (msecs `unsigned-int')
 -- Method: set-easing-delay
     Sets the delay that should be applied before tweening animatable
     properties.

    SELF
          a `<clutter-actor>'

    MSECS
          the delay before the start of the tweening, in milliseconds


     Since 1.10


 -- Function: clutter-actor-get-easing-delay (self `<clutter-actor>')
          =>  (ret `unsigned-int')
 -- Method: get-easing-delay
     Retrieves the delay that should be applied when tweening animatable
     properties.

    SELF
          a `<clutter-actor>'

    RET
          a delay, in milliseconds


     Since 1.10


 -- Function: clutter-actor-get-transition (self `<clutter-actor>')
          (name `mchars') =>  (ret `<clutter-transition>')
 -- Method: get-transition
     Retrieves the `<clutter-transition>' of a `<clutter-actor>' by
     using the transition NAME.

     Transitions created for animatable properties use the name of the
     property itself, for instance the code below:


            clutter_actor_set_easing_duration (actor, 1000);
            clutter_actor_set_rotation (actor, CLUTTER_Y_AXIS, 360.0, x, y, z);

            transition = clutter_actor_get_transition (actor, "rotation-angle-y");
            g_signal_connect (transition, "completed",
                              G_CALLBACK (on_transition_complete),
                              actor);

     will call the `on-transition-complete' callback when the transition
     is complete.

    SELF
          a `<clutter-actor>'

    NAME
          the name of the transition

    RET
          a `<clutter-transition>', or ``#f'' is none was found to
          match the passed name; the returned instance is owned by
          Clutter and it should not be freed.


     Since 1.10


 -- Function: clutter-actor-add-transition (self `<clutter-actor>')
          (name `mchars') (transition `<clutter-transition>')
 -- Method: add-transition
     Adds a TRANSITION to the `<clutter-actor>''s list of animations.

     The NAME string is a per-actor unique identifier of the
     TRANSITION: only one `<clutter-transition>' can be associated to
     the specified NAME.

     The TRANSITION will be given the easing duration, mode, and delay
     associated to the actor's current easing state; it is possible to
     modify these values after calling `clutter-actor-add-transition'.

     The TRANSITION will be started once added.

     This function will take a reference on the TRANSITION.

     This function is usually called implicitly when modifying an
     animatable property.

    SELF
          a `<clutter-actor>'

    NAME
          the name of the transition to add

    TRANSITION
          the `<clutter-transition>' to add


     Since 1.10


 -- Function: clutter-actor-remove-transition (self `<clutter-actor>')
          (name `mchars')
 -- Method: remove-transition
     Removes the transition stored inside a `<clutter-actor>' using
     NAME identifier.

     If the transition is currently in progress, it will be stopped.

     This function releases the reference acquired when the transition
     was added to the `<clutter-actor>'.

    SELF
          a `<clutter-actor>'

    NAME
          the name of the transition to remove


     Since 1.10


 -- Function: clutter-actor-set-reactive (self `<clutter-actor>')
          (reactive `bool')
 -- Method: set-reactive
     Sets ACTOR as reactive. Reactive actors will receive events.

    ACTOR
          a `<clutter-actor>'

    REACTIVE
          whether the actor should be reactive to events


     Since 0.6


 -- Function: clutter-actor-get-reactive (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: get-reactive
     Checks whether ACTOR is marked as reactive.

    ACTOR
          a `<clutter-actor>'

    RET
          ``#t'' if the actor is reactive


     Since 0.6


 -- Function: clutter-actor-has-key-focus (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-key-focus
     Checks whether SELF is the `<clutter-actor>' that has key focus

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor has key focus, and ``#f'' otherwise


     Since 1.4


 -- Function: clutter-actor-grab-key-focus (self `<clutter-actor>')
 -- Method: grab-key-focus
     Sets the key focus of the `<clutter-stage>' including SELF to this
     `<clutter-actor>'.

    SELF
          a `<clutter-actor>'


     Since 1.0


 -- Function: clutter-actor-has-pointer (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-pointer
     Checks whether an actor contains the pointer of a
     `<clutter-input-device>'

    SELF
          a `<clutter-actor>'

    RET
          ``#t'' if the actor contains the pointer, and ``#f'' otherwise


     Since 1.2


 -- Function: clutter-actor-get-pango-context (self `<clutter-actor>')
          =>  (ret `<pango-context>')
 -- Method: get-pango-context
     Retrieves the `<pango-context>' for SELF. The actor's
     `<pango-context>' is already configured using the appropriate font
     map, resolution and font options.

     Unlike `clutter-actor-create-pango-context', this context is owend
     by the `<clutter-actor>' and it will be updated each time the
     options stored by the `<clutter-backend>' change.

     You can use the returned `<pango-context>' to create a
     `<pango-layout>' and render text using `cogl-pango-render-layout'
     to reuse the glyphs cache also used by Clutter.

    SELF
          a `<clutter-actor>'

    RET
          the `<pango-context>' for a `<clutter-actor>'. The returned
          `<pango-context>' is owned by the actor and should not be
          unreferenced by the application code.


     Since 1.0


 -- Function: clutter-actor-create-pango-context
          (self `<clutter-actor>') =>  (ret `<pango-context>')
 -- Method: create-pango-context
     Creates a `<pango-context>' for the given actor. The
     `<pango-context>' is already configured using the appropriate font
     map, resolution and font options.

     See also `clutter-actor-get-pango-context'.

    SELF
          a `<clutter-actor>'

    RET
          the newly created `<pango-context>'. Use `g-object-unref' on
          the returned value to deallocate its resources.


     Since 1.0


 -- Function: clutter-actor-create-pango-layout
          (self `<clutter-actor>') (text `mchars') => 
          (ret `<pango-layout>')
 -- Method: create-pango-layout
     Creates a new `<pango-layout>' from the same `<pango-context>'
     used by the `<clutter-actor>'. The `<pango-layout>' is already
     configured with the font map, resolution and font options, and the
     given TEXT.

     If you want to keep around a `<pango-layout>' created by this
     function you will have to connect to the `<"font-changed">' and
     `<"resolution-changed">' signals, and call
     `pango-layout-context-changed' in response to them.

    SELF
          a `<clutter-actor>'

    TEXT
          (allow-none) the text to set on the `<pango-layout>', or
          ``#f''

    RET
          the newly created `<pango-layout>'. Use `g-object-unref' when
          done.


     Since 1.0


 -- Function: clutter-actor-set-text-direction (self `<clutter-actor>')
          (text_dir `<clutter-text-direction>')
 -- Method: set-text-direction
     Sets the `<clutter-text-direction>' for an actor

     The passed text direction must not be
     `CLUTTER_TEXT_DIRECTION_DEFAULT'

     If SELF implements `<clutter-container>' then this function will
     recurse inside all the children of SELF (including the internal
     ones).

     Composite actors not implementing `<clutter-container>', or actors
     requiring special handling when the text direction changes, should
     connect to the `<"notify">' signal for the `<"text-direction">'
     property

    SELF
          a `<clutter-actor>'

    TEXT-DIR
          the text direction for SELF


     Since 1.2


 -- Function: clutter-actor-get-text-direction (self `<clutter-actor>')
          =>  (ret `<clutter-text-direction>')
 -- Method: get-text-direction
     Retrieves the value set using `clutter-actor-set-text-direction'

     If no text direction has been previously set, the default text
     direction, as returned by `clutter-get-default-text-direction',
     will be returned instead

    SELF
          a `<clutter-actor>'

    RET
          the `<clutter-text-direction>' for the actor


     Since 1.2


 -- Function: clutter-actor-get-accessible (self `<clutter-actor>') => 
          (ret `<atk-object>')
 -- Method: get-accessible
     Returns the accessible object that describes the actor to an
     assistive technology.

     If no class-specific `<atk-object>' implementation is available for
     the actor instance in question, it will inherit an `<atk-object>'
     implementation from the first ancestor class for which such an
     implementation is defined.

     The documentation of the ATK
     (http://developer.gnome.org/doc/API/2.0/atk/index.html) library
     contains more information about accessible objects and their uses.

    SELF
          a `<clutter-actor>'

    RET
          the `<atk-object>' associated with ACTOR.



 -- Function: clutter-actor-add-action (self `<clutter-actor>')
          (action `<clutter-action>')
 -- Method: add-action
     Adds ACTION to the list of actions applied to SELF

     A `<clutter-action>' can only belong to one actor at a time

     The `<clutter-actor>' will hold a reference on ACTION until either
     `clutter-actor-remove-action' or `clutter-actor-clear-actions' is
     called

    SELF
          a `<clutter-actor>'

    ACTION
          a `<clutter-action>'


     Since 1.4


 -- Function: clutter-actor-add-action-with-name
          (self `<clutter-actor>') (name `mchars')
          (action `<clutter-action>')
 -- Method: add-action-with-name
     A convenience function for setting the name of a `<clutter-action>'
     while adding it to the list of actions applied to SELF

     This function is the logical equivalent of:


            clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
            clutter_actor_add_action (self, action);

    SELF
          a `<clutter-actor>'

    NAME
          the name to set on the action

    ACTION
          a `<clutter-action>'


     Since 1.4


 -- Function: clutter-actor-remove-action (self `<clutter-actor>')
          (action `<clutter-action>')
 -- Method: remove-action
     Removes ACTION from the list of actions applied to SELF

     The reference held by SELF on the `<clutter-action>' will be
     released

    SELF
          a `<clutter-actor>'

    ACTION
          a `<clutter-action>'


     Since 1.4


 -- Function: clutter-actor-remove-action-by-name
          (self `<clutter-actor>') (name `mchars')
 -- Method: remove-action-by-name
     Removes the `<clutter-action>' with the given name from the list of
     actions applied to SELF

    SELF
          a `<clutter-actor>'

    NAME
          the name of the action to remove


     Since 1.4


 -- Function: clutter-actor-has-actions (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-actions
     Returns whether the actor has any actions applied.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor has any actions, ``#f'' otherwise


     Since 1.10


 -- Function: clutter-actor-get-actions (self `<clutter-actor>') => 
          (ret `glist-of')
 -- Method: get-actions
     Retrieves the list of actions applied to SELF

    SELF
          a `<clutter-actor>'

    RET
          a copy of the list of `<clutter-action>'s. The contents of
          the list are owned by the `<clutter-actor>'. Use
          `g-list-free' to free the resources allocated by the returned
          `<g-list>'.


     Since 1.4


 -- Function: clutter-actor-get-action (self `<clutter-actor>')
          (name `mchars') =>  (ret `<clutter-action>')
 -- Method: get-action
     Retrieves the `<clutter-action>' with the given name in the list of
     actions applied to SELF

    SELF
          a `<clutter-actor>'

    NAME
          the name of the action to retrieve

    RET
          a `<clutter-action>' for the given name, or ``#f''. The
          returned `<clutter-action>' is owned by the actor and it
          should not be unreferenced directly.


     Since 1.4


 -- Function: clutter-actor-clear-actions (self `<clutter-actor>')
 -- Method: clear-actions
     Clears the list of actions applied to SELF

    SELF
          a `<clutter-actor>'


     Since 1.4


 -- Function: clutter-actor-add-constraint (self `<clutter-actor>')
          (constraint `<clutter-constraint>')
 -- Method: add-constraint
     Adds CONSTRAINT to the list of `<clutter-constraint>'s applied to
     SELF

     The `<clutter-actor>' will hold a reference on the CONSTRAINT
     until either `clutter-actor-remove-constraint' or
     `clutter-actor-clear-constraints' is called.

    SELF
          a `<clutter-actor>'

    CONSTRAINT
          a `<clutter-constraint>'


     Since 1.4


 -- Function: clutter-actor-remove-constraint (self `<clutter-actor>')
          (constraint `<clutter-constraint>')
 -- Method: remove-constraint
     Removes CONSTRAINT from the list of constraints applied to SELF

     The reference held by SELF on the `<clutter-constraint>' will be
     released

    SELF
          a `<clutter-actor>'

    CONSTRAINT
          a `<clutter-constraint>'


     Since 1.4


 -- Function: clutter-actor-has-constraints (self `<clutter-actor>')
          =>  (ret `bool')
 -- Method: has-constraints
     Returns whether the actor has any constraints applied.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor has any constraints, ``#f'' otherwise


     Since 1.10


 -- Function: clutter-actor-get-constraints (self `<clutter-actor>')
          =>  (ret `glist-of')
 -- Method: get-constraints
     Retrieves the list of constraints applied to SELF

    SELF
          a `<clutter-actor>'

    RET
          a copy of the list of `<clutter-constraint>'s. The contents
          of the list are owned by the `<clutter-actor>'. Use
          `g-list-free' to free the resources allocated by the returned
          `<g-list>'.


     Since 1.4


 -- Function: clutter-actor-get-constraint (self `<clutter-actor>')
          (name `mchars') =>  (ret `<clutter-constraint>')
 -- Method: get-constraint
     Retrieves the `<clutter-constraint>' with the given name in the
     list of constraints applied to SELF

    SELF
          a `<clutter-actor>'

    NAME
          the name of the constraint to retrieve

    RET
          a `<clutter-constraint>' for the given name, or ``#f''.  The
          returned `<clutter-constraint>' is owned by the actor and it
          should not be unreferenced directly.


     Since 1.4


 -- Function: clutter-actor-clear-constraints (self `<clutter-actor>')
 -- Method: clear-constraints
     Clears the list of constraints applied to SELF

    SELF
          a `<clutter-actor>'


     Since 1.4


 -- Function: clutter-actor-add-effect (self `<clutter-actor>')
          (effect `<clutter-effect>')
 -- Method: add-effect
     Adds EFFECT to the list of `<clutter-effect>'s applied to SELF

     The `<clutter-actor>' will hold a reference on the EFFECT until
     either `clutter-actor-remove-effect' or
     `clutter-actor-clear-effects' is called.

    SELF
          a `<clutter-actor>'

    EFFECT
          a `<clutter-effect>'


     Since 1.4


 -- Function: clutter-actor-add-effect-with-name
          (self `<clutter-actor>') (name `mchars')
          (effect `<clutter-effect>')
 -- Method: add-effect-with-name
     A convenience function for setting the name of a `<clutter-effect>'
     while adding it to the list of effectss applied to SELF

     This function is the logical equivalent of:


            clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
            clutter_actor_add_effect (self, effect);

    SELF
          a `<clutter-actor>'

    NAME
          the name to set on the effect

    EFFECT
          a `<clutter-effect>'


     Since 1.4


 -- Function: clutter-actor-remove-effect (self `<clutter-actor>')
          (effect `<clutter-effect>')
 -- Method: remove-effect
     Removes EFFECT from the list of effects applied to SELF

     The reference held by SELF on the `<clutter-effect>' will be
     released

    SELF
          a `<clutter-actor>'

    EFFECT
          a `<clutter-effect>'


     Since 1.4


 -- Function: clutter-actor-remove-effect-by-name
          (self `<clutter-actor>') (name `mchars')
 -- Method: remove-effect-by-name
     Removes the `<clutter-effect>' with the given name from the list of
     effects applied to SELF

    SELF
          a `<clutter-actor>'

    NAME
          the name of the effect to remove


     Since 1.4


 -- Function: clutter-actor-has-effects (self `<clutter-actor>') => 
          (ret `bool')
 -- Method: has-effects
     Returns whether the actor has any effects applied.

    SELF
          A `<clutter-actor>'

    RET
          ``#t'' if the actor has any effects, ``#f'' otherwise


     Since 1.10


 -- Function: clutter-actor-get-effects (self `<clutter-actor>') => 
          (ret `glist-of')
 -- Method: get-effects
     Retrieves the `<clutter-effect>'s applied on SELF, if any

    SELF
          a `<clutter-actor>'

    RET
          a list of `<clutter-effect>'s, or ``#f''. The elements of the
          returned list are owned by Clutter and they should not be
          freed. You should free the returned list using `g-list-free'
          when done.


     Since 1.4


 -- Function: clutter-actor-get-effect (self `<clutter-actor>')
          (name `mchars') =>  (ret `<clutter-effect>')
 -- Method: get-effect
     Retrieves the `<clutter-effect>' with the given name in the list of
     effects applied to SELF

    SELF
          a `<clutter-actor>'

    NAME
          the name of the effect to retrieve

    RET
          a `<clutter-effect>' for the given name, or ``#f''. The
          returned `<clutter-effect>' is owned by the actor and it
          should not be unreferenced directly.


     Since 1.4


 -- Function: clutter-actor-clear-effects (self `<clutter-actor>')
 -- Method: clear-effects
     Clears the list of effects applied to SELF

    SELF
          a `<clutter-actor>'


     Since 1.4


 -- Function: clutter-actor-box-new (x_1 `float') (y_1 `float')
          (x_2 `float') (y_2 `float') =>  (ret `<clutter-actor-box>')
     Allocates a new `<clutter-actor-box>' using the passed coordinates
     for the top left and bottom right points

    X-1
          X coordinate of the top left point

    Y-1
          Y coordinate of the top left point

    X-2
          X coordinate of the bottom right point

    Y-2
          Y coordinate of the bottom right point

    RET
          the newly allocated `<clutter-actor-box>'. Use
          `clutter-actor-box-free' to free the resources


     Since 1.0


 -- Function: clutter-actor-box-init (self `<clutter-actor-box>')
          (x_1 `float') (y_1 `float') (x_2 `float') (y_2 `float')
     Initializes BOX with the given coordinates.

    BOX
          a `<clutter-actor-box>'

    X-1
          X coordinate of the top left point

    Y-1
          Y coordinate of the top left point

    X-2
          X coordinate of the bottom right point

    Y-2
          Y coordinate of the bottom right point


     Since 1.10


 -- Function: clutter-actor-box-init-rect (self `<clutter-actor-box>')
          (x `float') (y `float') (width `float') (height `float')
     Initializes BOX with the given origin and size.

    BOX
          a `<clutter-actor-box>'

    X
          X coordinate of the origin

    Y
          Y coordinate of the origin

    WIDTH
          width of the box

    HEIGHT
          height of the box


     Since 1.10


 -- Function: clutter-actor-box-equal (self `<clutter-actor-box>')
          (box_b `<clutter-actor-box>') =>  (ret `bool')
     Checks BOX-A and BOX-B for equality

    BOX-A
          a `<clutter-actor-box>'

    BOX-B
          a `<clutter-actor-box>'

    RET
          ``#t'' if the passed `<clutter-actor-box>' are equal


     Since 1.0


 -- Function: clutter-actor-box-get-x (self `<clutter-actor-box>') => 
          (ret `float')
     Retrieves the X coordinate of the origin of BOX

    BOX
          a `<clutter-actor-box>'

    RET
          the X coordinate of the origin


     Since 1.0


 -- Function: clutter-actor-box-get-y (self `<clutter-actor-box>') => 
          (ret `float')
     Retrieves the Y coordinate of the origin of BOX

    BOX
          a `<clutter-actor-box>'

    RET
          the Y coordinate of the origin


     Since 1.0


 -- Function: clutter-actor-box-get-width (self `<clutter-actor-box>')
          =>  (ret `float')
     Retrieves the width of the BOX

    BOX
          a `<clutter-actor-box>'

    RET
          the width of the box


     Since 1.0


 -- Function: clutter-actor-box-get-height (self `<clutter-actor-box>')
          =>  (ret `float')
     Retrieves the height of the BOX

    BOX
          a `<clutter-actor-box>'

    RET
          the height of the box


     Since 1.0


 -- Function: clutter-actor-box-set-origin (self `<clutter-actor-box>')
          (x `float') (y `float')
     Changes the origin of BOX, maintaining the size of the
     `<clutter-actor-box>'.

    BOX
          a `<clutter-actor-box>'

    X
          the X coordinate of the new origin

    Y
          the Y coordinate of the new origin


     Since 1.6


 -- Function: clutter-actor-box-get-origin (self `<clutter-actor-box>')
          =>  (x `float') (y `float')
     Retrieves the origin of BOX

    BOX
          a `<clutter-actor-box>'

    X
          return location for the X coordinate, or ``#f''.

    Y
          return location for the Y coordinate, or ``#f''.


     Since 1.0


 -- Function: clutter-actor-box-set-size (self `<clutter-actor-box>')
          (width `float') (height `float')
     Sets the size of BOX, maintaining the origin of the
     `<clutter-actor-box>'.

    BOX
          a `<clutter-actor-box>'

    WIDTH
          the new width

    HEIGHT
          the new height


     Since 1.6


 -- Function: clutter-actor-box-get-size (self `<clutter-actor-box>')
          =>  (width `float') (height `float')
     Retrieves the size of BOX

    BOX
          a `<clutter-actor-box>'

    WIDTH
          return location for the width, or ``#f''.

    HEIGHT
          return location for the height, or ``#f''.


     Since 1.0


 -- Function: clutter-actor-box-get-area (self `<clutter-actor-box>')
          =>  (ret `float')
     Retrieves the area of BOX

    BOX
          a `<clutter-actor-box>'

    RET
          the area of a `<clutter-actor-box>', in pixels


     Since 1.0


 -- Function: clutter-actor-box-contains (self `<clutter-actor-box>')
          (x `float') (y `float') =>  (ret `bool')
     Checks whether a point with X, Y coordinates is contained withing
     BOX

    BOX
          a `<clutter-actor-box>'

    X
          X coordinate of the point

    Y
          Y coordinate of the point

    RET
          ``#t'' if the point is contained by the `<clutter-actor-box>'


     Since 1.0


 -- Function: clutter-actor-box-clamp-to-pixel
          (self `<clutter-actor-box>')
     Clamps the components of BOX to the nearest integer

    BOX
          the `<clutter-actor-box>' to clamp.


     Since 1.2


 -- Function: clutter-actor-box-interpolate
          (self `<clutter-actor-box>') (final `<clutter-actor-box>')
          (progress `double') (result `<clutter-actor-box>')
     Interpolates between INITIAL and FINAL`<clutter-actor-box>'es
     using PROGRESS

    INITIAL
          the initial `<clutter-actor-box>'

    FINAL
          the final `<clutter-actor-box>'

    PROGRESS
          the interpolation progress

    RESULT
          return location for the interpolation.


     Since 1.2


 -- Function: clutter-actor-box-union (self `<clutter-actor-box>')
          (b `<clutter-actor-box>') (result `<clutter-actor-box>')
     Unions the two boxes A and B and stores the result in RESULT.

    A
          (in) the first `<clutter-actor-box>'

    B
          the second `<clutter-actor-box>'.

    RESULT
          the `<clutter-actor-box>' representing a union of A and B.


     Since 1.4


 -- Function: clutter-vertex-new (x `float') (y `float') (z `float')
          =>  (ret `<clutter-vertex>')
     Creates a new `<clutter-vertex>' for the point in 3D space
     identified by the 3 coordinates X, Y, Z

    X
          X coordinate

    Y
          Y coordinate

    Z
          Z coordinate

    RET
          the newly allocate `<clutter-vertex>'. Use
          `clutter-vertex-free' to free the resources


     Since 1.0


 -- Function: clutter-vertex-init (self `<clutter-vertex>') (x `float')
          (y `float') (z `float')
     Initializes VERTEX with the given coordinates.

    VERTEX
          a `<clutter-vertex>'

    X
          X coordinate

    Y
          Y coordinate

    Z
          Z coordinate


     Since 1.10


 -- Function: clutter-vertex-equal (self `<clutter-vertex>')
          (vertex_b `<clutter-vertex>') =>  (ret `bool')
     Compares VERTEX-A and VERTEX-B for equality

    VERTEX-A
          a `<clutter-vertex>'

    VERTEX-B
          a `<clutter-vertex>'

    RET
          ``#t'' if the passed `<clutter-vertex>' are equal


     Since 1.0


 -- Function: clutter-geometry-union (self `<clutter-geometry>')
          (geometry_b `<clutter-geometry>')
          (result `<clutter-geometry>')
     Find the union of two rectangles represented as
     `<clutter-geometry>'.

    GEOMETRY-A
          a `<clutter-geometry>'

    GEOMETRY-B
          another `<clutter-geometry>'

    RESULT
          location to store the result.


     Since 1.4


 -- Function: clutter-geometry-intersects (self `<clutter-geometry>')
          (geometry1 `<clutter-geometry>') =>  (ret `bool')
     Determines if GEOMETRY0 and geometry1 intersect returning ``#t''
     if they do else ``#f''.

    GEOMETRY0
          The first geometry to test

    GEOMETRY1
          The second geometry to test

    RET
          ``#t'' of GEOMETRY0 and geometry1 intersect else ``#f''.


     Since 1.4


 -- Function: clutter-paint-volume-set-origin
          (self `<clutter-paint-volume>') (origin `<clutter-vertex>')
     Sets the origin of the paint volume.

     The origin is defined as the X, Y and Z coordinates of the top-left
     corner of an actor's paint volume, in actor coordinates.

     The default is origin is assumed at: (0, 0, 0)

    PV
          a `<clutter-paint-volume>'

    ORIGIN
          a `<clutter-vertex>'


     Since 1.6


 -- Function: clutter-paint-volume-get-origin
          (self `<clutter-paint-volume>') (vertex `<clutter-vertex>')
     Retrieves the origin of the `<clutter-paint-volume>'.

    PV
          a `<clutter-paint-volume>'

    VERTEX
          the return location for a `<clutter-vertex>'.


     Since 1.6


 -- Function: clutter-paint-volume-set-width
          (self `<clutter-paint-volume>') (width `float')
     Sets the width of the paint volume. The width is measured along
     the x axis in the actor coordinates that PV is associated with.

    PV
          a `<clutter-paint-volume>'

    WIDTH
          the width of the paint volume, in pixels


     Since 1.6


 -- Function: clutter-paint-volume-get-width
          (self `<clutter-paint-volume>') =>  (ret `float')
     Retrieves the width of the volume's, axis aligned, bounding box.

     In other words; this takes into account what actor's coordinate
     space PV belongs too and conceptually fits an axis aligned box
     around the volume. It returns the size of that bounding box as
     measured along the x-axis.

     If, for example, `clutter-actor-get-transformed-paint-volume' is
     used to transform a 2D child actor that is 100px wide, 100px high
     and 0px deep into container coordinates then the width might not
     simply be 100px if the child actor has a 3D rotation applied to it.

     Remember; after `clutter-actor-get-transformed-paint-volume' is
     used then a transformed child volume will be defined relative to
     the ancestor container actor and so a 2D child actor can have a 3D
     bounding volume.

     There are no accuracy guarantees for the reported width, except
     that it must always be >= to the true width. This is because
     actors may report simple, loose fitting paint-volumes for
     efficiency

    PV
          a `<clutter-paint-volume>'

    RET
          the width, in units of PV's local coordinate system.


     Since 1.6


 -- Function: clutter-paint-volume-set-height
          (self `<clutter-paint-volume>') (height `float')
     Sets the height of the paint volume. The height is measured along
     the y axis in the actor coordinates that PV is associated with.

    PV
          a `<clutter-paint-volume>'

    HEIGHT
          the height of the paint volume, in pixels


     Since 1.6


 -- Function: clutter-paint-volume-get-height
          (self `<clutter-paint-volume>') =>  (ret `float')
     Retrieves the height of the volume's, axis aligned, bounding box.

     In other words; this takes into account what actor's coordinate
     space PV belongs too and conceptually fits an axis aligned box
     around the volume. It returns the size of that bounding box as
     measured along the y-axis.

     If, for example, `clutter-actor-get-transformed-paint-volume' is
     used to transform a 2D child actor that is 100px wide, 100px high
     and 0px deep into container coordinates then the height might not
     simply be 100px if the child actor has a 3D rotation applied to it.

     Remember; after `clutter-actor-get-transformed-paint-volume' is
     used then a transformed child volume will be defined relative to
     the ancestor container actor and so a 2D child actor can have a 3D
     bounding volume.

     There are no accuracy guarantees for the reported height, except
     that it must always be >= to the true height. This is because
     actors may report simple, loose fitting paint-volumes for
     efficiency

    PV
          a `<clutter-paint-volume>'

    RET
          the height, in units of PV's local coordinate system.


     Since 1.6


 -- Function: clutter-paint-volume-set-depth
          (self `<clutter-paint-volume>') (depth `float')
     Sets the depth of the paint volume. The depth is measured along
     the z axis in the actor coordinates that PV is associated with.

    PV
          a `<clutter-paint-volume>'

    DEPTH
          the depth of the paint volume, in pixels


     Since 1.6


 -- Function: clutter-paint-volume-get-depth
          (self `<clutter-paint-volume>') =>  (ret `float')
     Retrieves the depth of the volume's, axis aligned, bounding box.

     In other words; this takes into account what actor's coordinate
     space PV belongs too and conceptually fits an axis aligned box
     around the volume. It returns the size of that bounding box as
     measured along the z-axis.

     If, for example, `clutter-actor-get-transformed-paint-volume' is
     used to transform a 2D child actor that is 100px wide, 100px high
     and 0px deep into container coordinates then the depth might not
     simply be 0px if the child actor has a 3D rotation applied to it.

     Remember; after `clutter-actor-get-transformed-paint-volume' is
     used then the transformed volume will be defined relative to the
     container actor and in container coordinates a 2D child actor can
     have a 3D bounding volume.

     There are no accuracy guarantees for the reported depth, except
     that it must always be >= to the true depth. This is because
     actors may report simple, loose fitting paint-volumes for
     efficiency.

    PV
          a `<clutter-paint-volume>'

    RET
          the depth, in units of PV's local coordinate system.


     Since 1.6


 -- Function: clutter-paint-volume-union
          (self `<clutter-paint-volume>')
          (another_pv `<clutter-paint-volume>')
     Updates the geometry of PV to encompass PV and ANOTHER-PV.

     There are no guarantees about how precisely the two volumes will
     be encompassed.

    PV
          The first `<clutter-paint-volume>' and destination for
          resulting union

    ANOTHER-PV
          A second `<clutter-paint-volume>' to union with PV


     Since 1.6


 -- Function: clutter-paint-volume-union-box
          (self `<clutter-paint-volume>') (box `<clutter-actor-box>')
     Unions the 2D region represented by BOX to a
     `<clutter-paint-volume>'.

     This function is similar to `clutter-paint-volume-union', but it is
     specific for 2D regions.

    PV
          a `<clutter-paint-volume>'

    BOX
          a `<clutter-actor-box>' to union to PV


     Since 1.10



File: guile-gnome-clutter.info,  Node: ClutterAlignConstraint,  Next: ClutterAnimatable,  Prev: ClutterActor,  Up: Top

5 ClutterAlignConstraint
************************

A constraint aligning the position of an actor

5.1 Overview
============

`<clutter-align-constraint>' is a `<clutter-constraint>' that aligns
the position of the `<clutter-actor>' to which it is applied to the
size of another `<clutter-actor>' using an alignment factor

   `<clutter-align-constraint>' is available since Clutter 1.4

5.2 Usage
=========

 -- Function: clutter-align-constraint-new (source `<clutter-actor>')
          (axis `<clutter-align-axis>') (factor `float') => 
          (ret `<clutter-constraint>')
     Creates a new constraint, aligning a `<clutter-actor>''s position
     with regards of the size of the actor to SOURCE, with the given
     alignment FACTOR

    SOURCE
          the `<clutter-actor>' to use as the source of the alignment,
          or ``#f''.

    AXIS
          the axis to be used to compute the alignment

    FACTOR
          the alignment factor, between 0.0 and 1.0

    RET
          the newly created `<clutter-align-constraint>'


     Since 1.4


 -- Function: clutter-align-constraint-set-source
          (self `<clutter-align-constraint>') (source `<clutter-actor>')
 -- Method: set-source
     Sets the source of the alignment constraint

    ALIGN
          a `<clutter-align-constraint>'

    SOURCE
          a `<clutter-actor>', or ``#f'' to unset the source.


     Since 1.4


 -- Function: clutter-align-constraint-get-source
          (self `<clutter-align-constraint>') => 
          (ret `<clutter-actor>')
 -- Method: get-source
     Retrieves the source of the alignment

    ALIGN
          a `<clutter-align-constraint>'

    RET
          the `<clutter-actor>' used as the source of the alignment.


     Since 1.4


 -- Function: clutter-align-constraint-set-factor
          (self `<clutter-align-constraint>') (factor `float')
 -- Method: set-factor
     Sets the alignment factor of the constraint

     The factor depends on the `<"align-axis">' property and it is a
     value between 0.0 (meaning left, when `<"align-axis">' is set to
     `CLUTTER_ALIGN_X_AXIS'; or meaning top, when `<"align-axis">' is
     set to `CLUTTER_ALIGN_Y_AXIS') and 1.0 (meaning right, when
     `<"align-axis">' is set to `CLUTTER_ALIGN_X_AXIS'; or meaning
     bottom, when `<"align-axis">' is set to `CLUTTER_ALIGN_Y_AXIS'). A
     value of 0.5 aligns in the middle in either cases

    ALIGN
          a `<clutter-align-constraint>'

    FACTOR
          the alignment factor, between 0.0 and 1.0


     Since 1.4


 -- Function: clutter-align-constraint-get-factor
          (self `<clutter-align-constraint>') =>  (ret `float')
 -- Method: get-factor
     Retrieves the factor set using
     `clutter-align-constraint-set-factor'

    ALIGN
          a `<clutter-align-constraint>'

    RET
          the alignment factor


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterAlpha,  Next: ClutterBackend,  Prev: Implicit Animations,  Up: Top

6 ClutterAlpha
**************

A class for calculating a value as a function of time

6.1 Overview
============

`<clutter-alpha>' is a class for calculating an floating point value
dependent only on the position of a `<clutter-timeline>'.

   (code "<\"progress-mode\">") " property of " (code
"<clutter-timeline>") ", or the\n" (code
"clutter-timeline-set-progress-func") " function instead of " (code
"<clutter-alpha>") ".\nThe " (code "<clutter-alpha>") " class will be
deprecated in the future, and will not\nbe available any more in the
next major version of Clutter.")

   A `<clutter-alpha>' binds a `<clutter-timeline>' to a progress
function which translates the time T into an adimensional factor alpha.
The factor can then be used to drive a `<clutter-behaviour>', which
will translate the alpha value into something meaningful for a
`<clutter-actor>'.

   You should provide a `<clutter-timeline>' and bind it to the
`<clutter-alpha>' instance using `clutter-alpha-set-timeline'.  You
should also set an "animation mode", either by using the
`<clutter-animation-mode>' values that Clutter itself provides or by
registering custom functions using `clutter-alpha-register-func'.

   Instead of a `<clutter-animation-mode>' you may provide a function
returning the alpha value depending on the progress of the timeline,
using `clutter-alpha-set-func' or `clutter-alpha-set-closure'.  The
alpha function will be executed each time a new frame in the
`<clutter-timeline>' is reached.

   Since the alpha function is controlled by the timeline instance, you
can pause, stop or resume the `<clutter-alpha>' from calling the alpha
function by using the appropriate functions of the `<clutter-timeline>'
object.

   `<clutter-alpha>' is used to "drive" a `<clutter-behaviour>'
instance, and it is internally used by the `<clutter-animation>' API.

   (The missing figure, easing-modes

6.2 ClutterAlpha custom properties for `<clutter-script>'
=========================================================

`<clutter-alpha>' defines a custom "function" property for
`<clutter-script>' which allows to reference a custom alpha function
available in the source code. Setting the "function" property is
equivalent to calling `clutter-alpha-set-func' with the specified
function name. No user data or `<g-destroy-notify>' is available to be
passed.

   The following JSON fragment defines a `<clutter-alpha>' using a
`<clutter-timeline>' with id "sine-timeline" and an alpha function
called `my-sine-alpha'. The defined `<clutter-alpha>' instance can be
reused in multiple `<clutter-behaviour>' definitions or for
`<clutter-animation>' definitions.


     {
       "id" : "sine-alpha",
       "timeline" : {
         "id" : "sine-timeline",
         "duration" : 500,
         "loop" : true
       },
       "function" : "my_sine_alpha"
     }

   For the way to define the `<"mode">' property inside a ClutterScript
fragment, see the corresponding section in `<clutter-animation>'.

6.3 Usage
=========

 -- Function: clutter-alpha-new =>  (ret `<clutter-alpha>')
     Creates a new `<clutter-alpha>' instance. You must set a function
     to compute the alpha value using `clutter-alpha-set-func' and bind
     a `<clutter-timeline>' object to the `<clutter-alpha>' instance
     using `clutter-alpha-set-timeline'.

     You should use the newly created `<clutter-alpha>' instance inside
     a `<clutter-behaviour>' object.

    RET
          the newly created empty `<clutter-alpha>' instance.


     Since 0.2


 -- Function: clutter-alpha-set-timeline (self `<clutter-alpha>')
          (timeline `<clutter-timeline>')
 -- Method: set-timeline
     Binds ALPHA to TIMELINE.

    ALPHA
          A `<clutter-alpha>'

    TIMELINE
          A `<clutter-timeline>'


     Since 0.2


 -- Function: clutter-alpha-get-timeline (self `<clutter-alpha>') => 
          (ret `<clutter-timeline>')
 -- Method: get-timeline
     Gets the `<clutter-timeline>' bound to ALPHA.

    ALPHA
          A `<clutter-alpha>'

    RET
          a `<clutter-timeline>' instance.


     Since 0.2


 -- Function: clutter-alpha-set-mode (self `<clutter-alpha>')
          (mode `<clutter-animation-mode>')
 -- Method: set-mode
     Sets the progress function of ALPHA using the symbolic value of
     MODE, as taken by the `<clutter-animation-mode>' enumeration or
     using the value returned by `clutter-alpha-register-func'.

    ALPHA
          a `<clutter-alpha>'

    MODE
          a `<clutter-animation-mode>'


     Since 1.0


 -- Function: clutter-alpha-get-mode (self `<clutter-alpha>') => 
          (ret `<clutter-animation-mode>')
 -- Method: get-mode
     Retrieves the `<clutter-animation-mode>' used by ALPHA.

    ALPHA
          a `<clutter-alpha>'

    RET
          the animation mode


     Since 1.0


 -- Function: clutter-alpha-get-alpha (self `<clutter-alpha>') => 
          (ret `double')
 -- Method: get-alpha
     Query the current alpha value.

    ALPHA
          A `<clutter-alpha>'

    RET
          The current alpha value for the alpha


     Since 0.2


 -- Function: clutter-alpha-set-closure (self `<clutter-alpha>')
          (closure `<gclosure>')
 -- Method: set-closure
     Sets the `<gclosure>' used to compute the alpha value at each frame
     of the `<clutter-timeline>' bound to ALPHA.

    ALPHA
          A `<clutter-alpha>'

    CLOSURE
          A `<gclosure>'


     Since 0.8


 -- Function: clutter-alpha-register-closure (closure `<gclosure>') => 
          (ret `unsigned-long')
     `<gclosure>' variant of `clutter-alpha-register-func'.

     Registers a global alpha function and returns its logical id to be
     used by `clutter-alpha-set-mode' or by `<clutter-animation>'.

     The logical id is always greater than `CLUTTER_ANIMATION_LAST'.

     Rename to: clutter_alpha_register_func

    CLOSURE
          a `<gclosure>'

    RET
          the logical id of the alpha function


     Since 1.0



File: guile-gnome-clutter.info,  Node: ClutterAnimatable,  Next: ClutterAnimator,  Prev: ClutterAlignConstraint,  Up: Top

7 ClutterAnimatable
*******************

Interface for animatable classes

7.1 Overview
============

`<clutter-animatable>' is an interface that allows a `<gobject>' class
to control how a `<clutter-animation>' will animate a property.

   Each `<clutter-animatable>' should implement the `animate-property'
virtual function of the interface to compute the animation state
between two values of an interval depending on a progress factor,
expressed as a floating point value.

   If a `<clutter-animatable>' is animated by a `<clutter-animation>'
instance, the `<clutter-animation>' will call
`clutter-animatable-animate-property' passing the name of the currently
animated property; the initial and final values of the animation
interval; the progress factor. The `<clutter-animatable>'
implementation should return the computed value for the animated
property.

   `<clutter-animatable>' is available since Clutter 1.0

7.2 Usage
=========

 -- Function: clutter-animatable-find-property
          (self `<clutter-animatable>') (property_name `mchars') => 
          (ret `<gparam>')
 -- Method: find-property
     Finds the `<gparam>' for PROPERTY-NAME

    ANIMATABLE
          a `<clutter-animatable>'

    PROPERTY-NAME
          the name of the animatable property to find

    RET
          The `<gparam>' for the given property or ``#f''.


     Since 1.4


 -- Function: clutter-animatable-set-final-state
          (self `<clutter-animatable>') (property_name `mchars')
          (value `<gvalue>')
 -- Method: set-final-state
     Sets the current state of PROPERTY-NAME to VALUE

    ANIMATABLE
          a `<clutter-animatable>'

    PROPERTY-NAME
          the name of the animatable property to set

    VALUE
          the value of the animatable property to set


     Since 1.4



File: guile-gnome-clutter.info,  Node: Implicit Animations,  Next: ClutterAlpha,  Prev: ClutterAnimator,  Up: Top

8 Implicit Animations
*********************

Simple implicit animations

8.1 Overview
============

`<clutter-animation>' is an object providing simple, implicit
animations for `<gobject>'s.

   `<clutter-animation>' instances will bind one or more `<gobject>'
properties belonging to a `<gobject>' to a `<clutter-interval>', and
will then use a `<clutter-alpha>' to interpolate the property between
the initial and final values of the interval.

   The duration of the animation is set using
`clutter-animation-set-duration'. The easing mode of the animation is
set using `clutter-animation-set-mode'.

   If you want to control the animation you should retrieve the
`<clutter-timeline>' using `clutter-animation-get-timeline' and then
use `<clutter-timeline>' functions like `clutter-timeline-start',
`clutter-timeline-pause' or `clutter-timeline-stop'.

   A `<clutter-animation>' will emit the `<"completed">' signal when
the `<clutter-timeline>' used by the animation is completed; unlike
`<clutter-timeline>', though, the `<"completed">' will not be emitted
if `<"loop">' is set to ``#t'' - that is, a looping animation never
completes.

   If your animation depends on user control you can force its
completion using `clutter-animation-completed'.

   If the `<gobject>' instance bound to a `<clutter-animation>'
implements the `<clutter-animatable>' interface it is possible for that
instance to control the way the initial and final states are
interpolated.

   `<clutter-animation>'s are distinguished from `<clutter-behaviour>'s
because the former can only control `<gobject>' properties of a single
`<gobject>' instance, while the latter can control multiple properties
using accessor functions inside the `<clutter-behaviour>'`alpha-notify'
virtual function, and can control multiple `<clutter-actor>'s as well.

   For convenience, it is possible to use the `clutter-actor-animate'
function call which will take care of setting up and tearing down a
`<clutter-animation>' instance and animate an actor between its current
state and the specified final state.

8.2 Defining ClutterAnimationMode inside ClutterScript
======================================================

When defining a `<clutter-animation>' inside a ClutterScript file or
string the `<"mode">' can be defined either using the
`<clutter-animation-mode>' enumeration values through their "nick" (the
short string used inside `<g-enum-value>'), their numeric id, or using
the following strings:

EASEINCUBIC, EASEOUTCUBIC, EASEINOUTCUBIC

EASEINQUART, EASEOUTQUART, EASEINOUTQUART

EASEINQUINT, EASEOUTQUINT, EASEINOUTQUINT

EASEINSINE, EASEOUTSINE, EASEINOUTSINE

EASEINEXPO, EASEOUTEXPO, EASEINOUTEXPO

EASEINCIRC, EASEOUTCIRC, EASEINOUTCIRC

EASEINELASTIC, EASEOUTELASTIC, EASEINOUTELASTIC

EASEINBACK, EASEOUTBACK, EASEINOUTBACK

EASEINBOUNCE, EASEOUTBOUNCE, EASEINOUTBOUNCE

   Corresponding to the quadratic easing modes

   Corresponding to the cubic easing modes

   Corresponding to the quartic easing modes

   Corresponding to the quintic easing modes

   Corresponding to the sine easing modes

   Corresponding to the exponential easing modes

   Corresponding to the circular easing modes

   Corresponding to the overshooting elastic easing modes

   Corresponding to the overshooting cubic easing modes

   Corresponding to the bouncing easing modes


   `<clutter-animation>' is available since Clutter 1.0

8.3 Usage
=========

 -- Function: clutter-animation-new =>  (ret `<clutter-animation>')
     Creates a new `<clutter-animation>' instance. You should set the
     `<gobject>' to be animated using `clutter-animation-set-object',
     set the duration with `clutter-animation-set-duration' and the
     easing mode using `clutter-animation-set-mode'.

     Use `clutter-animation-bind' or `clutter-animation-bind-interval'
     to define the properties to be animated. The interval and the
     animated properties can be updated at runtime.

     The `clutter-actor-animate' and relative family of functions
     provide an easy way to animate a `<clutter-actor>' and
     automatically manage the lifetime of a `<clutter-animation>'
     instance, so you should consider using those functions instead of
     manually creating an animation.

    RET
          the newly created `<clutter-animation>'. Use `g-object-unref'
          to release the associated resources


     Since 1.0


 -- Function: clutter-animation-set-object (self `<clutter-animation>')
          (object `<gobject>')
 -- Method: set-object
     Attaches ANIMATION to OBJECT. The `<clutter-animation>' will take
     a reference on OBJECT.

    ANIMATION
          a `<clutter-animation>'

    OBJECT
          a `<gobject>'


     Since 1.0


 -- Function: clutter-animation-get-object (self `<clutter-animation>')
          =>  (ret `<gobject>')
 -- Method: get-object
     Retrieves the `<gobject>' attached to ANIMATION.

    ANIMATION
          a `<clutter-animation>'

    RET
          a `<gobject>'.


     Since 1.0


 -- Function: clutter-animation-set-mode (self `<clutter-animation>')
          (mode `unsigned-long')
 -- Method: set-mode
     Sets the animation MODE of ANIMATION. The animation MODE is a
     logical id, either coming from the `<clutter-animation-mode>'
     enumeration or the return value of `clutter-alpha-register-func'.

     This function will also set `<"alpha">' if needed.

    ANIMATION
          a `<clutter-animation>'

    MODE
          an animation mode logical id


     Since 1.0


 -- Function: clutter-animation-get-mode (self `<clutter-animation>')
          =>  (ret `unsigned-long')
 -- Method: get-mode
     Retrieves the animation mode of ANIMATION, as set by
     `clutter-animation-set-mode'.

    ANIMATION
          a `<clutter-animation>'

    RET
          the mode for the animation


     Since 1.0


 -- Function: clutter-animation-set-duration
          (self `<clutter-animation>') (msecs `unsigned-int')
 -- Method: set-duration
     Sets the duration of ANIMATION in milliseconds.

     This function will set `<"alpha">' and `<"timeline">' if needed.

    ANIMATION
          a `<clutter-animation>'

    MSECS
          the duration in milliseconds


     Since 1.0


 -- Function: clutter-animation-get-duration
          (self `<clutter-animation>') =>  (ret `unsigned-int')
 -- Method: get-duration
     Retrieves the duration of ANIMATION, in milliseconds.

    ANIMATION
          a `<clutter-animation>'

    RET
          the duration of the animation


     Since 1.0


 -- Function: clutter-animation-set-loop (self `<clutter-animation>')
          (loop `bool')
 -- Method: set-loop
     Sets whether ANIMATION should loop over itself once finished.

     A looping `<clutter-animation>' will not emit the `<"completed">'
     signal when finished.

     This function will set `<"alpha">' and `<"timeline">' if needed.

    ANIMATION
          a `<clutter-animation>'

    LOOP
          ``#t'' if the animation should loop


     Since 1.0


 -- Function: clutter-animation-get-loop (self `<clutter-animation>')
          =>  (ret `bool')
 -- Method: get-loop
     Retrieves whether ANIMATION is looping.

    ANIMATION
          a `<clutter-animation>'

    RET
          ``#t'' if the animation is looping


     Since 1.0


 -- Function: clutter-animation-set-timeline
          (self `<clutter-animation>') (timeline `<clutter-timeline>')
 -- Method: set-timeline
     Sets the `<clutter-timeline>' used by ANIMATION.

     This function will take a reference on the passed TIMELINE.

    ANIMATION
          a `<clutter-animation>'

    TIMELINE
          a `<clutter-timeline>', or ``#f'' to unset the current
          `<clutter-timeline>'.


     Since 1.0


 -- Function: clutter-animation-get-timeline
          (self `<clutter-animation>') =>  (ret `<clutter-timeline>')
 -- Method: get-timeline
     Retrieves the `<clutter-timeline>' used by ANIMATION

    ANIMATION
          a `<clutter-animation>'

    RET
          the timeline used by the animation.


     Since 1.0


 -- Function: clutter-animation-completed (self `<clutter-animation>')
 -- Method: completed
     Emits the ::completed signal on ANIMATION

     When using this function with a `<clutter-animation>' created by
     the `clutter-actor-animate' family of functions, ANIMATION will be
     unreferenced and it will not be valid anymore, unless
     `g-object-ref' was called before calling this function or unless a
     reference was taken inside a handler for the `<"completed">' signal

    ANIMATION
          a `<clutter-animation>'


     Since 1.0


 -- Function: clutter-animation-bind (self `<clutter-animation>')
          (property_name `mchars') (final `<gvalue>') => 
          (ret `<clutter-animation>')
 -- Method: bind
     Adds a single property with name PROPERTY-NAME to the animation
     ANIMATION. For more information about animations, see
     `clutter-actor-animate'.

     This method returns the animation primarily to make chained calls
     convenient in language bindings.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          the property to control

    FINAL
          The final value of the property

    RET
          The animation itself.


     Since 1.0


 -- Function: clutter-animation-bind-interval
          (self `<clutter-animation>') (property_name `mchars')
          (interval `<clutter-interval>') => 
          (ret `<clutter-animation>')
 -- Method: bind-interval
     Binds INTERVAL to the PROPERTY-NAME of the `<gobject>' attached to
     ANIMATION. The `<clutter-animation>' will take ownership of the
     passed `<clutter-interval>'. For more information about
     animations, see `clutter-actor-animate'.

     If you need to update the interval instance use
     `clutter-animation-update-interval' instead.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          the property to control

    INTERVAL
          a `<clutter-interval>'.

    RET
          The animation itself.


     Since 1.0


 -- Function: clutter-animation-update (self `<clutter-animation>')
          (property_name `mchars') (final `<gvalue>') => 
          (ret `<clutter-animation>')
 -- Method: update
     Updates the FINAL value of the interval for PROPERTY-NAME

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          name of the property

    FINAL
          The final value of the property

    RET
          The animation itself.


     Since 1.0


 -- Function: clutter-animation-update-interval
          (self `<clutter-animation>') (property_name `mchars')
          (interval `<clutter-interval>')
 -- Method: update-interval
     Changes the INTERVAL for PROPERTY-NAME. The `<clutter-animation>'
     will take ownership of the passed `<clutter-interval>'.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          name of the property

    INTERVAL
          a `<clutter-interval>'


     Since 1.0


 -- Function: clutter-animation-has-property
          (self `<clutter-animation>') (property_name `mchars') => 
          (ret `bool')
 -- Method: has-property
     Checks whether ANIMATION is controlling PROPERTY-NAME.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          name of the property

    RET
          ``#t'' if the property is animated by the
          `<clutter-animation>', ``#f'' otherwise


     Since 1.0


 -- Function: clutter-animation-unbind-property
          (self `<clutter-animation>') (property_name `mchars')
 -- Method: unbind-property
     Removes PROPERTY-NAME from the list of animated properties.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          name of the property


     Since 1.0


 -- Function: clutter-animation-get-interval
          (self `<clutter-animation>') (property_name `mchars') => 
          (ret `<clutter-interval>')
 -- Method: get-interval
     Retrieves the `<clutter-interval>' associated to PROPERTY-NAME
     inside ANIMATION.

    ANIMATION
          a `<clutter-animation>'

    PROPERTY-NAME
          name of the property

    RET
          a `<clutter-interval>' or ``#f'' if no property with the same
          name was found. The returned interval is owned by the
          `<clutter-animation>' and should not be unreferenced.


     Since 1.0


 -- Function: clutter-actor-get-animation (self `<clutter-actor>') => 
          (ret `<clutter-animation>')
 -- Method: get-animation
     Retrieves the `<clutter-animation>' used by ACTOR, if
     `clutter-actor-animate' has been called on ACTOR.

    ACTOR
          a `<clutter-actor>'

    RET
          a `<clutter-animation>', or ``#f''.


     Since 1.0


 -- Function: clutter-actor-detach-animation (self `<clutter-actor>')
 -- Method: detach-animation
     Detaches the `<clutter-animation>' used by ACTOR, if
     `clutter-actor-animate' has been called on ACTOR.

     Once the animation has been detached, it loses a reference. If it
     was the only reference then the `<clutter-animation>' becomes
     invalid.

     The `<"completed">' signal will not be emitted.

    ACTOR
          a `<clutter-actor>'


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterAnimator,  Next: Implicit Animations,  Prev: ClutterAnimatable,  Up: Top

9 ClutterAnimator
*****************

Multi-actor tweener

9.1 Overview
============

`<clutter-animator>' is an object providing declarative animations for
`<gobject>' properties belonging to one or more `<gobject>'s to
`<clutter-intervals>'.

   `<clutter-animator>' is used to build and describe complex
animations in terms of "key frames". `<clutter-animator>' is meant to
be used through the `<clutter-script>' definition format, but it comes
with a convenience C API.

9.2 Key Frames
==============

Every animation handled by a `<clutter-animator>' can be described in
terms of "key frames". For each `<gobject>' property there can be
multiple key frames, each one defined by the end value for the property
to be computed starting from the current value to a specific point in
time, using a given easing mode.

   The point in time is defined using a value representing the progress
in the normalized interval of [ 0, 1 ]. This maps the value returned by
`clutter-timeline-get-duration'.

   In the image above the duration of the animation is represented by
the blue line. Each key frame is the white dot, along with its
progress. The red line represents the computed function of time given
the easing mode.

9.3 ClutterAnimator description for `<clutter-script>'
======================================================

`<clutter-animator>' defines a custom "properties" property which
allows describing the key frames for objects.

   The "properties" property has the following syntax:


      {
        "properties" : [
          {
            "object" : &lt;id of an object>,
            "name" : &lt;name of the property>,
            "ease-in" : &lt;boolean>,
            "interpolation" : &lt;#ClutterInterpolation value>,
            "keys" : [
              [ &lt;progress>, &lt;easing mode>, &lt;final value> ]
            ]
        ]
      }

   The following JSON fragment defines a `<clutter-animator>' with the
duration of 1 second and operating on the x and y properties of a
`<clutter-actor>' named "rect-01", with two frames for each property.
The first frame will linearly move the actor from its current position
to the 100, 100 position in 20 percent of the duration of the
animation; the second will using a cubic easing to move the actor to the
200, 200 coordinates.


      {
        "type" : "ClutterAnimator",
        "duration" : 1000,
        "properties" : [
          {
            "object" : "rect-01",
            "name" : "x",
            "ease-in" : true,
            "keys" : [
              [ 0.2, "linear",       100.0 ],
              [ 1.0, "easeOutCubic", 200.0 ]
            ]
          },
          {
            "object" : "rect-01",
            "name" : "y",
            "ease-in" : true,
            "keys" : [
              [ 0.2, "linear",       100.0 ],
              [ 1.0, "easeOutCubic", 200.0 ]
            ]
          }
        ]
      }

   `<clutter-animator>' is available since Clutter 1.2

9.4 Usage
=========

 -- Function: clutter-animator-new =>  (ret `<clutter-animator>')
     Creates a new `<clutter-animator>' instance

    RET
          a new `<clutter-animator>'.


     Since 1.2


 -- Function: clutter-animator-set-key (self `<clutter-animator>')
          (object `<gobject>') (property_name `mchars')
          (mode `unsigned-int') (progress `double') (value `<gvalue>')
          =>  (ret `<clutter-animator>')
 -- Method: set-key
     Sets a single key in the `<clutter-animator>' for the
     PROPERTY-NAME of OBJECT at PROGRESS.

     See also: `clutter-animator-set'

    ANIMATOR
          a `<clutter-animator>'

    OBJECT
          a `<gobject>'

    PROPERTY-NAME
          the property to specify a key for

    MODE
          the id of the alpha function to use

    PROGRESS
          the normalized range at which stage of the animation this
          value applies

    VALUE
          the value property_name should have at progress.

    RET
          The animator instance.


     Since 1.2


 -- Function: clutter-animator-remove-key (self `<clutter-animator>')
          (object `<gobject>') (property_name `mchars')
          (progress `double')
 -- Method: remove-key
     Removes all keys matching the conditions specificed in the
     arguments.

    ANIMATOR
          a `<clutter-animator>'

    OBJECT
          a `<gobject>' to search for, or ``#f'' for all.

    PROPERTY-NAME
          a specific property name to query for, or ``#f'' for all.

    PROGRESS
          a specific progress to search for or a negative value for all


     Since 1.2


 -- Function: clutter-animator-get-keys (self `<clutter-animator>')
          (object `<gobject>') (property_name `mchars')
          (progress `double') =>  (ret `glist-of')
 -- Method: get-keys
     Returns a list of pointers to opaque structures with accessor
     functions that describe the keys added to an animator.

    ANIMATOR
          a `<clutter-animator>' instance

    OBJECT
          a `<gobject>' to search for, or ``#f'' for all objects.

    PROPERTY-NAME
          a specific property name to query for, or ``#f'' for all
          properties.

    PROGRESS
          a specific progress to search for, or a negative value for all
          progresses

    RET
          a list of `<clutter-animator-key>'s; the contents of the list
          are owned by the `<clutter-animator>', but you should free
          the returned list when done, using `g-list-free'.


     Since 1.2


 -- Function: clutter-animator-start (self `<clutter-animator>') => 
          (ret `<clutter-timeline>')
 -- Method: start
     Start the ClutterAnimator, this is a thin wrapper that rewinds and
     starts the animators current timeline.

    ANIMATOR
          a `<clutter-animator>'

    RET
          the `<clutter-timeline>' that drives the animator. The
          returned timeline is owned by the `<clutter-animator>' and it
          should not be unreferenced.


     Since 1.2


 -- Function: clutter-animator-compute-value
          (self `<clutter-animator>') (object `<gobject>')
          (property_name `mchars') (progress `double')
          (value `<gvalue>') =>  (ret `bool')
 -- Method: compute-value
     Compute the value for a managed property at a given progress.

     If the property is an ease-in property, the current value of the
     property on the object will be used as the starting point for
     computation.

    ANIMATOR
          a `<clutter-animator>'

    OBJECT
          a `<gobject>'

    PROPERTY-NAME
          the name of the property on object to check

    PROGRESS
          a value between 0.0 and 1.0

    VALUE
          an initialized value to store the computed result

    RET
          ``#t'' if the computation yields has a value, otherwise (when
          an error occurs or the progress is before any of the keys)
          ``#f'' is returned and the `<gvalue>' is left untouched


     Since 1.2


 -- Function: clutter-animator-set-timeline (self `<clutter-animator>')
          (timeline `<clutter-timeline>')
 -- Method: set-timeline
     Sets an external timeline that will be used for driving the
     animation

    ANIMATOR
          a `<clutter-animator>'

    TIMELINE
          a `<clutter-timeline>'


     Since 1.2


 -- Function: clutter-animator-get-timeline (self `<clutter-animator>')
          =>  (ret `<clutter-timeline>')
 -- Method: get-timeline
     Get the timeline hooked up for driving the `<clutter-animator>'

    ANIMATOR
          a `<clutter-animator>'

    RET
          the `<clutter-timeline>' that drives the animator.


     Since 1.2


 -- Function: clutter-animator-set-duration (self `<clutter-animator>')
          (duration `unsigned-int')
 -- Method: set-duration
     Runs the timeline of the `<clutter-animator>' with a duration in
     msecs as specified.

    ANIMATOR
          a `<clutter-animator>'

    DURATION
          milliseconds a run of the animator should last.


     Since 1.2


 -- Function: clutter-animator-get-duration (self `<clutter-animator>')
          =>  (ret `unsigned-int')
 -- Method: get-duration
     Retrieves the current duration of an animator

    ANIMATOR
          a `<clutter-animator>'

    RET
          the duration of the animation, in milliseconds


     Since 1.2


 -- Function: clutter-animator-key-get-object
          (self `<clutter-animator-key>') =>  (ret `<gobject>')
     Retrieves the object a key applies to.

    KEY
          a `<clutter-animator-key>'

    RET
          the object an animator_key exist for.


     Since 1.2


 -- Function: clutter-animator-key-get-mode
          (self `<clutter-animator-key>') =>  (ret `unsigned-long')
     Retrieves the mode of a `<clutter-animator>' key, for the first key
     of a property for an object this represents the whether the
     animation is open ended and or curved for the remainding keys for
     the property it represents the easing mode.

    KEY
          a `<clutter-animator-key>'

    RET
          the mode of a `<clutter-animator-key>'


     Since 1.2


 -- Function: clutter-animator-key-get-progress
          (self `<clutter-animator-key>') =>  (ret `double')
     Retrieves the progress of an clutter_animator_key

    KEY
          a `<clutter-animator-key>'

    RET
          the progress defined for a `<clutter-animator>' key.


     Since 1.2


 -- Function: clutter-animator-key-get-value
          (self `<clutter-animator-key>') (value `<gvalue>') => 
          (ret `bool')
     Retrieves a copy of the value for a `<clutter-animator-key>'.

     The passed in `<gvalue>' needs to be already initialized for the
     value type of the key or to a type that allow transformation from
     the value type of the key.

     Use `g-value-unset' when done.

    KEY
          a `<clutter-animator-key>'

    VALUE
          a `<gvalue>' initialized with the correct type for the
          animator key

    RET
          ``#t'' if the passed `<gvalue>' was successfully set, and
          ``#f'' otherwise


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterBackend,  Next: ClutterBindConstraint,  Prev: ClutterAlpha,  Up: Top

10 ClutterBackend
*****************

Backend abstraction

10.1 Overview
=============

Clutter can be compiled against different backends. Each backend has to
implement a set of functions, in order to be used by Clutter.

   `<clutter-backend>' is the base class abstracting the various
implementation; it provides a basic API to query the backend for generic
information and settings.

   `<clutter-backend>' is available since Clutter 0.4

10.2 Usage
==========

 -- Function: clutter-get-default-backend =>  (ret `<clutter-backend>')
     Retrieves the default `<clutter-backend>' used by Clutter. The
     `<clutter-backend>' holds backend-specific configuration options.

    RET
          the default backend. You should not ref or unref the returned
          object.  Applications should rarely need to use this.


     Since 0.4


 -- Function: clutter-backend-get-resolution (self `<clutter-backend>')
          =>  (ret `double')
 -- Method: get-resolution
     Gets the resolution for font handling on the screen.

     The resolution is a scale factor between points specified in a
     `<pango-font-description>' and cairo units. The default value is
     96.0, meaning that a 10 point font will be 13 units high (10 * 96.
     / 72.  = 13.3).

     Clutter will set the resolution using the current backend when
     initializing; the resolution is also stored in the `<"font-dpi">'
     property.

    BACKEND
          a `<clutter-backend>'

    RET
          the current resolution, or -1 if no resolution has been set.


     Since 0.4


 -- Function: clutter-backend-set-font-options
          (self `<clutter-backend>') (options `cairo-font-options-t')
 -- Method: set-font-options
     Sets the new font options for BACKEND. The `<clutter-backend>'
     will copy the `<cairo-font-options-t>'.

     If OPTIONS is ``#f'', the first following call to
     `clutter-backend-get-font-options' will return the default font
     options for BACKEND.

     This function is intended for actors creating a Pango layout using
     the PangoCairo API.

    BACKEND
          a `<clutter-backend>'

    OPTIONS
          Cairo font options for the backend, or ``#f''


     Since 0.8


 -- Function: clutter-check-windowing-backend (backend_type `mchars')
          =>  (ret `bool')
     Checks the run-time name of the Clutter windowing system backend,
     using the symbolic macros like `CLUTTER_WINDOWING_WIN32' or
     `CLUTTER_WINDOWING_X11'.

     This function should be used in conjuction with the compile-time
     macros inside applications and libraries that are using the
     platform-specific windowing system API, to ensure that they are
     running on the correct windowing system; for instance:


          &#x0023;ifdef CLUTTER_WINDOWING_X11
            if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11))
              {
                /&#x002A; it is safe to use the clutter_x11_* API &#x002A;/
              }
            else
          &#x0023;endif
          &#x0023;ifdef CLUTTER_WINDOWING_WIN32
            if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32))
              {
                /&#x002A; it is safe to use the clutter_win32_* API &#x002A;/
              }
            else
          &#x0023;endif
              g_error ("Unknown Clutter backend.");

    BACKEND-TYPE
          the name of the backend to check

    RET
          ``#t'' if the current Clutter windowing system backend is the
          one checked, and ``#f'' otherwise


     Since 1.10



File: guile-gnome-clutter.info,  Node: ClutterBinLayout,  Next: ClutterBlurEffect,  Prev: ClutterBindConstraint,  Up: Top

11 ClutterBinLayout
*******************

A simple layout manager

11.1 Overview
=============

`<clutter-bin-layout>' is a layout manager which implements the
following policy:

   * the preferred size is the maximum preferred size between all the
     children of the container using the layout;

   * each child is allocated in "layers", on on top of the other;

   * for each layer there are horizontal and vertical alignment
     policies.


   (The missing figure, bin-layout

   The image shows a `<clutter-bin-layout>' with three layers: a
background `<clutter-cairo-texture>', set to fill on both the X and Y
axis; a `<clutter-texture>', set to center on both the X and Y axis;
and a `<clutter-rectangle>', set to `CLUTTER_BIN_ALIGNMENT_END' on both
the X and Y axis.

   The following code shows how to build a composite actor with a
texture and a background, and add controls overlayed on top. The
background is set to fill the whole allocation, whilst the texture is
centered; there is a control in the top right corner and a label in the
bottom, filling out the whole allocated width.


      ClutterLayoutManager *manager;
      ClutterActor *box;

      /&#x002A; create the layout first &#x002A;/
      layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_CENTER,
                                       CLUTTER_BIN_ALIGNMENT_CENTER);
      box = clutter_box_new (layout); /&#x002A; then the container &#x002A;/

      /&#x002A; we can use the layout object to add actors &#x002A;/
      clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), background,
                              CLUTTER_BIN_ALIGNMENT_FILL,
                              CLUTTER_BIN_ALIGNMENT_FILL);
      clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), icon,
                              CLUTTER_BIN_ALIGNMENT_CENTER,
                              CLUTTER_BIN_ALIGNMENT_CENTER);

      /&#x002A; align to the bottom left &#x002A;/
      clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), label,
                              CLUTTER_BIN_ALIGNMENT_START,
                              CLUTTER_BIN_ALIGNMENT_END);
      /&#x002A; align to the top right &#x002A;/
      clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), button,
                              CLUTTER_BIN_ALIGNMENT_END,
                              CLUTTER_BIN_ALIGNMENT_START);

   `<clutter-bin-layout>' is available since Clutter 1.2

11.2 Usage
==========

 -- Function: clutter-bin-layout-new
          (x_align `<clutter-bin-alignment>')
          (y_align `<clutter-bin-alignment>') => 
          (ret `<clutter-layout-manager>')
     Creates a new `<clutter-bin-layout>' layout manager

    X-ALIGN
          the default alignment policy to be used on the horizontal axis

    Y-ALIGN
          the default alignment policy to be used on the vertical axis

    RET
          the newly created layout manager


     Since 1.2


 -- Function: clutter-bin-layout-set-alignment
          (self `<clutter-bin-layout>') (child `<clutter-actor>')
          (x_align `<clutter-bin-alignment>')
          (y_align `<clutter-bin-alignment>')
 -- Method: set-alignment
     Sets the horizontal and vertical alignment policies to be applied
     to a CHILD of SELF

     If CHILD is ``#f'' then the X-ALIGN and Y-ALIGN values will be set
     as the default alignment policies

    SELF
          a `<clutter-bin-layout>'

    CHILD
          a child of CONTAINER.

    X-ALIGN
          the horizontal alignment policy to be used for the CHILD
          inside CONTAINER

    Y-ALIGN
          the vertical aligment policy to be used on the CHILD inside
          CONTAINER


     Since 1.2


 -- Function: clutter-bin-layout-get-alignment
          (self `<clutter-bin-layout>') (child `<clutter-actor>') => 
          (x_align `<clutter-bin-alignment>')
          (y_align `<clutter-bin-alignment>')
 -- Method: get-alignment
     Retrieves the horizontal and vertical alignment policies for a
     child of SELF

     If CHILD is ``#f'' the default alignment policies will be returned
     instead

    SELF
          a `<clutter-bin-layout>'

    CHILD
          a child of CONTAINER.

    X-ALIGN
          return location for the horizontal alignment policy.

    Y-ALIGN
          return location for the vertical alignment policy.


     Since 1.2


 -- Function: clutter-bin-layout-add (self `<clutter-bin-layout>')
          (child `<clutter-actor>') (x_align `<clutter-bin-alignment>')
          (y_align `<clutter-bin-alignment>')
 -- Method: add
     Adds a `<clutter-actor>' to the container using SELF and sets the
     alignment policies for it

     This function is equivalent to `clutter-container-add-actor' and
     `clutter-layout-manager-child-set-property' but it does not require
     a pointer to the `<clutter-container>' associated to the
     `<clutter-bin-layout>'

    SELF
          a `<clutter-bin-layout>'

    CHILD
          a `<clutter-actor>'

    X-ALIGN
          horizontal alignment policy for CHILD

    Y-ALIGN
          vertical alignment policy for CHILD


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterBindConstraint,  Next: ClutterBinLayout,  Prev: ClutterBackend,  Up: Top

12 ClutterBindConstraint
************************

A constraint binding the position or size of an actor

12.1 Overview
=============

`<clutter-bind-constraint>' is a `<clutter-constraint>' that binds the
position or the size of the `<clutter-actor>' to which it is applied to
the the position or the size of another `<clutter-actor>', or "source".

   An offset can be applied to the constraint, to avoid overlapping. The
offset can also be animated. For instance, the following code will set
up three actors to be bound to the same origin:


     /&#x002A; source &#x002A;/
     rect[0] = clutter_rectangle_new_with_color (&red_color);
     clutter_actor_set_position (rect[0], x_pos, y_pos);
     clutter_actor_set_size (rect[0], 100, 100);

     /&#x002A; second rectangle &#x002A;/
     rect[1] = clutter_rectangle_new_with_color (&green_color);
     clutter_actor_set_size (rect[1], 100, 100);
     clutter_actor_set_opacity (rect[1], 0);

     constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_X, 0.0);
     clutter_actor_add_constraint_with_name (rect[1], "green-x", constraint);
     constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0);
     clutter_actor_add_constraint_with_name (rect[1], "green-y", constraint);

     /&#x002A; third rectangle &#x002A;/
     rect[2] = clutter_rectangle_new_with_color (&blue_color);
     clutter_actor_set_size (rect[2], 100, 100);
     clutter_actor_set_opacity (rect[2], 0);

     constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_X, 0.0);
     clutter_actor_add_constraint_with_name (rect[2], "blue-x", constraint);
     constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0);
     clutter_actor_add_constraint_with_name (rect[2], "blue-y", constraint);

   The following code animates the second and third rectangles to
"expand" them horizontally from underneath the first rectangle:


     clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250,
                            "@constraints.green-x.offset", 100.0,
                            "opacity", 255,
                            NULL);
     clutter_actor_animate (rect[2], CLUTTER_EASE_OUT_CUBIC, 250,
                            "@constraints.blue-x.offset", 200.0,
                            "opacity", 255,
                            NULL);


   The example above creates eight rectangles and binds them to a
rectangle positioned in the center of the stage; when the user presses
the center rectangle, the `<"offset">' property is animated through the
`clutter-actor-animate' function to lay out the eight rectangles around
the center one. Pressing one of the outer rectangles will animate the
offset back to 0.

   `<clutter-bind-constraint>' is available since Clutter 1.4

12.2 Usage
==========

 -- Function: clutter-bind-constraint-new (source `<clutter-actor>')
          (coordinate `<clutter-bind-coordinate>') (offset `float') => 
          (ret `<clutter-constraint>')
     Creates a new constraint, binding a `<clutter-actor>''s position to
     the given COORDINATE of the position of SOURCE

    SOURCE
          the `<clutter-actor>' to use as the source of the binding, or
          ``#f''.

    COORDINATE
          the coordinate to bind

    OFFSET
          the offset to apply to the binding, in pixels

    RET
          the newly created `<clutter-bind-constraint>'


     Since 1.4


 -- Function: clutter-bind-constraint-set-source
          (self `<clutter-bind-constraint>') (source `<clutter-actor>')
 -- Method: set-source
     Sets the source `<clutter-actor>' for the constraint

    CONSTRAINT
          a `<clutter-bind-constraint>'

    SOURCE
          a `<clutter-actor>', or ``#f'' to unset the source.


     Since 1.4


 -- Function: clutter-bind-constraint-get-source
          (self `<clutter-bind-constraint>') =>  (ret `<clutter-actor>')
 -- Method: get-source
     Retrieves the `<clutter-actor>' set using
     `clutter-bind-constraint-set-source'

    CONSTRAINT
          a `<clutter-bind-constraint>'

    RET
          a pointer to the source actor.


     Since 1.4


 -- Function: clutter-bind-constraint-set-offset
          (self `<clutter-bind-constraint>') (offset `float')
 -- Method: set-offset
     Sets the offset to be applied to the constraint

    CONSTRAINT
          a `<clutter-bind-constraint>'

    OFFSET
          the offset to apply, in pixels


     Since 1.4


 -- Function: clutter-bind-constraint-get-offset
          (self `<clutter-bind-constraint>') =>  (ret `float')
 -- Method: get-offset
     Retrieves the offset set using `clutter-bind-constraint-set-offset'

    CONSTRAINT
          a `<clutter-bind-constraint>'

    RET
          the offset, in pixels


     Since 1.4



File: guile-gnome-clutter.info,  Node: Key Bindings,  Next: ClutterCanvas,  Prev: ClutterBoxLayout,  Up: Top

13 Key Bindings
***************

Pool for key bindings

13.1 Overview
=============

`<clutter-binding-pool>' is a data structure holding a set of key
bindings. Each key binding associates a key symbol (eventually with
modifiers) to an action. A callback function is associated to each
action.

   For a given key symbol and modifier mask combination there can be
only one action; for each action there can be only one callback. There
can be multiple actions with the same name, and the same callback can
be used to handle multiple key bindings.

   Actors requiring key bindings should create a new
`<clutter-binding-pool>' inside their class initialization function and
then install actions like this:


     static void
     foo_class_init (FooClass *klass)
     {
       ClutterBindingPool *binding_pool;

       binding_pool = clutter_binding_pool_get_for_class (klass);

       clutter_binding_pool_install_action (binding_pool, "move-up",
                                            CLUTTER_Up, 0,
                                            G_CALLBACK (foo_action_move_up),
                                            NULL, NULL);
       clutter_binding_pool_install_action (binding_pool, "move-up",
                                            CLUTTER_KP_Up, 0,
                                            G_CALLBACK (foo_action_move_up),
                                            NULL, NULL);
     }

   The callback has a signature of:


        gboolean (* callback) (GObject             *instance,
                               const gchar         *action_name,
                               guint                key_val,
                               ClutterModifierType  modifiers,
                               gpointer             user_data);

   The actor should then override the `<"key-press-event">' and use
`clutter-binding-pool-activate' to match a `<clutter-key-event>'
structure to one of the actions:


       ClutterBindingPool *pool;

       /&#x002A; retrieve the binding pool for the type of the actor &#x002A;/
       pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));

       /&#x002A; activate any callback matching the key symbol and modifiers
        &#x002A; mask of the key event. the returned value can be directly
        &#x002A; used to signal that the actor has handled the event.
        &#x002A;/
       return clutter_binding_pool_activate (pool,
                                             key_event->keyval,
                                             key_event->modifier_state,
                                             G_OBJECT (actor));

   The `clutter-binding-pool-activate' function will return ``#f'' if
no action for the given key binding was found, if the action was
blocked (using `clutter-binding-pool-block-action') or if the key
binding handler returned ``#f''.

   `<clutter-binding-pool>' is available since Clutter 1.0

13.2 Usage
==========

 -- Function: clutter-binding-pool-new (name `mchars') => 
          (ret `<clutter-binding-pool>')
     Creates a new `<clutter-binding-pool>' that can be used to store
     key bindings for an actor. The NAME must be a unique identifier
     for the binding pool, so that `clutter-binding-pool-find' will be
     able to return the correct binding pool.

    NAME
          the name of the binding pool

    RET
          the newly created binding pool with the given name. Use
          `g-object-unref' when done.


     Since 1.0


 -- Function: clutter-binding-pool-get-for-class
          (klass `<g-object-class>') =>  (ret `<clutter-binding-pool>')
     Retrieves the `<clutter-binding-pool>' for the given `<gobject>'
     class and, eventually, creates it. This function is a wrapper
     around `clutter-binding-pool-new' and uses the class type name as
     the unique name for the binding pool.

     Calling this function multiple times will return the same
     `<clutter-binding-pool>'.

     A binding pool for a class can also be retrieved using
     `clutter-binding-pool-find' with the class type name:


            pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));

    KLASS
          a `<g-object-class>' pointer

    RET
          the binding pool for the given class. The returned
          `<clutter-binding-pool>' is owned by Clutter and should not be
          freed directly.


     Since 1.0


 -- Function: clutter-binding-pool-find (name `mchars') => 
          (ret `<clutter-binding-pool>')
     Finds the `<clutter-binding-pool>' with NAME.

    NAME
          the name of the binding pool to find

    RET
          a pointer to the `<clutter-binding-pool>', or ``#f''.


     Since 1.0


 -- Function: clutter-binding-pool-find-action
          (self `<clutter-binding-pool>') (key_val `unsigned-int')
          (modifiers `<clutter-modifier-type>') =>  (ret `mchars')
 -- Method: find-action
     Retrieves the name of the action matching the given key symbol and
     modifiers bitmask.

    POOL
          a `<clutter-binding-pool>'

    KEY-VAL
          a key symbol

    MODIFIERS
          a bitmask for the modifiers

    RET
          the name of the action, if found, or ``#f''. The returned
          string is owned by the binding pool and should never be
          modified or freed


     Since 1.0


 -- Function: clutter-binding-pool-remove-action
          (self `<clutter-binding-pool>') (key_val `unsigned-int')
          (modifiers `<clutter-modifier-type>')
 -- Method: remove-action
     Removes the action matching the given KEY-VAL, MODIFIERS pair, if
     any exists.

    POOL
          a `<clutter-binding-pool>'

    KEY-VAL
          a key symbol

    MODIFIERS
          a bitmask for the modifiers


     Since 1.0


 -- Function: clutter-binding-pool-block-action
          (self `<clutter-binding-pool>') (action_name `mchars')
 -- Method: block-action
     Blocks all the actions with name ACTION-NAME inside POOL.

    POOL
          a `<clutter-binding-pool>'

    ACTION-NAME
          an action name


     Since 1.0


 -- Function: clutter-binding-pool-unblock-action
          (self `<clutter-binding-pool>') (action_name `mchars')
 -- Method: unblock-action
     Unblockes all the actions with name ACTION-NAME inside POOL.

     Unblocking an action does not cause the callback bound to it to be
     invoked in case `clutter-binding-pool-activate' was called on an
     action previously blocked with `clutter-binding-pool-block-action'.

    POOL
          a `<clutter-binding-pool>'

    ACTION-NAME
          an action name


     Since 1.0


 -- Function: clutter-binding-pool-activate
          (self `<clutter-binding-pool>') (key_val `unsigned-int')
          (modifiers `<clutter-modifier-type>') (gobject `<gobject>')
          =>  (ret `bool')
 -- Method: activate
     Activates the callback associated to the action that is bound to
     the KEY-VAL and MODIFIERS pair.

     The callback has the following signature:


            void (* callback) (GObject             *gobject,
                               const gchar         *action_name,
                               guint                key_val,
                               ClutterModifierType  modifiers,
                               gpointer             user_data);

     Where the `<gobject>' instance is GOBJECT and the user data is the
     one passed when installing the action with
     `clutter-binding-pool-install-action'.

     If the action bound to the KEY-VAL, MODIFIERS pair has been
     blocked using `clutter-binding-pool-block-action', the callback
     will not be invoked, and this function will return ``#f''.

    POOL
          a `<clutter-binding-pool>'

    KEY-VAL
          the key symbol

    MODIFIERS
          bitmask for the modifiers

    GOBJECT
          a `<gobject>'

    RET
          ``#t'' if an action was found and was activated


     Since 1.0



File: guile-gnome-clutter.info,  Node: ClutterBlurEffect,  Next: ClutterBrightnessContrastEffect,  Prev: ClutterBinLayout,  Up: Top

14 ClutterBlurEffect
********************

A blur effect

14.1 Overview
=============

`<clutter-blur-effect>' is a sub-class of `<clutter-effect>' that
allows blurring a actor and its contents.

   `<clutter-blur-effect>' is available since Clutter 1.4

14.2 Usage
==========

 -- Function: clutter-blur-effect-new =>  (ret `<clutter-effect>')
     Creates a new `<clutter-blur-effect>' to be used with
     `clutter-actor-add-effect'

    RET
          the newly created `<clutter-blur-effect>' or ``#f''


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterBoxLayout,  Next: Key Bindings,  Prev: ClutterBrightnessContrastEffect,  Up: Top

15 ClutterBoxLayout
*******************

A layout manager arranging children on a single line

15.1 Overview
=============

The `<clutter-box-layout>' is a `<clutter-layout-manager>' implementing
the following layout policy:

   *   *   *   *   *   *   *
   all children are arranged on a single line;

   the axis used is controlled by the `<"vertical">' boolean property;

   the order of the packing is determined by the `<"pack-start">'
boolean property;

   each child will be allocated to its natural size or, if set to
expand, the available size;

   if a child is set to fill on either (or both) axis, its allocation
will match all the available size; the fill layout property only makes
sense if the expand property is also set;

   if a child is set to expand but not to fill then it is possible to
control the alignment using the X and Y alignment layout properties.

   if the `<"homogeneous">' boolean property is set, then all widgets
will get the same size, ignoring expand settings and the preferred sizes

   (The missing figure, box-layout

   The image shows a `<clutter-box-layout>' with the `<"vertical">'
property set to ``#f''.

   It is possible to control the spacing between children of a
`<clutter-box-layout>' by using `clutter-box-layout-set-spacing'.

   In order to set the layout properties when packing an actor inside a
`<clutter-box-layout>' you should use the `clutter-box-layout-pack'
function.

   `<clutter-box-layout>' is available since Clutter 1.2

15.2 Usage
==========

 -- Function: clutter-box-layout-new => 
          (ret `<clutter-layout-manager>')
     Creates a new `<clutter-box-layout>' layout manager

    RET
          the newly created `<clutter-box-layout>'


     Since 1.2


 -- Function: clutter-box-layout-set-pack-start
          (self `<clutter-box-layout>') (pack_start `bool')
 -- Method: set-pack-start
     Sets whether children of LAYOUT should be layed out by appending
     them or by prepending them

    LAYOUT
          a `<clutter-box-layout>'

    PACK-START
          ``#t'' if the LAYOUT should pack children at the beginning of
          the layout


     Since 1.2


 -- Function: clutter-box-layout-get-pack-start
          (self `<clutter-box-layout>') =>  (ret `bool')
 -- Method: get-pack-start
     Retrieves the value set using `clutter-box-layout-set-pack-start'

    LAYOUT
          a `<clutter-box-layout>'

    RET
          ``#t'' if the `<clutter-box-layout>' should pack children at
          the beginning of the layout, and ``#f'' otherwise


     Since 1.2


 -- Function: clutter-box-layout-set-spacing
          (self `<clutter-box-layout>') (spacing `unsigned-int')
 -- Method: set-spacing
     Sets the spacing between children of LAYOUT

    LAYOUT
          a `<clutter-box-layout>'

    SPACING
          the spacing between children of the layout, in pixels


     Since 1.2


 -- Function: clutter-box-layout-get-spacing
          (self `<clutter-box-layout>') =>  (ret `unsigned-int')
 -- Method: get-spacing
     Retrieves the spacing set using `clutter-box-layout-set-spacing'

    LAYOUT
          a `<clutter-box-layout>'

    RET
          the spacing between children of the `<clutter-box-layout>'


     Since 1.2


 -- Function: clutter-box-layout-set-vertical
          (self `<clutter-box-layout>') (vertical `bool')
 -- Method: set-vertical
     Sets whether LAYOUT should arrange its children vertically
     alongside the Y axis, instead of horizontally alongside the X axis

    LAYOUT
          a `<clutter-box-layout>'

    VERTICAL
          ``#t'' if the layout should be vertical


     Since 1.2


 -- Function: clutter-box-layout-get-vertical
          (self `<clutter-box-layout>') =>  (ret `bool')
 -- Method: get-vertical
     Retrieves the orientation of the LAYOUT as set using the
     `clutter-box-layout-set-vertical' function

    LAYOUT
          a `<clutter-box-layout>'

    RET
          ``#t'' if the `<clutter-box-layout>' is arranging its
          children vertically, and ``#f'' otherwise


     Since 1.2


 -- Function: clutter-box-layout-set-homogeneous
          (self `<clutter-box-layout>') (homogeneous `bool')
 -- Method: set-homogeneous
     Sets whether the size of LAYOUT children should be homogeneous

    LAYOUT
          a `<clutter-box-layout>'

    HOMOGENEOUS
          ``#t'' if the layout should be homogeneous


     Since 1.4


 -- Function: clutter-box-layout-get-homogeneous
          (self `<clutter-box-layout>') =>  (ret `bool')
 -- Method: get-homogeneous
     Retrieves if the children sizes are allocated homogeneously.

    LAYOUT
          a `<clutter-box-layout>'

    RET
          ``#t'' if the `<clutter-box-layout>' is arranging its
          children homogeneously, and ``#f'' otherwise


     Since 1.4


 -- Function: clutter-box-layout-pack (self `<clutter-box-layout>')
          (actor `<clutter-actor>') (expand `bool') (x_fill `bool')
          (y_fill `bool') (x_align `<clutter-box-alignment>')
          (y_align `<clutter-box-alignment>')
 -- Method: pack
     Packs ACTOR inside the `<clutter-container>' associated to LAYOUT
     and sets the layout properties

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>'

    EXPAND
          whether the ACTOR should expand

    X-FILL
          whether the ACTOR should fill horizontally

    Y-FILL
          whether the ACTOR should fill vertically

    X-ALIGN
          the horizontal alignment policy for ACTOR

    Y-ALIGN
          the vertical alignment policy for ACTOR


     Since 1.2


 -- Function: clutter-box-layout-set-alignment
          (self `<clutter-box-layout>') (actor `<clutter-actor>')
          (x_align `<clutter-box-alignment>')
          (y_align `<clutter-box-alignment>')
 -- Method: set-alignment
     Sets the horizontal and vertical alignment policies for ACTOR
     inside LAYOUT

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    X-ALIGN
          Horizontal alignment policy for ACTOR

    Y-ALIGN
          Vertical alignment policy for ACTOR


     Since 1.2


 -- Function: clutter-box-layout-get-alignment
          (self `<clutter-box-layout>') (actor `<clutter-actor>') => 
          (x_align `<clutter-box-alignment>')
          (y_align `<clutter-box-alignment>')
 -- Method: get-alignment
     Retrieves the horizontal and vertical alignment policies for ACTOR
     as set using `clutter-box-layout-pack' or
     `clutter-box-layout-set-alignment'

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    X-ALIGN
          return location for the horizontal alignment policy.

    Y-ALIGN
          return location for the vertical alignment policy.


     Since 1.2


 -- Function: clutter-box-layout-set-expand
          (self `<clutter-box-layout>') (actor `<clutter-actor>')
          (expand `bool')
 -- Method: set-expand
     Sets whether ACTOR should expand inside LAYOUT

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    EXPAND
          whether ACTOR should expand


     Since 1.2


 -- Function: clutter-box-layout-get-expand
          (self `<clutter-box-layout>') (actor `<clutter-actor>') => 
          (ret `bool')
 -- Method: get-expand
     Retrieves whether ACTOR should expand inside LAYOUT

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    RET
          ``#t'' if the `<clutter-actor>' should expand, ``#f''
          otherwise


     Since 1.2


 -- Function: clutter-box-layout-set-fill (self `<clutter-box-layout>')
          (actor `<clutter-actor>') (x_fill `bool') (y_fill `bool')
 -- Method: set-fill
     Sets the horizontal and vertical fill policies for ACTOR inside
     LAYOUT

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    X-FILL
          whether ACTOR should fill horizontally the allocated space

    Y-FILL
          whether ACTOR should fill vertically the allocated space


     Since 1.2


 -- Function: clutter-box-layout-get-fill (self `<clutter-box-layout>')
          (actor `<clutter-actor>') =>  (x_fill `bool') (y_fill `bool')
 -- Method: get-fill
     Retrieves the horizontal and vertical fill policies for ACTOR as
     set using `clutter-box-layout-pack' or
     `clutter-box-layout-set-fill'

    LAYOUT
          a `<clutter-box-layout>'

    ACTOR
          a `<clutter-actor>' child of LAYOUT

    X-FILL
          return location for the horizontal fill policy.

    Y-FILL
          return location for the vertical fill policy.


     Since 1.2


 -- Function: clutter-box-layout-set-easing-mode
          (self `<clutter-box-layout>') (mode `unsigned-long')
 -- Method: set-easing-mode
     Sets the easing mode to be used by LAYOUT when animating changes
     in layout properties

     Use `clutter-box-layout-set-use-animations' to enable and disable
     the animations

    LAYOUT
          a `<clutter-box-layout>'

    MODE
          an easing mode, either from `<clutter-animation-mode>' or a
          logical id from `clutter-alpha-register-func'


     Since 1.2


 -- Function: clutter-box-layout-get-easing-mode
          (self `<clutter-box-layout>') =>  (ret `unsigned-long')
 -- Method: get-easing-mode
     Retrieves the easing mode set using
     `clutter-box-layout-set-easing-mode'

    LAYOUT
          a `<clutter-box-layout>'

    RET
          an easing mode


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterBrightnessContrastEffect,  Next: ClutterBoxLayout,  Prev: ClutterBlurEffect,  Up: Top

16 ClutterBrightnessContrastEffect
**********************************

Increase/decrease brightness and/or contrast of actor.

16.1 Overview
=============

`<clutter-brightness-contrast-effect>' is a sub-class of
`<clutter-effect>' that changes the overall brightness of a
`<clutter-actor>'.

   `<clutter-brightness-contrast-effect>' is available since Clutter
1.10

16.2 Usage
==========


File: guile-gnome-clutter.info,  Node: ClutterCairoTexture,  Next: ClutterClickAction,  Prev: ClutterChildMeta,  Up: Top

17 ClutterCairoTexture
**********************

Texture with Cairo integration

17.1 Overview
=============

`<clutter-cairo-texture>' is a `<clutter-texture>' that displays the
contents of a Cairo context. The `<clutter-cairo-texture>' actor will
create a Cairo image surface which will then be uploaded to a GL
texture when needed.

   Since `<clutter-cairo-texture>' uses a Cairo image surface
internally all the drawing operations will be performed in software and
not using hardware acceleration. This can lead to performance
degradation if the contents of the texture change frequently.

   In order to use a `<clutter-cairo-texture>' you should connect to
the `<"draw">' signal; the signal is emitted each time the
`<clutter-cairo-texture>' has been told to invalidate its contents, by
using `clutter-cairo-texture-invalidate-rectangle' or its sister
function, `clutter-cairo-texture-invalidate'.

   Each callback to the `<"draw">' signal will receive a `<cairo-t>'
context which can be used for drawing; the Cairo context is owned by
the `<clutter-cairo-texture>' and should not be destroyed explicitly.


   `<clutter-cairo-texture>' is available since Clutter 1.0.

17.2 Usage
==========

 -- Function: clutter-cairo-texture-new (width `unsigned-int')
          (height `unsigned-int') =>  (ret `<clutter-actor>')
     Creates a new `<clutter-cairo-texture>' actor, with a surface of
     WIDTH by HEIGHT pixels.

    WIDTH
          the width of the surface

    HEIGHT
          the height of the surface

    RET
          the newly created `<clutter-cairo-texture>' actor


     Since 1.0


 -- Function: clutter-cairo-texture-invalidate
          (self `<clutter-cairo-texture>')
 -- Method: invalidate
     Invalidates the whole surface of a `<clutter-cairo-texture>'.

     This function will cause the `<"draw">' signal to be emitted.

     See also: `clutter-cairo-texture-invalidate-rectangle'

    SELF
          a `<clutter-cairo-texture>'


     Since 1.8


 -- Function: clutter-cairo-texture-clear
          (self `<clutter-cairo-texture>')
 -- Method: clear
     Clears SELF's internal drawing surface, so that the next upload
     will replace the previous contents of the `<clutter-cairo-texture>'
     rather than adding to it.

     Calling this function from within a `<"draw">' signal handler will
     clear the invalidated area.

    SELF
          a `<clutter-cairo-texture>'


     Since 1.0


 -- Function: clutter-cairo-set-source-color (cr `cairo-t')
          (color `<clutter-color>')
     Utility function for setting the source color of CR using a
     `<clutter-color>'. This function is the equivalent of:


            cairo_set_source_rgba (cr,
                                   color->red / 255.0,
                                   color->green / 255.0,
                                   color->blue / 255.0,
                                   color->alpha / 255.0);

    CR
          a Cairo context

    COLOR
          a `<clutter-color>'


     Since 1.0



File: guile-gnome-clutter.info,  Node: ClutterCanvas,  Next: ClutterChildMeta,  Prev: Key Bindings,  Up: Top

18 ClutterCanvas
****************

Content for 2D painting

18.1 Overview
=============

The `<clutter-canvas>' class is a `<clutter-content>' implementation
that allows drawing using the Cairo API on a 2D surface.

   In order to draw on a `<clutter-canvas>', you should connect a
handler to the `<"draw">' signal; the signal will receive a `<cairo-t>'
context that can be used to draw.  `<clutter-canvas>' will emit the
`<"draw">' signal when invalidated using `clutter-content-invalidate'.


   `<clutter-canvas>' is available since Clutter 1.10.

18.2 Usage
==========

 -- Function: clutter-canvas-new =>  (ret `<clutter-content>')
     Creates a new instance of `<clutter-canvas>'.

     You should call `clutter-canvas-set-size' to set the size of the
     canvas.

     You should call `clutter-content-invalidate' every time you wish to
     draw the contents of the canvas.

    RET
          The newly allocated instance of `<clutter-canvas>'. Use
          `g-object-unref' when done.


     Since 1.10


 -- Function: clutter-canvas-set-size (self `<clutter-canvas>')
          (width `int') (height `int')
 -- Method: set-size
     Sets the size of the CANVAS.

     This function will cause the CANVAS to be invalidated.

    CANVAS
          a `<clutter-canvas>'

    WIDTH
          the width of the canvas, in pixels

    HEIGHT
          the height of the canvas, in pixels


     Since 1.10



File: guile-gnome-clutter.info,  Node: ClutterChildMeta,  Next: ClutterCairoTexture,  Prev: ClutterCanvas,  Up: Top

19 ClutterChildMeta
*******************

Wrapper for actors inside a container

19.1 Overview
=============

`<clutter-child-meta>' is a wrapper object created by
`<clutter-container>' implementations in order to store child-specific
data and properties.

   A `<clutter-child-meta>' wraps a `<clutter-actor>' inside a
`<clutter-container>'.

   `<clutter-child-meta>' is available since Clutter 0.8

19.2 Usage
==========

 -- Function: clutter-child-meta-get-container
          (self `<clutter-child-meta>') =>  (ret `<clutter-container>')
 -- Method: get-container
     Retrieves the container using DATA

    DATA
          a `<clutter-child-meta>'

    RET
          a `<clutter-container>'.


     Since 0.8


 -- Function: clutter-child-meta-get-actor
          (self `<clutter-child-meta>') =>  (ret `<clutter-actor>')
 -- Method: get-actor
     Retrieves the actor wrapped by DATA

    DATA
          a `<clutter-child-meta>'

    RET
          a `<clutter-actor>'.


     Since 0.8



File: guile-gnome-clutter.info,  Node: ClutterClickAction,  Next: ClutterClone,  Prev: ClutterCairoTexture,  Up: Top

20 ClutterClickAction
*********************

Action for clickable actors

20.1 Overview
=============

`<clutter-click-action>' is a sub-class of `<clutter-action>' that
implements the logic for clickable actors, by using the low level
events of `<clutter-actor>', such as `<"button-press-event">' and
`<"button-release-event">', to synthesize the high level `<"clicked">'
signal.

   To use `<clutter-click-action>' you just need to apply it to a
`<clutter-actor>' using `clutter-actor-add-action' and connect to the
`<"clicked">' signal:


       ClutterAction *action = clutter_click_action_new ();

       clutter_actor_add_action (actor, action);

       g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), NULL);

   `<clutter-click-action>' also supports long press gestures: a long
press is activated if the pointer remains pressed within a certain
threshold (as defined by the `<"long-press-threshold">' property) for a
minimum amount of time (as the defined by the `<"long-press-duration">'
property). The `<"long-press">' signal is emitted multiple times, using
different `<clutter-long-press-state>' values; to handle long presses
you should connect to the `<"long-press">' signal and handle the
different states:


       static gboolean
       on_long_press (ClutterClickAction    *action,
                      ClutterActor          *actor,
                      ClutterLongPressState  state)
       {
         switch (state)
           {
           case CLUTTER_LONG_PRESS_QUERY:
             /&#x002A; return TRUE if the actor should support long press
              &#x002A; gestures, and FALSE otherwise; this state will be
              &#x002A; emitted on button presses
              &#x002A;/
             return TRUE;

           case CLUTTER_LONG_PRESS_ACTIVATE:
             /&#x002A; this state is emitted if the minimum duration has
              &#x002A; been reached without the gesture being cancelled.
              &#x002A; the return value is not used
              &#x002A;/
             return TRUE;

           case CLUTTER_LONG_PRESS_CANCEL:
             /&#x002A; this state is emitted if the long press was cancelled;
              &#x002A; for instance, the pointer went outside the actor or the
              &#x002A; allowed threshold, or the button was released before
              &#x002A; the minimum duration was reached. the return value is
              &#x002A; not used
              &#x002A;/
             return FALSE;
           }
       }

   `<clutter-click-action>' is available since Clutter 1.4

20.2 Usage
==========

 -- Function: clutter-click-action-new =>  (ret `<clutter-action>')
     Creates a new `<clutter-click-action>' instance

    RET
          the newly created `<clutter-click-action>'


     Since 1.4


 -- Function: clutter-click-action-get-button
          (self `<clutter-click-action>') =>  (ret `unsigned-int')
 -- Method: get-button
     Retrieves the button that was pressed.

    ACTION
          a `<clutter-click-action>'

    RET
          the button value


     Since 1.4


 -- Function: clutter-click-action-get-state
          (self `<clutter-click-action>') => 
          (ret `<clutter-modifier-type>')
 -- Method: get-state
     Retrieves the modifier state of the click action.

    ACTION
          a `<clutter-click-action>'

    RET
          the modifier state parameter, or 0


     Since 1.6


 -- Function: clutter-click-action-get-coords
          (self `<clutter-click-action>') =>  (press_x `float')
          (press_y `float')
 -- Method: get-coords
     Retrieves the screen coordinates of the button press.

    ACTION
          a `<clutter-click-action>'

    PRESS-X
          return location for the X coordinate, or ``#f''.

    PRESS-Y
          return location for the Y coordinate, or ``#f''.


     Since 1.8


 -- Function: clutter-click-action-release
          (self `<clutter-click-action>')
 -- Method: release
     Emulates a release of the pointer button, which ungrabs the
     pointer and unsets the `<"pressed">' state.

     This function will also cancel the long press gesture if one was
     initiated.

     This function is useful to break a grab, for instance after a
     certain amount of time has passed.

    ACTION
          a `<clutter-click-action>'


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterClone,  Next: ClutterColorizeEffect,  Prev: ClutterClickAction,  Up: Top

21 ClutterClone
***************

An actor that displays a clone of a source actor

21.1 Overview
=============

`<clutter-clone>' is a `<clutter-actor>' which draws with the paint
function of another actor, scaled to fit its own allocation.

   `<clutter-clone>' can be used to efficiently clone any other actor.

   This is different from `clutter-texture-new-from-actor' which
requires support for FBOs in the underlying GL implementation.

   `<clutter-clone>' is available since Clutter 1.0

21.2 Usage
==========

 -- Function: clutter-clone-new (source `<clutter-actor>') => 
          (ret `<clutter-actor>')
     Creates a new `<clutter-actor>' which clones SOURCE/

    SOURCE
          a `<clutter-actor>', or ``#f''

    RET
          the newly created `<clutter-clone>'


     Since 1.0


 -- Function: clutter-clone-set-source (self `<clutter-clone>')
          (source `<clutter-actor>')
 -- Method: set-source
     Sets SOURCE as the source actor to be cloned by SELF.

    SELF
          a `<clutter-clone>'

    SOURCE
          a `<clutter-actor>', or ``#f''.


     Since 1.0


 -- Function: clutter-clone-get-source (self `<clutter-clone>') => 
          (ret `<clutter-actor>')
 -- Method: get-source
     Retrieves the source `<clutter-actor>' being cloned by SELF.

    SELF
          a `<clutter-clone>'

    RET
          the actor source for the clone.


     Since 1.0



File: guile-gnome-clutter.info,  Node: Colors,  Next: ClutterConstraint,  Prev: ClutterColorizeEffect,  Up: Top

22 Colors
*********

Color management and manipulation.

22.1 Overview
=============

`<clutter-color>' is a simple type for representing colors in Clutter.

   A `<clutter-color>' is expressed as a 4-tuple of values ranging from
zero to 255, one for each color channel plus one for the alpha.

   The alpha channel is fully opaque at 255 and fully transparent at 0.

22.2 Usage
==========

 -- Function: clutter-color-new (red `unsigned-int8')
          (green `unsigned-int8') (blue `unsigned-int8')
          (alpha `unsigned-int8') =>  (ret `<clutter-color>')
     Creates a new `<clutter-color>' with the given values.

    RED
          red component of the color, between 0 and 255

    GREEN
          green component of the color, between 0 and 255

    BLUE
          blue component of the color, between 0 and 255

    ALPHA
          alpha component of the color, between 0 and 255

    RET
          the newly allocated color. Use `clutter-color-free' when done.


     Since 0.8.4


 -- Function: clutter-color-get-static (color `<clutter-static-color>')
          =>  (ret `<clutter-color>')
     Retrieves a static color for the given COLOR name

     Static colors are created by Clutter and are guaranteed to always
     be available and valid

    COLOR
          the named global color

    RET
          a pointer to a static color; the returned pointer is owned by
          Clutter and it should never be modified or freed


     Since 1.6


 -- Function: clutter-color-from-string (name `mchars') =>  (ret `scm')
     Parses a string definition of a color, filling the "red") ,
     (structfield "alpha") channels of COLOR.

     The COLOR is not allocated.

     The format of STR can be either one of:

        *        *        *        *        *        *
     a standard name (as taken from the X11 rgb.txt file)

     an hexadecimal value in the form: `&#x0023;rgb', `&#x0023;rrggbb',
     `&#x0023;rgba' or `&#x0023;rrggbbaa'

     a RGB color in the form: `rgb(r, g, b)'

     a RGB color in the form: `rgba(r, g, b, a)'

     a HSL color in the form: `hsl(h, s, l)'

     a HSL color in the form: `hsla(h, s, l, a)'

     where 'r', 'g', 'b' and 'a' are (respectively) the red, green, blue
     color intensities and the opacity. The 'h', 's' and 'l' are
     (respectively) the hue, saturation and luminance values.

     In the `rgb' and `rgba' formats, the 'r', 'g', and 'b' values are
     either integers between 0 and 255, or percentage values in the
     range between 0% and 100%; the percentages require the '%'
     character. The 'a' value, if specified, can only be a floating
     point value between 0.0 and 1.0.

     In the `hls' and `hlsa' formats, the 'h' value (hue) it's an angle
     between 0 and 360.0 degrees; the 'l' and 's' values (luminance and
     saturation) are a floating point value between 0.0 and 1.0. The 'a'
     value, if specified, can only be a floating point value between
     0.0 and 1.0.

     Whitespace inside the definitions is ignored; no leading
     whitespace is allowed.

     If the alpha component is not specified then it is assumed to be
     set to be fully opaque.

    COLOR
          return location for a `<clutter-color>'.

    STR
          a string specifiying a color

    RET
          ``#t'' if parsing succeeded, and ``#f'' otherwise


     Since 1.0


 -- Function: clutter-color-to-string (self `<clutter-color>') => 
          (ret `mchars')
     Returns a textual specification of COLOR in the hexadecimal form
     `&#x0023;rrggbbaa', where `r', `g', `b' and `a' are hexadecimal
     digits representing the red, green, blue and alpha components
     respectively.

    COLOR
          a `<clutter-color>'

    RET
          a newly-allocated text string.


     Since 0.2


 -- Function: clutter-color-from-hls (self `<clutter-color>')
          (hue `float') (luminance `float') (saturation `float')
     Converts a color expressed in HLS (hue, luminance and saturation)
     values into a `<clutter-color>'.

    COLOR
          return location for a `<clutter-color>'.

    HUE
          hue value, in the 0 .. 360 range

    LUMINANCE
          luminance value, in the 0 .. 1 range

    SATURATION
          saturation value, in the 0 .. 1 range



 -- Function: clutter-color-to-hls (self `<clutter-color>') => 
          (hue `float') (luminance `float') (saturation `float')
     Converts COLOR to the HLS format.

     The HUE value is in the 0 .. 360 range. The LUMINANCE and
     SATURATION values are in the 0 .. 1 range.

    COLOR
          a `<clutter-color>'

    HUE
          return location for the hue value or ``#f''.

    LUMINANCE
          return location for the luminance value or ``#f''.

    SATURATION
          return location for the saturation value or ``#f''.



 -- Function: clutter-color-from-pixel (self `<clutter-color>')
          (pixel `unsigned-int32')
     Converts PIXEL from the packed representation of a four 8 bit
     channel color to a `<clutter-color>'.

    COLOR
          return location for a `<clutter-color>'.

    PIXEL
          a 32 bit packed integer containing a color



 -- Function: clutter-color-to-pixel (self `<clutter-color>') => 
          (ret `unsigned-int32')
     Converts COLOR into a packed 32 bit integer, containing all the
     four 8 bit channels used by `<clutter-color>'.

    COLOR
          a `<clutter-color>'

    RET
          a packed color



 -- Function: clutter-color-add (self `<clutter-color>')
          (b `<clutter-color>') (result `<clutter-color>')
     Adds A to B and saves the resulting color inside RESULT.

     The alpha channel of RESULT is set as as the maximum value between
     the alpha channels of A and B.

    A
          a `<clutter-color>'

    B
          a `<clutter-color>'

    RESULT
          return location for the result.



 -- Function: clutter-color-subtract (self `<clutter-color>')
          (b `<clutter-color>') (result `<clutter-color>')
     Subtracts B from A and saves the resulting color inside RESULT.

     This function assumes that the components of A are greater than
     the components of B; the result is, otherwise, undefined.

     The alpha channel of RESULT is set as the minimum value between
     the alpha channels of A and B.

    A
          a `<clutter-color>'

    B
          a `<clutter-color>'

    RESULT
          return location for the result.



 -- Function: clutter-color-lighten (self `<clutter-color>')
          (result `<clutter-color>')
     Lightens COLOR by a fixed amount, and saves the changed color in
     RESULT.

    COLOR
          a `<clutter-color>'

    RESULT
          return location for the lighter color.



 -- Function: clutter-color-darken (self `<clutter-color>')
          (result `<clutter-color>')
     Darkens COLOR by a fixed amount, and saves the changed color in
     RESULT.

    COLOR
          a `<clutter-color>'

    RESULT
          return location for the darker color.



 -- Function: clutter-color-shade (self `<clutter-color>')
          (factor `double') (result `<clutter-color>')
     Shades COLOR by FACTOR and saves the modified color into RESULT.

    COLOR
          a `<clutter-color>'

    FACTOR
          the shade factor to apply

    RESULT
          return location for the shaded color.



 -- Function: clutter-color-interpolate (self `<clutter-color>')
          (final `<clutter-color>') (progress `double')
          (result `<clutter-color>')
     Interpolates between INITIAL and FINAL`<clutter-color>'s using
     PROGRESS

    INITIAL
          the initial `<clutter-color>'

    FINAL
          the final `<clutter-color>'

    PROGRESS
          the interpolation progress

    RESULT
          return location for the interpolation.


     Since 1.6


 -- Function: clutter-value-set-color (value `<gvalue>')
          (color `<clutter-color>')
     Sets VALUE to COLOR.

    VALUE
          a `<gvalue>' initialized to `<clutter-type-color>'

    COLOR
          the color to set


     Since 0.8.4


 -- Function: clutter-value-get-color (value `<gvalue>') => 
          (ret `<clutter-color>')
     Gets the `<clutter-color>' contained in VALUE.

    VALUE
          a `<gvalue>' initialized to `<clutter-type-color>'

    RET
          the color inside the passed `<gvalue>'.


     Since 0.8.4



File: guile-gnome-clutter.info,  Node: ClutterColorizeEffect,  Next: Colors,  Prev: ClutterClone,  Up: Top

23 ClutterColorizeEffect
************************

A colorization effect

23.1 Overview
=============

`<clutter-colorize-effect>' is a sub-class of `<clutter-effect>' that
colorizes an actor with the given tint.

   `<clutter-colorize-effect>' is available since Clutter 1.4

23.2 Usage
==========

 -- Function: clutter-colorize-effect-new (self `<clutter-color>') => 
          (ret `<clutter-effect>')
     Creates a new `<clutter-colorize-effect>' to be used with
     `clutter-actor-add-effect'

    TINT
          the color to be used

    RET
          the newly created `<clutter-colorize-effect>' or ``#f''


     Since 1.4


 -- Function: clutter-colorize-effect-set-tint
          (self `<clutter-colorize-effect>') (tint `<clutter-color>')
 -- Method: set-tint
     Sets the tint to be used when colorizing

    EFFECT
          a `<clutter-colorize-effect>'

    TINT
          the color to be used


     Since 1.4


 -- Function: clutter-colorize-effect-get-tint
          (self `<clutter-colorize-effect>') (tint `<clutter-color>')
 -- Method: get-tint
     Retrieves the tint used by EFFECT

    EFFECT
          a `<clutter-colorize-effect>'

    TINT
          return location for the color used.


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterConstraint,  Next: ClutterContainer,  Prev: Colors,  Up: Top

24 ClutterConstraint
********************

Abstract class for constraints on position or size

24.1 Overview
=============

`<clutter-constraint>' is a base abstract class for modifiers of a
`<clutter-actor>' position or size.

   A `<clutter-constraint>' sub-class should contain the logic for
modifying the position or size of the `<clutter-actor>' to which it is
applied, by updating the actor's allocation. Each
`<clutter-constraint>' can change the allocation of the actor to which
they are applied by overriding the ``update-allocation'' virtual
function.

24.2 Using Constraints
======================

Constraints can be used with fixed layout managers, like
`<clutter-fixed-layout>', or with actors implicitly using a fixed
layout manager, like `<clutter-group>' and `<clutter-stage>'.

   Constraints provide a way to build user interfaces by using relations
between `<clutter-actor>'s, without explicit fixed positioning and
sizing, similarly to how fluid layout managers like
`<clutter-box-layout>' and `<clutter-table-layout>' lay out their
children.

   Constraints are attached to a `<clutter-actor>', and are available
for inspection using `clutter-actor-get-constraints'.

   Clutter provides different implementation of the
`<clutter-constraint>' abstract class, for instance:

<CLUTTER-BIND-CONSTRAINT>
     this constraint binds the X, Y, width or height of an actor to the
     corresponding position or size of a source actor; it can also
     apply an offset.

<CLUTTER-SNAP-CONSTRAINT>
     this constraint "snaps" together the edges of two
     `<clutter-actor>'s; if an actor uses two constraints on both its
     horizontal or vertical edges then it can also expand to fit the
     empty space.


   The example below uses various `<clutter-constraint>'s to lay out
three actors on a resizable stage. Only the central actor has an
explicit size, and no actor has an explicit position.

  1. The `<clutter-rectangle>' with `<"name">'_layerA_ is explicitly
     sized to 100 pixels by 25 pixels, and it's added to the
     `<clutter-stage>';

  2. two `<clutter-align-constraint>'s are used to anchor _layerA_ to
     the center of the stage, by using 0.5 as the alignment
     `<"factor">' on both the X and Y axis.

  3. the `<clutter-rectangle>' with `<"name">'_layerB_ is added to the
     `<clutter-stage>' with no explicit size;

  4. the `<"x">' and `<"width">' of _layerB_ are bound to the same
     properties of _layerA_ using two `<clutter-bind-constraint>'
     objects, thus keeping _layerB_ aligned to _layerA_;

  5. the top edge of _layerB_ is snapped together with the bottom edge
     of _layerA_; the bottom edge of _layerB_ is also snapped together
     with the bottom edge of the `<clutter-stage>'; an offset is given
     to the two `<clutter-snap-constraint>'s to allow for some padding;
     since _layerB_ is snapped between two different
     `<clutter-actor>'s, its height is stretched to match the gap;

  6. the `<clutter-rectangle>' with `<"name">'_layerC_ mirrors
     _layerB_, snapping the top edge of the `<clutter-stage>' to the
     top edge of _layerC_ and the top edge of _layerA_ to the bottom
     edge of _layerC_;



   You can try resizing interactively the `<clutter-stage>' and verify
that the three `<clutter-actor>'s maintain the same position and size
relative to each other, and to the `<clutter-stage>'.

   It's important to note that Clutter does not avoid loops or competing
constraints; if two or more `<clutter-constraint>'s are operating on
the same positional or dimensional attributes of an actor, or if the
constraints on two different actors depend on each other, then the
behavior is undefined.

24.3 Implementing a ClutterConstraint
=====================================

Creating a sub-class of `<clutter-constraint>' requires the
implementation of the ``update-allocation'' virtual function.

   The ``update-allocation'' virtual function is called during the
allocation sequence of a `<clutter-actor>', and allows any
`<clutter-constraint>' attached to that actor to modify the allocation
before it is passed to the ``allocate'' implementation.

   The `<clutter-actor-box>' passed to the ``update-allocation''
implementation contains the original allocation of the
`<clutter-actor>', plus the eventual modifications applied by the other
`<clutter-constraint>'s.

   Constraints are queried in the same order as they were applied using
`clutter-actor-add-constraint' or
`clutter-actor-add-constraint-with-name'.

   It is not necessary for a `<clutter-constraint>' sub-class to chain
up to the parent's implementation.

   If a `<clutter-constraint>' is parametrized - i.e. if it contains
properties that affect the way the constraint is implemented - it should
call `clutter-actor-queue-relayout' on the actor to which it is
attached to whenever any parameter is changed. The actor to which it is
attached can be recovered at any point using
`clutter-actor-meta-get-actor'.

   `<clutter-constraint>' is available since Clutter 1.4

24.4 Usage
==========


File: guile-gnome-clutter.info,  Node: ClutterContainer,  Next: ClutterContent,  Prev: ClutterConstraint,  Up: Top

25 ClutterContainer
*******************

An interface for container actors

25.1 Overview
=============

`<clutter-container>' is an interface implemented by `<clutter-actor>',
and it provides some common API for notifying when a child actor is
added or removed, as well as the infrastructure for accessing child
properties through `<clutter-child-meta>'.

   Until Clutter 1.10, the `<clutter-container>' interface was also the
public API for implementing container actors; this part of the
interface has been deprecated: `<clutter-container>' has a default
implementation which defers to `<clutter-actor>' the child addition and
removal, as well as the iteration. See the documentation of
`<clutter-container-iface>' for the list of virtual functions that
should be overridden.

25.2 Usage
==========

 -- Function: clutter-container-child-notify
          (self `<clutter-container>') (child `<clutter-actor>')
          (pspec `<gparam>')
 -- Method: child-notify
     Calls the `clutter-container-iface.child-notify' virtual function
     of `<clutter-container>'. The default implementation will emit the
     `<"child-notify">' signal.

    CONTAINER
          a `<clutter-container>'

    CHILD
          a `<clutter-actor>'

    PSPEC
          a `<gparam>'


     Since 1.6


 -- Function: clutter-container-create-child-meta
          (self `<clutter-container>') (actor `<clutter-actor>')
 -- Method: create-child-meta
     Creates the `<clutter-child-meta>' wrapping ACTOR inside the
     CONTAINER, if the `<"child-meta-type">' class member is not set to
     `G_TYPE_INVALID'.

     This function is only useful when adding a `<clutter-actor>' to a
     `<clutter-container>' implementation outside of the
     `<clutter-container>'::`add' virtual function implementation.

     Applications should not call this function.

    CONTAINER
          a `<clutter-container>'

    ACTOR
          a `<clutter-actor>'


     Since 1.2


 -- Function: clutter-container-get-child-meta
          (self `<clutter-container>') (actor `<clutter-actor>') => 
          (ret `<clutter-child-meta>')
 -- Method: get-child-meta
     Retrieves the `<clutter-child-meta>' which contains the data about
     the CONTAINER specific state for ACTOR.

    CONTAINER
          a `<clutter-container>'

    ACTOR
          a `<clutter-actor>' that is a child of CONTAINER.

    RET
          the `<clutter-child-meta>' for the ACTOR child of CONTAINER
          or ``#f'' if the specifiec actor does not exist or the
          container is not configured to provide
          `<clutter-child-meta>'s.


     Since 0.8



File: guile-gnome-clutter.info,  Node: ClutterContent,  Next: ClutterDeformEffect,  Prev: ClutterContainer,  Up: Top

26 ClutterContent
*****************

Delegate for painting the content of an actor

26.1 Overview
=============

`<clutter-content>' is an interface to implement types responsible for
painting the content of a `<clutter-actor>'.

   Multiple actors can use the same `<clutter-content>' instance, in
order to share the resources associated with painting the same content.

   `<clutter-content>' is available since Clutter 1.10.

26.2 Usage
==========

 -- Function: clutter-content-get-preferred-size
          (self `<clutter-content>') =>  (ret `bool') (width `float')
          (height `float')
 -- Method: get-preferred-size
     Retrieves the natural size of the CONTENT, if any.

     The natural size of a `<clutter-content>' is defined as the size
     the content would have regardless of the allocation of the actor
     that is painting it, for instance the size of an image data.

    CONTENT
          a `<clutter-content>'

    WIDTH
          return location for the natural width of the content.

    HEIGHT
          return location for the natural height of the content.

    RET
          ``#t'' if the content has a preferred size, and ``#f''
          otherwise


     Since 1.10


 -- Function: clutter-content-invalidate (self `<clutter-content>')
 -- Method: invalidate
     Invalidates a `<clutter-content>'.

     This function should be called by `<clutter-content>'
     implementations when they change the way a the content should be
     painted regardless of the actor state.

    CONTENT
          a `<clutter-content>'


     Since 1.10



File: guile-gnome-clutter.info,  Node: ClutterDeformEffect,  Next: ClutterDesaturateEffect,  Prev: ClutterContent,  Up: Top

27 ClutterDeformEffect
**********************

A base class for effects deforming the geometry of an actor

27.1 Overview
=============

`<clutter-deform-effect>' is an abstract class providing all the
plumbing for creating effects that result in the deformation of an
actor's geometry.

   `<clutter-deform-effect>' uses offscreen buffers to render the
contents of a `<clutter-actor>' and then the Cogl vertex buffers API to
submit the geometry to the GPU.

27.2 Implementing ClutterDeformEffect
=====================================

Sub-classes of `<clutter-deform-effect>' should override the
``deform-vertex'' virtual function; this function is called on every
vertex that needs to be deformed by the effect. Each passed vertex is
an in-out parameter that initially contains the position of the vertex
and should be modified according to a specific deformation algorithm.

   `<clutter-deform-effect>' is available since Clutter 1.4

27.3 Usage
==========

 -- Function: clutter-deform-effect-set-n-tiles
          (self `<clutter-deform-effect>') (x_tiles `unsigned-int')
          (y_tiles `unsigned-int')
 -- Method: set-n-tiles
     Sets the number of horizontal and vertical tiles to be used when
     applying the effect

     More tiles allow a finer grained deformation at the expenses of
     computation

    EFFECT
          a `<clutter-deform-effect>'

    X-TILES
          number of horizontal tiles

    Y-TILES
          number of vertical tiles


     Since 1.4


 -- Function: clutter-deform-effect-get-n-tiles
          (self `<clutter-deform-effect>') =>  (x_tiles `unsigned-int')
          (y_tiles `unsigned-int')
 -- Method: get-n-tiles
     Retrieves the number of horizontal and vertical tiles used to
     sub-divide the actor's geometry during the effect

    EFFECT
          a `<clutter-deform-effect>'

    X-TILES
          return location for the number of horizontal tiles, or ``#f''.

    Y-TILES
          return location for the number of vertical tiles, or ``#f''.


     Since 1.4


 -- Function: clutter-deform-effect-invalidate
          (self `<clutter-deform-effect>')
 -- Method: invalidate
     Invalidates the EFFECT's vertices and, if it is associated to an
     actor, it will queue a redraw

    EFFECT
          a `<clutter-deform-effect>'


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterDesaturateEffect,  Next: ClutterDeviceManager,  Prev: ClutterDeformEffect,  Up: Top

28 ClutterDesaturateEffect
**************************

A desaturation effect

28.1 Overview
=============

`<clutter-desaturate-effect>' is a sub-class of `<clutter-effect>' that
desaturates the color of an actor and its contents. The strenght of the
desaturation effect is controllable and animatable through the
`<"factor">' property.

   `<clutter-desaturate-effect>' is available since Clutter 1.4

28.2 Usage
==========

 -- Function: clutter-desaturate-effect-new (factor `double') => 
          (ret `<clutter-effect>')
     Creates a new `<clutter-desaturate-effect>' to be used with
     `clutter-actor-add-effect'

    FACTOR
          the desaturation factor, between 0.0 and 1.0

    RET
          the newly created `<clutter-desaturate-effect>' or ``#f''


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterDeviceManager,  Next: ClutterDragAction,  Prev: ClutterDesaturateEffect,  Up: Top

29 ClutterDeviceManager
***********************

Maintains the list of input devices

29.1 Overview
=============

`<clutter-device-manager>' is a singleton object, owned by Clutter,
which maintains the list of `<clutter-input-device>'s.

   Depending on the backend used by Clutter it is possible to use the
`<"device-added">' and `<"device-removed">' to monitor addition and
removal of devices.

   `<clutter-device-manager>' is available since Clutter 1.2

29.2 Usage
==========

 -- Function: clutter-device-manager-list-devices
          (self `<clutter-device-manager>') =>  (ret `gslist-of')
 -- Method: list-devices
     Lists all currently registered input devices

    DEVICE-MANAGER
          a `<clutter-device-manager>'

    RET
          a newly allocated list of `<clutter-input-device>' objects.
          Use `g-slist-free' to deallocate it when done.


     Since 1.2


 -- Function: clutter-device-manager-peek-devices
          (self `<clutter-device-manager>') =>  (ret `gslist-of')
 -- Method: peek-devices
     Lists all currently registered input devices

    DEVICE-MANAGER
          a `<clutter-device-manager>'

    RET
          a pointer to the internal list of `<clutter-input-device>'
          objects.  The returned list is owned by the
          `<clutter-device-manager>' and should never be modified or
          freed.


     Since 1.2


 -- Function: clutter-device-manager-get-device
          (self `<clutter-device-manager>') (device_id `int') => 
          (ret `<clutter-input-device*>')
 -- Method: get-device
     Retrieves the `<clutter-input-device>' with the given DEVICE-ID

    DEVICE-MANAGER
          a `<clutter-device-manager>'

    DEVICE-ID
          the integer id of a device

    RET
          a `<clutter-input-device>' or ``#f''. The returned device is
          owned by the `<clutter-device-manager>' and should never be
          modified or freed.


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterDragAction,  Next: ClutterDropAction,  Prev: ClutterDeviceManager,  Up: Top

30 ClutterDragAction
********************

Action enabling dragging on actors

30.1 Overview
=============

`<clutter-drag-action>' is a sub-class of `<clutter-action>' that
implements all the necessary logic for dragging actors.

   The simplest usage of `<clutter-drag-action>' consists in adding it
to a `<clutter-actor>' and setting it as reactive; for instance, the
following code:


       clutter_actor_add_action (actor, clutter_drag_action_new ());
       clutter_actor_set_reactive (actor, TRUE);

   will automatically result in the actor moving to follow the pointer
whenever the pointer's button is pressed over the actor and moved across
the stage.

   The `<clutter-drag-action>' will signal the begin and the end of a
dragging through the `<"drag-begin">' and `<"drag-end">' signals,
respectively. Each pointer motion during a drag will also result in the
`<"drag-motion">' signal to be emitted.

   It is also possible to set another `<clutter-actor>' as the dragged
actor by calling `clutter-drag-action-set-drag-handle' from within a
handle of the `<"drag-begin">' signal. The drag handle must be parented
and exist between the emission of `<"drag-begin">' and `<"drag-end">'.


   The example program above allows dragging the rectangle around the
stage using a `<clutter-drag-action>'. When pressing the "Shift") key
the actor that is going to be dragged is a separate rectangle, and when
the drag ends, the original rectangle will be animated to the final
coordinates.

   `<clutter-drag-action>' is available since Clutter 1.4

30.2 Usage
==========

 -- Function: clutter-drag-action-new =>  (ret `<clutter-action>')
     Creates a new `<clutter-drag-action>' instance

    RET
          the newly created `<clutter-drag-action>'


     Since 1.4


 -- Function: clutter-drag-action-set-drag-handle
          (self `<clutter-drag-action>') (handle `<clutter-actor>')
 -- Method: set-drag-handle
     Sets the actor to be used as the drag handle.

    ACTION
          a `<clutter-drag-action>'

    HANDLE
          a `<clutter-actor>', or ``#f'' to unset.


     Since 1.4


 -- Function: clutter-drag-action-get-drag-handle
          (self `<clutter-drag-action>') =>  (ret `<clutter-actor>')
 -- Method: get-drag-handle
     Retrieves the drag handle set by
     `clutter-drag-action-set-drag-handle'

    ACTION
          a `<clutter-drag-action>'

    RET
          a `<clutter-actor>', used as the drag handle, or ``#f'' if
          none was set.


     Since 1.4


 -- Function: clutter-drag-action-set-drag-axis
          (self `<clutter-drag-action>') (axis `<clutter-drag-axis>')
 -- Method: set-drag-axis
     Restricts the dragging action to a specific axis

    ACTION
          a `<clutter-drag-action>'

    AXIS
          the axis to constraint the dragging to


     Since 1.4


 -- Function: clutter-drag-action-get-drag-axis
          (self `<clutter-drag-action>') =>  (ret `<clutter-drag-axis>')
 -- Method: get-drag-axis
     Retrieves the axis constraint set by
     `clutter-drag-action-set-drag-axis'

    ACTION
          a `<clutter-drag-action>'

    RET
          the axis constraint


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterDropAction,  Next: ClutterEffect,  Prev: ClutterDragAction,  Up: Top

31 ClutterDropAction
********************

An action for drop targets

31.1 Overview
=============

`<clutter-drop-action>' is a `<clutter-action>' that allows a
`<clutter-actor>' implementation to control what happens when an actor
dragged using a `<clutter-drag-action>' crosses the target area or when
a dragged actor is released (or "dropped") on the target area.

   A trivial use of `<clutter-drop-action>' consists in connecting to
the `<"drop">' signal and handling the drop from there, for instance:


       ClutterAction *action = clutter_drop_action ();

       g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL);
       clutter_actor_add_action (an_actor, action);

   The `<"can-drop">' can be used to control whether the `<"drop">'
signal is going to be emitted; returning ``#f'' from a handler
connected to the `<"can-drop">' signal will cause the `<"drop">' signal
to be skipped when the input device button is released.


   It's important to note that `<clutter-drop-action>' will only work
with actors dragged using `<clutter-drag-action>'.

   `<clutter-drop-action>' is available since Clutter 1.8

31.2 Usage
==========

 -- Function: clutter-drop-action-new =>  (ret `<clutter-action>')
     Creates a new `<clutter-drop-action>'.

     Use `clutter-actor-add-action' to add the action to a
     `<clutter-actor>'.

    RET
          the newly created `<clutter-drop-action>'


     Since 1.8



File: guile-gnome-clutter.info,  Node: ClutterEffect,  Next: Events,  Prev: ClutterDropAction,  Up: Top

32 ClutterEffect
****************

Base class for actor effects

32.1 Overview
=============

The `<clutter-effect>' class provides a default type and API for
creating effects for generic actors.

   Effects are a `<clutter-actor-meta>' sub-class that modify the way
an actor is painted in a way that is not part of the actor's
implementation.

   Effects should be the preferred way to affect the paint sequence of
an actor without sub-classing the actor itself and overriding the
`<"paint">' virtual function.

32.2 Implementing a ClutterEffect
=================================

Creating a sub-class of `<clutter-effect>' requires overriding the
‘paint’ method. The implementation of the function should look
something like this:


     void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags)
     {
       /&#x002A; Set up initialisation of the paint such as binding a
          CoglOffscreen or other operations &#x002A;/

       /&#x002A; Chain to the next item in the paint sequence. This will either call
          ‘paint’ on the next effect or just paint the actor if this is
          the last effect. &#x002A;/
       ClutterActor *actor =
         clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect));
       clutter_actor_continue_paint (actor);

       /&#x002A; perform any cleanup of state, such as popping the
          CoglOffscreen &#x002A;/
     }

   The effect can optionally avoid calling
`clutter-actor-continue-paint' to skip any further stages of the paint
sequence. This is useful for example if the effect contains a cached
image of the actor. In that case it can optimise painting by avoiding
the actor paint and instead painting the cached image. The
`CLUTTER_EFFECT_PAINT_ACTOR_DIRTY' flag is useful in this case.
Clutter will set this flag when a redraw has been queued on the actor
since it was last painted. The effect can use this information to decide
if the cached image is still valid.

   The ‘paint’ virtual was added in Clutter 1.8. Prior to that there
were two separate functions as follows.

   * ``pre-paint'', which is called before painting the
     `<clutter-actor>'.

   * ``post-paint'', which is called after painting the
     `<clutter-actor>'.


   The ``pre-paint'' function was used to set up the `<clutter-effect>'
right before the `<clutter-actor>''s paint sequence. This function can
fail, and return ``#f''; in that case, no ``post-paint'' invocation
will follow.

   The ``post-paint'' function was called after the `<clutter-actor>''s
paint sequence.

   With these two functions it is not possible to skip the rest of the
paint sequence. The default implementation of the ‘paint’ virtual calls
`pre-paint', `clutter-actor-continue-paint' and then `post-paint' so
that existing actors that aren't using the paint virtual will continue
to work. New actors using the paint virtual do not need to implement
pre or post paint.

   The example below creates two rectangles: one will be painted
"behind" the actor, while another will be painted "on top" of the
actor. The ``set-actor'' implementation will create the two materials
used for the two different rectangles; the ``paint'' function will
paint the first material using `cogl-rectangle', before continuing and
then it will paint paint the second material after.


      typedef struct {
        ClutterEffect parent_instance;

        CoglHandle rect_1;
        CoglHandle rect_2;
      } MyEffect;

      typedef struct _ClutterEffectClass MyEffectClass;

      G_DEFINE_TYPE (MyEffect, my_effect, CLUTTER_TYPE_EFFECT);

      static void
      my_effect_set_actor (ClutterActorMeta *meta,
                           ClutterActor     *actor)
      {
        MyEffect *self = MY_EFFECT (meta);

        /&#x002A; Clear the previous state &#x002A;/
        if (self->rect_1)
          {
            cogl_handle_unref (self->rect_1);
            self->rect_1 = NULL;
          }

        if (self->rect_2)
          {
            cogl_handle_unref (self->rect_2);
            self->rect_2 = NULL;
          }

        /&#x002A; Maintain a pointer to the actor &#x002A;
        self->actor = actor;

        /&#x002A; If we've been detached by the actor then we should
         &#x002A; just bail out here
         &#x002A;/
        if (self->actor == NULL)
          return;

        /&#x002A; Create a red material &#x002A;/
        self->rect_1 = cogl_material_new ();
        cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0);

        /&#x002A; Create a green material &#x002A;/
        self->rect_2 = cogl_material_new ();
        cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0);
      }

      static gboolean
      my_effect_paint (ClutterEffect *effect)
      {
        MyEffect *self = MY_EFFECT (effect);
        gfloat width, height;

        clutter_actor_get_size (self->actor, &width, &height);

        /&#x002A; Paint the first rectangle in the upper left quadrant &#x002A;/
        cogl_set_source (self->rect_1);
        cogl_rectangle (0, 0, width / 2, height / 2);

        /&#x002A; Continue to the rest of the paint sequence &#x002A;/
        clutter_actor_continue_paint (self->actor);

        /&#x002A; Paint the second rectangle in the lower right quadrant &#x002A;/
        cogl_set_source (self->rect_2);
        cogl_rectangle (width / 2, height / 2, width, height);
      }

      static void
      my_effect_class_init (MyEffectClass *klass)
      {
        ClutterActorMetaClas *meta_class = CLUTTER_ACTOR_META_CLASS (klass);

        meta_class->set_actor = my_effect_set_actor;

        klass->paint = my_effect_paint;
      }

   `<clutter-effect>' is available since Clutter 1.4

32.3 Usage
==========

 -- Function: clutter-effect-queue-repaint (self `<clutter-effect>')
 -- Method: queue-repaint
     Queues a repaint of the effect. The effect can detect when the
     ‘paint’ method is called as a result of this function because it
     will not have the `CLUTTER_EFFECT_PAINT_ACTOR_DIRTY' flag set. In
     that case the effect is free to assume that the actor has not
     changed its appearance since the last time it was painted so it
     doesn't need to call `clutter-actor-continue-paint' if it can draw
     a cached image.  This is mostly intended for effects that are
     using a `CoglOffscreen' to redirect the actor (such as
     `ClutterOffscreenEffect'). In that case the effect can save a bit
     of rendering time by painting the cached texture without causing
     the entire actor to be painted.

     This function can be used by effects that have their own animatable
     parameters. For example, an effect which adds a varying degree of
     a red tint to an actor by redirecting it through a CoglOffscreen
     might have a property to specify the level of tint. When this
     value changes, the underlying actor doesn't need to be redrawn so
     the effect can call `clutter-effect-queue-repaint' to make sure
     the effect is repainted.

     Note however that modifying the position of the parent of an actor
     may change the appearance of the actor because its transformation
     matrix would change. In this case a redraw wouldn't be queued on
     the actor itself so the `CLUTTER_EFFECT_PAINT_ACTOR_DIRTY' would
     still not be set. The effect can detect this case by keeping track
     of the last modelview matrix that was used to render the actor and
     veryifying that it remains the same in the next paint.

     Any other effects that are layered on top of the passed in effect
     will still be passed the `CLUTTER_EFFECT_PAINT_ACTOR_DIRTY' flag.
     If anything queues a redraw on the actor without specifying an
     effect or with an effect that is lower in the chain of effects
     than this one then that will override this call. In that case this
     effect will instead be called with the
     `CLUTTER_EFFECT_PAINT_ACTOR_DIRTY' flag set.

    EFFECT
          A `<clutter-effect>' which needs redrawing


     Since 1.8



File: guile-gnome-clutter.info,  Node: Events,  Next: Features,  Prev: ClutterEffect,  Up: Top

33 Events
*********

User and window system events

33.1 Overview
=============

Windowing events handled by Clutter.

   The events usually come from the windowing backend, but can also be
synthesized by Clutter itself or by the application code.

33.2 Usage
==========

 -- Function: clutter-event-new (type `<clutter-event-type>') => 
          (ret `<clutter-event>')
     Creates a new `<clutter-event>' of the specified type.

    TYPE
          The type of event.

    RET
          A newly allocated `<clutter-event>'.



 -- Function: clutter-event-type (self `<clutter-event>') => 
          (ret `<clutter-event-type>')
 -- Method: type
     Retrieves the type of the event.

    EVENT
          a `<clutter-event>'

    RET
          a `<clutter-event-type>'



 -- Function: clutter-event-set-coords (self `<clutter-event>')
          (x `float') (y `float')
 -- Method: set-coords
     Sets the coordinates of the EVENT.

    EVENT
          a `<clutter-event>'

    X
          the X coordinate of the event

    Y
          the Y coordinate of the event


     Since 1.8


 -- Function: clutter-event-get-coords (self `<clutter-event>') => 
          (x `float') (y `float')
 -- Method: get-coords
     Retrieves the coordinates of EVENT and puts them into X and Y.

    EVENT
          a `<clutter-event>'

    X
          return location for the X coordinate, or ``#f''.

    Y
          return location for the Y coordinate, or ``#f''.


     Since 0.4


 -- Function: clutter-event-set-state (self `<clutter-event>')
          (state `<clutter-modifier-type>')
 -- Method: set-state
     Sets the modifier state of the event.

    EVENT
          a `<clutter-event>'

    STATE
          the modifier state to set


     Since 1.8


 -- Function: clutter-event-get-state (self `<clutter-event>') => 
          (ret `<clutter-modifier-type>')
 -- Method: get-state
     Retrieves the modifier state of the event.

    EVENT
          a `<clutter-event>'

    RET
          the modifier state parameter, or 0


     Since 0.4


 -- Function: clutter-event-set-time (self `<clutter-event>')
          (time_ `unsigned-int32')
 -- Method: set-time
     Sets the time of the event.

    EVENT
          a `<clutter-event>'

    TIME
          the time of the event


     Since 1.8


 -- Function: clutter-event-get-time (self `<clutter-event>') => 
          (ret `unsigned-int32')
 -- Method: get-time
     Retrieves the time of the event.

    EVENT
          a `<clutter-event>'

    RET
          the time of the event, or `CLUTTER_CURRENT_TIME'


     Since 0.4


 -- Function: clutter-event-set-source (self `<clutter-event>')
          (actor `<clutter-actor>')
 -- Method: set-source
     Sets the source `<clutter-actor>' of EVENT.

    EVENT
          a `<clutter-event>'

    ACTOR
          a `<clutter-actor>', or ``#f''.


     Since 1.8


 -- Function: clutter-event-get-source (self `<clutter-event>') => 
          (ret `<clutter-actor>')
 -- Method: get-source
     Retrieves the source `<clutter-actor>' the event originated from,
     or NULL if the event has no source.

    EVENT
          a `<clutter-event>'

    RET
          a `<clutter-actor>'.


     Since 0.6


 -- Function: clutter-event-set-stage (self `<clutter-event>')
          (stage `<clutter-stage>')
 -- Method: set-stage
     Sets the source `<clutter-stage>' of the event.

    EVENT
          a `<clutter-event>'

    STAGE
          a `<clutter-stage>', or ``#f''.


     Since 1.8


 -- Function: clutter-event-get-stage (self `<clutter-event>') => 
          (ret `<clutter-stage>')
 -- Method: get-stage
     Retrieves the source `<clutter-stage>' the event originated for, or
     ``#f'' if the event has no stage.

    EVENT
          a `<clutter-event>'

    RET
          a `<clutter-stage>'.


     Since 0.8


 -- Function: clutter-event-set-flags (self `<clutter-event>')
          (flags `<clutter-event-flags>')
 -- Method: set-flags
     Sets the `<clutter-event-flags>' of EVENT

    EVENT
          a `<clutter-event>'

    FLAGS
          a binary OR of `<clutter-event-flags>' values


     Since 1.8


 -- Function: clutter-event-get-flags (self `<clutter-event>') => 
          (ret `<clutter-event-flags>')
 -- Method: get-flags
     Retrieves the `<clutter-event-flags>' of EVENT

    EVENT
          a `<clutter-event>'

    RET
          the event flags


     Since 1.0


 -- Function: clutter-event-get-event-sequence (self `<clutter-event>')
          =>  (ret `<clutter-event-sequence*>')
 -- Method: get-event-sequence
     Retrieves the `<clutter-event-sequence>' of EVENT.

    EVENT
          a `<clutter-event>' of type `CLUTTER_TOUCH_BEGIN',
          `CLUTTER_TOUCH_UPDATE', `CLUTTER_TOUCH_END', or
          `CLUTTER_TOUCH_CANCEL'

    RET
          the event sequence, or ``#f''.


     Since 1.10


 -- Function: clutter-event-get =>  (ret `<clutter-event>')
     Pops an event off the event queue. Applications should not need to
     call this.

    RET
          A `<clutter-event>' or NULL if queue empty


     Since 0.4


 -- Function: clutter-event-peek =>  (ret `<clutter-event>')
     Returns a pointer to the first event from the event queue but does
     not remove it.

    RET
          A `<clutter-event>' or NULL if queue empty.


     Since 0.4


 -- Function: clutter-event-put (self `<clutter-event>')
 -- Method: put
     Puts a copy of the event on the back of the event queue. The event
     will have the `CLUTTER_EVENT_FLAG_SYNTHETIC' flag set. If the
     source is set event signals will be emitted for this source and
     capture/bubbling for its ancestors. If the source is not set it
     will be generated by picking or use the actor that currently has
     keyboard focus

    EVENT
          a `<clutter-event>'


     Since 0.6


 -- Function: clutter-events-pending =>  (ret `bool')
     Checks if events are pending in the event queue.

    RET
          TRUE if there are pending events, FALSE otherwise.


     Since 0.4


 -- Function: clutter-event-set-button (self `<clutter-event>')
          (button `unsigned-int32')
 -- Method: set-button
     Sets the button number of EVENT

    EVENT
          a `<clutter-event>' or type `CLUTTER_BUTTON_PRESS' or of type
          `CLUTTER_BUTTON_RELEASE'

    BUTTON
          the button number


     Since 1.8


 -- Function: clutter-event-get-button (self `<clutter-event>') => 
          (ret `unsigned-int32')
 -- Method: get-button
     Retrieves the button number of EVENT

    EVENT
          a `<clutter-event>' of type `CLUTTER_BUTTON_PRESS' or of type
          `CLUTTER_BUTTON_RELEASE'

    RET
          the button number


     Since 1.0


 -- Function: clutter-event-get-click-count (self `<clutter-event>')
          =>  (ret `unsigned-int')
 -- Method: get-click-count
     Retrieves the number of clicks of EVENT

    EVENT
          a `<clutter-event>' of type `CLUTTER_BUTTON_PRESS' or of type
          `CLUTTER_BUTTON_RELEASE'

    RET
          the click count


     Since 1.0


 -- Function: clutter-event-set-key-symbol (self `<clutter-event>')
          (key_sym `unsigned-int')
 -- Method: set-key-symbol
     Sets the key symbol of EVENT.

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or
          `CLUTTER_KEY_RELEASE'

    KEY-SYM
          the key symbol representing the key


     Since 1.8


 -- Function: clutter-event-get-key-symbol (self `<clutter-event>') => 
          (ret `unsigned-int')
 -- Method: get-key-symbol
     Retrieves the key symbol of EVENT

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or of type
          `CLUTTER_KEY_RELEASE'

    RET
          the key symbol representing the key


     Since 1.0


 -- Function: clutter-event-set-key-code (self `<clutter-event>')
          (key_code `unsigned-int16')
 -- Method: set-key-code
     Sets the keycode of the EVENT.

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or
          `CLUTTER_KEY_RELEASE'

    KEY-CODE
          the keycode representing the key


     Since 1.8


 -- Function: clutter-event-get-key-code (self `<clutter-event>') => 
          (ret `unsigned-int16')
 -- Method: get-key-code
     Retrieves the keycode of the key that caused EVENT

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or of type
          `CLUTTER_KEY_RELEASE'

    RET
          The keycode representing the key


     Since 1.0


 -- Function: clutter-event-set-key-unicode (self `<clutter-event>')
          (key_unicode `unsigned-int32')
 -- Method: set-key-unicode
     Sets the Unicode value of EVENT.

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or
          `CLUTTER_KEY_RELEASE'

    KEY-UNICODE
          the Unicode value representing the key


     Since 1.8


 -- Function: clutter-event-get-key-unicode (self `<clutter-event>')
          =>  (ret `unsigned-int32')
 -- Method: get-key-unicode
     Retrieves the unicode value for the key that caused KEYEV.

    EVENT
          a `<clutter-event>' of type `CLUTTER_KEY_PRESS' or
          `CLUTTER_KEY_RELEASE'

    RET
          The unicode value representing the key



 -- Function: clutter-keysym-to-unicode (keyval `unsigned-int') => 
          (ret `unsigned-int32')
     Converts KEYVAL from a Clutter key symbol to the corresponding
     ISO10646 (Unicode) character.

    KEYVAL
          a key symbol

    RET
          a Unicode character, or 0 if there is no corresponding
          character.



 -- Function: clutter-unicode-to-keysym (wc `unsigned-int32') => 
          (ret `unsigned-int')
     Convert from a ISO10646 character to a key symbol.

    WC
          a ISO10646 encoded character

    RET
          the corresponding Clutter key symbol, if one exists. or, if
          there is no corresponding symbol, wc | 0x01000000


     Since 1.10


 -- Function: clutter-event-set-related (self `<clutter-event>')
          (actor `<clutter-actor>')
 -- Method: set-related
     Sets the related actor of a crossing event

    EVENT
          a `<clutter-event>' of type `CLUTTER_ENTER' or `CLUTTER_LEAVE'

    ACTOR
          a `<clutter-actor>' or ``#f''.


     Since 1.8


 -- Function: clutter-event-get-related (self `<clutter-event>') => 
          (ret `<clutter-actor>')
 -- Method: get-related
     Retrieves the related actor of a crossing event.

    EVENT
          a `<clutter-event>' of type `CLUTTER_ENTER' or of type
          `CLUTTER_LEAVE'

    RET
          the related `<clutter-actor>', or ``#f''.


     Since 1.0


 -- Function: clutter-event-set-scroll-direction
          (self `<clutter-event>')
          (direction `<clutter-scroll-direction>')
 -- Method: set-scroll-direction
     Sets the direction of the scrolling of EVENT

    EVENT
          a `<clutter-event>'

    DIRECTION
          the scrolling direction


     Since 1.8


 -- Function: clutter-event-get-scroll-delta (self `<clutter-event>')
          =>  (dx `double') (dy `double')
 -- Method: get-scroll-delta
     Retrieves the precise scrolling information of EVENT.

     The EVENT has to have a `<clutter-scroll-event.direction>' value
     of `CLUTTER_SCROLL_SMOOTH'.

    EVENT
          a `<clutter-event>' of type `CLUTTER_SCROLL'

    DX
          return location for the delta on the horizontal axis.

    DY
          return location for the delta on the vertical axis.


     Since 1.10


 -- Function: clutter-event-set-scroll-delta (self `<clutter-event>')
          (dx `double') (dy `double')
 -- Method: set-scroll-delta
     Sets the precise scrolling information of EVENT.

    EVENT
          a `<clutter-event>' of type `CLUTTER_SCROLL'

    DX
          delta on the horizontal axis

    DY
          delta on the vertical axis


     Since 1.10


 -- Function: clutter-event-set-device (self `<clutter-event>')
          (device `<clutter-input-device*>')
 -- Method: set-device
     Sets the device for EVENT.

    EVENT
          a `<clutter-event>'

    DEVICE
          a `<clutter-input-device>', or ``#f''.


     Since 1.6


 -- Function: clutter-event-get-device (self `<clutter-event>') => 
          (ret `<clutter-input-device*>')
 -- Method: get-device
     Retrieves the `<clutter-input-device>' for the event.

     The `<clutter-input-device>' structure is completely opaque and
     should be cast to the platform-specific implementation.

    EVENT
          a `<clutter-event>'

    RET
          the `<clutter-input-device>' or ``#f''. The returned device
          is owned by the `<clutter-event>' and it should not be
          unreferenced.


     Since 1.0


 -- Function: clutter-event-set-source-device (self `<clutter-event>')
          (device `<clutter-input-device*>')
 -- Method: set-source-device
     Sets the source `<clutter-input-device>' for EVENT.

     The `<clutter-event>' must have been created using
     `clutter-event-new'.

    EVENT
          a `<clutter-event>'

    DEVICE
          a `<clutter-input-device>'.


     Since 1.8


 -- Function: clutter-event-get-source-device (self `<clutter-event>')
          =>  (ret `<clutter-input-device*>')
 -- Method: get-source-device
     Retrieves the hardware device that originated the event.

     If you need the virtual device, use `clutter-event-get-device'.

     If no hardware device originated this event, this function will
     return the same device as `clutter-event-get-device'.

    EVENT
          a `<clutter-event>'

    RET
          a pointer to a `<clutter-input-device>' or ``#f''.


     Since 1.6


 -- Function: clutter-event-get-device-id (self `<clutter-event>') => 
          (ret `int')
 -- Method: get-device-id
     Retrieves the events device id if set.

    EVENT
          a clutter event

    RET
          A unique identifier for the device or -1 if the event has no
          specific device set.



 -- Function: clutter-event-get-device-type (self `<clutter-event>')
          =>  (ret `<clutter-input-device-type>')
 -- Method: get-device-type
     Retrieves the type of the device for EVENT

    EVENT
          a `<clutter-event>'

    RET
          the `<clutter-input-device-type>' for the device, if any is
          set


     Since 1.0


 -- Function: clutter-get-current-event-time =>  (ret `unsigned-int32')
     Retrieves the timestamp of the last event, if there is an event or
     if the event has a timestamp.

    RET
          the event timestamp, or `CLUTTER_CURRENT_TIME'


     Since 1.0


 -- Function: clutter-get-current-event =>  (ret `<clutter-event>')
     If an event is currently being processed, return that event. This
     function is intended to be used to access event state that might
     not be exposed by higher-level widgets. For example, to get the
     key modifier state from a Button 'clicked' event.

    RET
          The current ClutterEvent, or ``#f'' if none.


     Since 1.2



File: guile-gnome-clutter.info,  Node: Features,  Next: ClutterFixedLayout,  Prev: Events,  Up: Top

34 Features
***********

Run-time detection of Clutter features

34.1 Overview
=============

Parts of Clutter depend on the underlying platform, including the
capabilities of the backend used and the OpenGL features exposed through
the Clutter and COGL API.

   It is possible to ask whether Clutter has support for specific
features at run-time.

   See also `cogl-get-features' and `<cogl-feature-flags>'

34.2 Usage
==========

 -- Function: clutter-feature-available
          (feature `<clutter-feature-flags>') =>  (ret `bool')
     Checks whether FEATURE is available. FEATURE can be a logical OR
     of `<clutter-feature-flags>'.

    FEATURE
          a `<clutter-feature-flags>'

    RET
          ``#t'' if a feature is available


     Since 0.1.1


 -- Function: clutter-feature-get-all => 
          (ret `<clutter-feature-flags>')
     Returns all the supported features.

    RET
          a logical OR of all the supported features.


     Since 0.1.1



File: guile-gnome-clutter.info,  Node: ClutterFixedLayout,  Next: ClutterFlowLayout,  Prev: Features,  Up: Top

35 ClutterFixedLayout
*********************

A fixed layout manager

35.1 Overview
=============

`<clutter-fixed-layout>' is a layout manager implementing the same
layout policies as `<clutter-group>'.

   `<clutter-fixed-layout>' is available since Clutter 1.2

35.2 Usage
==========

 -- Function: clutter-fixed-layout-new => 
          (ret `<clutter-layout-manager>')
     Creates a new `<clutter-fixed-layout>'

    RET
          the newly created `<clutter-fixed-layout>'


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterFlowLayout,  Next: ClutterGestureAction,  Prev: ClutterFixedLayout,  Up: Top

36 ClutterFlowLayout
********************

A reflowing layout manager

36.1 Overview
=============

`<clutter-flow-layout>' is a layout manager which implements the
following policy:

   *   *   *   *
   the preferred natural size depends on the value of the
`<"orientation">' property; the layout will try to maintain all its
children on a single row or column;

   if either the width or the height allocated are smaller than the
preferred ones, the layout will wrap; in this case, the preferred height
or width, respectively, will take into account the amount of columns and
rows;

   each line (either column or row) in reflowing will have the size of
the biggest cell on that line; if the `<"homogeneous">' property is set
to ``#f'' the actor will be allocated within that area, and if set to
``#t'' instead the actor will be given exactly that area;

   the size of the columns or rows can be controlled for both minimum
and maximum; the spacing can also be controlled in both columns and
rows.

   (The missing figure, flow-layout-image

   The image shows a `<clutter-flow-layout>' with the `<"orientation">'
propert set to `CLUTTER_FLOW_HORIZONTAL'.

   `<clutter-flow-layout>' is available since Clutter 1.2

36.2 Usage
==========

 -- Function: clutter-flow-layout-new
          (orientation `<clutter-flow-orientation>') => 
          (ret `<clutter-layout-manager>')
     Creates a new `<clutter-flow-layout>' with the given ORIENTATION

    ORIENTATION
          the orientation of the flow layout

    RET
          the newly created `<clutter-flow-layout>'


     Since 1.2


 -- Function: clutter-flow-layout-set-homogeneous
          (self `<clutter-flow-layout>') (homogeneous `bool')
 -- Method: set-homogeneous
     Sets whether the LAYOUT should allocate the same space for each
     child

    LAYOUT
          a `<clutter-flow-layout>'

    HOMOGENEOUS
          whether the layout should be homogeneous or not


     Since 1.2


 -- Function: clutter-flow-layout-get-homogeneous
          (self `<clutter-flow-layout>') =>  (ret `bool')
 -- Method: get-homogeneous
     Retrieves whether the LAYOUT is homogeneous

    LAYOUT
          a `<clutter-flow-layout>'

    RET
          ``#t'' if the `<clutter-flow-layout>' is homogeneous


     Since 1.2


 -- Function: clutter-flow-layout-set-orientation
          (self `<clutter-flow-layout>')
          (orientation `<clutter-flow-orientation>')
 -- Method: set-orientation
     Sets the orientation of the flow layout

     The orientation controls the direction used to allocate the
     children: either horizontally or vertically. The orientation also
     controls the direction of the overflowing

    LAYOUT
          a `<clutter-flow-layout>'

    ORIENTATION
          the orientation of the layout


     Since 1.2


 -- Function: clutter-flow-layout-set-row-spacing
          (self `<clutter-flow-layout>') (spacing `float')
 -- Method: set-row-spacing
     Sets the spacing between rows, in pixels

    LAYOUT
          a `<clutter-flow-layout>'

    SPACING
          the space between rows


     Since 1.2


 -- Function: clutter-flow-layout-get-row-spacing
          (self `<clutter-flow-layout>') =>  (ret `float')
 -- Method: get-row-spacing
     Retrieves the spacing between rows

    LAYOUT
          a `<clutter-flow-layout>'

    RET
          the spacing between rows of the `<clutter-flow-layout>', in
          pixels


     Since 1.2


 -- Function: clutter-flow-layout-set-row-height
          (self `<clutter-flow-layout>') (min_height `float')
          (max_height `float')
 -- Method: set-row-height
     Sets the minimum and maximum heights that a row can have

    LAYOUT
          a `<clutter-flow-layout>'

    MIN-HEIGHT
          the minimum height of a row

    MAX-HEIGHT
          the maximum height of a row


     Since 1.2


 -- Function: clutter-flow-layout-get-row-height
          (self `<clutter-flow-layout>') =>  (min_height `float')
          (max_height `float')
 -- Method: get-row-height
     Retrieves the minimum and maximum row heights

    LAYOUT
          a `<clutter-flow-layout>'

    MIN-HEIGHT
          return location for the minimum row height, or ``#f''.

    MAX-HEIGHT
          return location for the maximum row height, or ``#f''.


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterGestureAction,  Next: ClutterInputDevice,  Prev: ClutterFlowLayout,  Up: Top

37 ClutterGestureAction
***********************

Action for gesture gestures

37.1 Overview
=============

`<clutter-gesture-action>' is a sub-class of `<clutter-action>' that
implements the logic for recognizing gesture gestures. It listens for
low level events such as `<clutter-button-event>' and
`<clutter-motion-event>' on the stage to raise the `<"gesture-begin">',
`<"gesture-progress">', and * `<"gesture-end">' signals.

   To use `<clutter-gesture-action>' you just need to apply it to a
`<clutter-actor>' using `clutter-actor-add-action' and connect to the
signals:


       ClutterAction *action = clutter_gesture_action_new ();

       clutter_actor_add_action (actor, action);

       g_signal_connect (action, "gesture-begin", G_CALLBACK (on_gesture_begin), NULL);
       g_signal_connect (action, "gesture-progress", G_CALLBACK (on_gesture_progress), NULL);
       g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);

37.2 Usage
==========

 -- Function: clutter-gesture-action-new =>  (ret `<clutter-action>')
     Creates a new `<clutter-gesture-action>' instance.

    RET
          the newly created `<clutter-gesture-action>'


     Since 1.8



File: guile-gnome-clutter.info,  Node: ClutterImage,  Next: Value intervals,  Prev: ClutterInputDevice,  Up: Top

38 ClutterImage
***************

Image data content

38.1 Overview
=============

`<clutter-image>' is a `<clutter-content>' implementation that displays
image data.


   `<clutter-image>' is available since Clutter 1.10.

38.2 Usage
==========

 -- Function: clutter-image-new =>  (ret `<clutter-content>')
     Creates a new `<clutter-image>' instance.

    RET
          the newly created `<clutter-image>' instance. Use
          `g-object-unref' when done.


     Since 1.10



File: guile-gnome-clutter.info,  Node: ClutterInputDevice,  Next: ClutterImage,  Prev: ClutterGestureAction,  Up: Top

39 ClutterInputDevice
*********************

An input device managed by Clutter

39.1 Overview
=============

`<clutter-input-device>' represents an input device known to Clutter.

   The `<clutter-input-device>' class holds the state of the device,
but its contents are usually defined by the Clutter backend in use.

39.2 Usage
==========

 -- Function: clutter-input-device-get-device-id
          (self `<clutter-input-device*>') =>  (ret `int')
     Retrieves the unique identifier of DEVICE

    DEVICE
          a `<clutter-input-device>'

    RET
          the identifier of the device


     Since 1.0


 -- Function: clutter-input-device-get-has-cursor
          (self `<clutter-input-device*>') =>  (ret `bool')
     Retrieves whether DEVICE has a pointer that follows the device
     motion.

    DEVICE
          a `<clutter-input-device>'

    RET
          ``#t'' if the device has a cursor


     Since 1.6


 -- Function: clutter-input-device-set-enabled
          (self `<clutter-input-device*>') (enabled `bool')
     Enables or disables a `<clutter-input-device>'.

     Only devices with a `<"device-mode">' property set to
     `CLUTTER_INPUT_MODE_SLAVE' or `CLUTTER_INPUT_MODE_FLOATING' can be
     disabled.

    DEVICE
          a `<clutter-input-device>'

    ENABLED
          ``#t'' to enable the DEVICE


     Since 1.6


 -- Function: clutter-input-device-get-enabled
          (self `<clutter-input-device*>') =>  (ret `bool')
     Retrieves whether DEVICE is enabled.

    DEVICE
          a `<clutter-input-device>'

    RET
          ``#t'' if the device is enabled


     Since 1.6


 -- Function: clutter-input-device-get-n-keys
          (self `<clutter-input-device*>') =>  (ret `unsigned-int')
     Retrieves the number of keys registered for DEVICE.

    DEVICE
          a `<clutter-input-device>'

    RET
          the number of registered keys


     Since 1.6


 -- Function: clutter-input-device-set-key
          (self `<clutter-input-device*>') (index_ `unsigned-int')
          (keyval `unsigned-int') (modifiers `<clutter-modifier-type>')
     Sets the keyval and modifiers at the given INDEX for DEVICE.

     Clutter will use the keyval and modifiers set when filling out an
     event coming from the same input device.

    DEVICE
          a `<clutter-input-device>'

    INDEX
          the index of the key

    KEYVAL
          the keyval

    MODIFIERS
          a bitmask of modifiers


     Since 1.6


 -- Function: clutter-input-device-get-key
          (self `<clutter-input-device*>') (index_ `unsigned-int') => 
          (ret `bool') (keyval `unsigned-int')
          (modifiers `<clutter-modifier-type>')
     Retrieves the key set using `clutter-input-device-set-key'

    DEVICE
          a `<clutter-input-device>'

    INDEX
          the index of the key

    KEYVAL
          return location for the keyval at INDEX.

    MODIFIERS
          return location for the modifiers at INDEX.

    RET
          ``#t'' if a key was set at the given index


     Since 1.6


 -- Function: clutter-input-device-get-n-axes
          (self `<clutter-input-device*>') =>  (ret `unsigned-int')
     Retrieves the number of axes available on DEVICE.

    DEVICE
          a `<clutter-input-device>'

    RET
          the number of axes on the device


     Since 1.6


 -- Function: clutter-input-device-get-axis
          (self `<clutter-input-device*>') (index_ `unsigned-int') => 
          (ret `<clutter-input-axis>')
     Retrieves the type of axis on DEVICE at the given index.

    DEVICE
          a `<clutter-input-device>'

    INDEX
          the index of the axis

    RET
          the axis type


     Since 1.6


 -- Function: clutter-input-device-get-axis-value
          (self `<clutter-input-device*>')
          (axis `<clutter-input-axis>') =>  (ret `bool')
          (axes `double') (value `double')
     Extracts the value of the given AXIS of a `<clutter-input-device>'
     from an array of axis values.

     An example of typical usage for this function is:


            ClutterInputDevice *device = clutter_event_get_device (event);
            gdouble *axes = clutter_event_get_axes (event, NULL);
            gdouble pressure_value = 0;

            clutter_input_device_get_axis_value (device, axes,
                                                 CLUTTER_INPUT_AXIS_PRESSURE,
                                                 &pressure_value);

    DEVICE
          a `<clutter-input-device>'

    AXES
          an array of axes values, typically coming from
          `clutter-event-get-axes'.

    AXIS
          the axis to extract

    VALUE
          return location for the axis value.

    RET
          ``#t'' if the value was set, and ``#f'' otherwise


     Since 1.6


 -- Function: clutter-input-device-grab
          (self `<clutter-input-device*>') (actor `<clutter-actor>')
     Acquires a grab on ACTOR for the given DEVICE.

     Any event coming from DEVICE will be delivered to ACTOR, bypassing
     the usual event delivery mechanism, until the grab is released by
     calling `clutter-input-device-ungrab'.

     The grab is client-side: even if the windowing system used by the
     Clutter backend has the concept of "device grabs", Clutter will
     not use them.

     Only `<clutter-input-device>' of types `CLUTTER_POINTER_DEVICE'
     and `CLUTTER_KEYBOARD_DEVICE' can hold a grab.

    DEVICE
          a `<clutter-input-device>'

    ACTOR
          a `<clutter-actor>'


     Since 1.10


 -- Function: clutter-input-device-ungrab
          (self `<clutter-input-device*>')
     Releases the grab on the DEVICE, if one is in place.

    DEVICE
          a `<clutter-input-device>'


     Since 1.10



File: guile-gnome-clutter.info,  Node: Value intervals,  Next: ClutterLayoutManager,  Prev: ClutterImage,  Up: Top

40 Value intervals
******************

An object holding an interval of two values

40.1 Overview
=============

`<clutter-interval>' is a simple object that can hold two values
defining an interval. `<clutter-interval>' can hold any value that can
be enclosed inside a `<gvalue>'.

   Once a `<clutter-interval>' for a specific `<g-type>' has been
instantiated the `<"value-type">' property cannot be changed anymore.

   `<clutter-interval>' starts with a floating reference; this means
that any object taking a reference on a `<clutter-interval>' instance
should also take ownership of the interval by using `g-object-ref-sink'.

   `<clutter-interval>' is used by `<clutter-animation>' to define the
interval of values that an implicit animation should tween over.

   `<clutter-interval>' can be subclassed to override the validation
and value computation.

   `<clutter-interval>' is available since Clutter 1.0

40.2 Usage
==========

 -- Function: clutter-interval-new-with-values (gtype `<gtype>')
          (initial `<gvalue>') (final `<gvalue>') => 
          (ret `<clutter-interval>')
     Creates a new `<clutter-interval>' of type GTYPE, between INITIAL
     and FINAL.

     This function is useful for language bindings.

    GTYPE
          the type of the values in the interval

    INITIAL
          a `<gvalue>' holding the initial value of the interval

    FINAL
          a `<gvalue>' holding the final value of the interval

    RET
          the newly created `<clutter-interval>'


     Since 1.0


 -- Function: clutter-interval-clone (self `<clutter-interval>') => 
          (ret `<clutter-interval>')
 -- Method: clone
     Creates a copy of INTERVAL.

    INTERVAL
          a `<clutter-interval>'

    RET
          the newly created `<clutter-interval>'.


     Since 1.0


 -- Function: clutter-interval-get-value-type
          (self `<clutter-interval>') =>  (ret `<gtype>')
 -- Method: get-value-type
     Retrieves the `<g-type>' of the values inside INTERVAL.

    INTERVAL
          a `<clutter-interval>'

    RET
          the type of the value, or G_TYPE_INVALID


     Since 1.0


 -- Function: clutter-interval-set-initial-value
          (self `<clutter-interval>') (value `<gvalue>')
 -- Method: set-initial-value
     Sets the initial value of INTERVAL to VALUE. The value is copied
     inside the `<clutter-interval>'.

     Rename to: clutter_interval_set_initial

    INTERVAL
          a `<clutter-interval>'

    VALUE
          a `<gvalue>'


     Since 1.0


 -- Function: clutter-interval-get-initial-value
          (self `<clutter-interval>') =>  (ret `<gvalue>')
 -- Method: get-initial-value
     Retrieves the initial value of INTERVAL and copies it into VALUE.

     The passed `<gvalue>' must be initialized to the value held by the
     `<clutter-interval>'.

    INTERVAL
          a `<clutter-interval>'

    VALUE
          a `<gvalue>'.


     Since 1.0


 -- Function: clutter-interval-set-final-value
          (self `<clutter-interval>') (value `<gvalue>')
 -- Method: set-final-value
     Sets the final value of INTERVAL to VALUE. The value is copied
     inside the `<clutter-interval>'.

     Rename to: clutter_interval_set_final

    INTERVAL
          a `<clutter-interval>'

    VALUE
          a `<gvalue>'


     Since 1.0


 -- Function: clutter-interval-get-final-value
          (self `<clutter-interval>') =>  (ret `<gvalue>')
 -- Method: get-final-value
     Retrieves the final value of INTERVAL and copies it into VALUE.

     The passed `<gvalue>' must be initialized to the value held by the
     `<clutter-interval>'.

    INTERVAL
          a `<clutter-interval>'

    VALUE
          a `<gvalue>'.


     Since 1.0


 -- Function: clutter-interval-validate (self `<clutter-interval>')
          (pspec `<gparam>') =>  (ret `bool')
 -- Method: validate
     Validates the initial and final values of INTERVAL against a
     `<gparam>'.

    INTERVAL
          a `<clutter-interval>'

    PSPEC
          a `<gparam>'

    RET
          ``#t'' if the `<clutter-interval>' is valid, ``#f'' otherwise


     Since 1.0


 -- Function: clutter-interval-compute (self `<clutter-interval>')
          (factor `double') =>  (ret `<gvalue>')
 -- Method: compute
     Computes the value between the INTERVAL boundaries given the
     progress FACTOR

     Unlike `clutter-interval-compute-value', this function will return
     a const pointer to the computed value

     You should use this function if you immediately pass the computed
     value to another function that makes a copy of it, like
     `g-object-set-property'

    INTERVAL
          a `<clutter-interval>'

    FACTOR
          the progress factor, between 0 and 1

    RET
          a pointer to the computed value, or ``#f'' if the computation
          was not successfull.


     Since 1.4



File: guile-gnome-clutter.info,  Node: ClutterLayoutManager,  Next: ClutterLayoutMeta,  Prev: Value intervals,  Up: Top

41 ClutterLayoutManager
***********************

Layout managers base class

41.1 Overview
=============

`<clutter-layout-manager>' is a base abstract class for layout
managers. A layout manager implements the layouting policy for a
composite or a container actor: it controls the preferred size of the
actor to which it has been paired, and it controls the allocation of its
children.

   Any composite or container `<clutter-actor>' subclass can delegate
the layouting of its children to a `<clutter-layout-manager>'.  Clutter
provides a generic container using `<clutter-layout-manager>' called
`<clutter-box>'.

   Clutter provides some simple `<clutter-layout-manager>' sub-classes,
like `<clutter-flow-layout>' and `<clutter-bin-layout>'.

41.2 Using a Layout Manager inside an Actor
===========================================

In order to use a `<clutter-layout-manager>' inside a `<clutter-actor>'
sub-class you should invoke
`clutter-layout-manager-get-preferred-width' inside the (structname
"ClutterActor") ::`get-preferred-width' virtual function and
`clutter-layout-manager-get-preferred-height' inside the function
implementations. You should also call `clutter-layout-manager-allocate'
inside the implementation of the

   In order to receive notifications for changes in the layout manager
policies you should also connect to the `<"layout-changed">' signal and
queue a relayout on your actor. The following code should be enough if
the actor does not need to perform specific operations whenever a
layout manager changes:


      g_signal_connect_swapped (layout_manager,
                                "layout-changed",
                                G_CALLBACK (clutter_actor_queue_relayout),
                                actor);

41.3 Implementing a ClutterLayoutManager
========================================

The implementation of a layout manager does not differ from the
implementation of the size requisition and allocation bits of
`<clutter-actor>', so you should read the relative documentation for
subclassing ClutterActor.

   The layout manager implementation can hold a back pointer to the
`<clutter-container>' by implementing the ``set-container'' virtual
function. The layout manager should not hold a real reference (i.e.
call `g-object-ref') on the container actor, to avoid reference cycles.

   If a layout manager has properties affecting the layout policies
then it should emit the `<"layout-changed">' signal on itself by using
the `clutter-layout-manager-layout-changed' function whenever one of
these properties changes.

41.4 Animating a ClutterLayoutManager
=====================================

A layout manager is used to let a `<clutter-container>' take complete
ownership over the layout (that is: the position and sizing) of its
children; this means that using the Clutter animation API, like
`clutter-actor-animate', to animate the position and sizing of a child
of a layout manager it is not going to work properly, as the animation
will automatically override any setting done by the layout manager
itself.

   It is possible for a `<clutter-layout-manager>' sub-class to animate
its children layout by using the base class animation support.  The
`<clutter-layout-manager>' animation support consists of three virtual
functions: ``begin-animation'', ``get-animation-progress'' and
``end-animation''.

`GET-ANIMATION-PROGRESS'

`END-ANIMATION'

   This virtual function is invoked when the layout manager should
begin an animation. The implementation should set up the state for the
animation and create the ancillary objects for animating the layout.
The default implementation creates a `<clutter-timeline>' for the given
duration and a `<clutter-alpha>' binding the timeline to the given
easing mode. This function returns a `<clutter-alpha>' which should be
used to control the animation from the caller perspective.

   This virtual function should be invoked when animating a layout
manager.  It returns the progress of the animation, using the same
semantics as the `<"alpha">' value.

   This virtual function is invoked when the animation of a layout
manager ends, and it is meant to be used for bookkeeping the objects
created in the ``begin-animation'' function. The default implementation
will call it implicitly when the timeline is complete.

   The simplest way to animate a layout is to create a
`<clutter-timeline>' inside the ``begin-animation'' virtual function,
along with a `<clutter-alpha>', and for each `<"new-frame">' signal
emission call `clutter-layout-manager-layout-changed', which will cause
a relayout. The `<"completed">' signal emission should cause
`clutter-layout-manager-end-animation' to be called. The default
implementation provided internally by `<clutter-layout-manager>' does
exactly this, so most sub-classes should either not override any
animation-related virtual function or simply override
``begin-animation'' and ``end-animation'' to set up ad hoc state, and
then chain up to the parent's implementation.

   The code below shows how a `<clutter-layout-manager>' sub-class
should provide animating the allocation of its children from within the
``allocate'' virtual function implementation. The animation is computed
between the last stable allocation performed before the animation
started and the desired final allocation.

   The `<clutter-layout-manager>' sub-class and it is updated by
overriding the ``begin-animation'' and ``end-animation'' virtual
functions and chaining up to the base class implementation.

   The last stable allocation is stored within a
`<clutter-layout-meta>' sub-class used by the implementation.


     static void
     my_layout_manager_allocate (ClutterLayoutManager   *manager,
                                 ClutterContainer       *container,
                                 const ClutterActorBox  *allocation,
                                 ClutterAllocationFlags  flags)
     {
       MyLayoutManager *self = MY_LAYOUT_MANAGER (manager);
       ClutterActor *child;

       for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container));
            child != NULL;
            child = clutter_actor_get_next_sibling (child))
         {
           ClutterLayoutMeta *meta;
           MyLayoutMeta *my_meta;

           /&#x002A; retrieve the layout meta-object &#x002A;/
           meta = clutter_layout_manager_get_child_meta (manager,
                                                         container,
                                                         child);
           my_meta = MY_LAYOUT_META (meta);

           /&#x002A; compute the desired allocation for the child &#x002A;/
           compute_allocation (self, my_meta, child,
                               allocation, flags,
                               &child_box);

           /&#x002A; this is the additional code that deals with the animation
            &#x002A; of the layout manager
            &#x002A;/
           if (!self->is_animating)
             {
               /&#x002A; store the last stable allocation for later use &#x002A;/
               my_meta->last_alloc = clutter_actor_box_copy (&child_box);
             }
           else
             {
               ClutterActorBox end = { 0, };
               gdouble p;

               /&#x002A; get the progress of the animation &#x002A;/
               p = clutter_layout_manager_get_animation_progress (manager);

               if (my_meta->last_alloc != NULL)
                 {
                   /&#x002A; copy the desired allocation as the final state &#x002A;/
                   end = child_box;

                   /&#x002A; then interpolate the initial and final state
                    &#x002A; depending on the progress of the animation,
                    &#x002A; and put the result inside the box we will use
                    &#x002A; to allocate the child
                    &#x002A;/
                   clutter_actor_box_interpolate (my_meta->last_alloc,
                                                  &end,
                                                  p,
                                                  &child_box);
                 }
               else
                 {
                   /&#x002A; if there is no stable allocation then the child was
                    &#x002A; added while animating; one possible course of action
                    &#x002A; is to just bail out and fall through to the allocation
                    &#x002A; to position the child directly at its final state
                    &#x002A;/
                   my_meta->last_alloc =
                     clutter_actor_box_copy (&child_box);
                 }
             }

           /&#x002A; allocate the child &#x002A;/
           clutter_actor_allocate (child, &child_box, flags);
         }
     }

   Sub-classes of `<clutter-layout-manager>' that support animations of
the layout changes should call `clutter-layout-manager-begin-animation'
whenever a layout property changes value, e.g.:


     if (self->orientation != new_orientation)
       {
         ClutterLayoutManager *manager;

         self->orientation = new_orientation;

         manager = CLUTTER_LAYOUT_MANAGER (self);
         clutter_layout_manager_layout_changed (manager);
         clutter_layout_manager_begin_animation (manager, 500, CLUTTER_LINEAR);

         g_object_notify (G_OBJECT (self), "orientation");
       }

   The code above will animate a change in the layout property of a
layout manager.

41.5 Layout Properties
======================

If a layout manager has layout properties, that is properties that
should exist only as the result of the presence of a specific (layout
manager, container actor, child actor) combination, and it wishes to
store those properties inside a `<clutter-layout-meta>', then it should
override the ::`get-child-meta-type' virtual function to return the
`<g-type>' of the `<clutter-layout-meta>' sub-class used to store the
layout properties; optionally, the `<clutter-layout-manager>' sub-class
might also override the (structname "ClutterLayoutManager")
::`create-child-meta' virtual function to control how the
`<clutter-layout-meta>' instance is created, otherwise the default
implementation will be equivalent to:


      ClutterLayoutManagerClass *klass;
      GType meta_type;

      klass = CLUTTER_LAYOUT_MANAGER_GET_CLASS (manager);
      meta_type = klass->get_child_meta_type (manager);

      return g_object_new (meta_type,
                           "manager", manager,
                           "container", container,
                           "actor", actor,
                           NULL);

   Where (varname "container") is the `<clutter-container>' using the
`<clutter-layout-manager>' and `<clutter-actor>' child of the
`<clutter-container>'.

41.6 Using ClutterLayoutManager with ClutterScript
==================================================

`<clutter-layout-manager>' instance can be created in the same way as
other objects in `<clutter-script>'; properties can be set using the
common syntax.

   Layout properties can be set on children of a container with a
`<clutter-layout-manager>' using the _layout::_ modifier on the
property name, for instance:


     {
       "type" : "ClutterBox",
       "layout-manager" : { "type" : "ClutterTableLayout" },
       "children" : [
         {
           "type" : "ClutterTexture",
           "filename" : "image-00.png",

           "layout::row" : 0,
           "layout::column" : 0,
           "layout::x-align" : "left",
           "layout::y-align" : "center",
           "layout::x-expand" : true,
           "layout::y-expand" : true
         },
         {
           "type" : "ClutterTexture",
           "filename" : "image-01.png",

           "layout::row" : 0,
           "layout::column" : 1,
           "layout::x-align" : "right",
           "layout::y-align" : "center",
           "layout::x-expand" : true,
           "layout::y-expand" : true
         }
       ]
     }

   `<clutter-layout-manager>' is available since Clutter 1.2

41.7 Usage
==========

 -- Function: clutter-layout-manager-allocate
          (self `<clutter-layout-manager>')
          (container `<clutter-container>')
          (allocation `<clutter-actor-box>')
          (flags `<clutter-allocation-flags>')
 -- Method: allocate
     Allocates the children of CONTAINER given an area

     See also `clutter-actor-allocate'

    MANAGER
          a `<clutter-layout-manager>'

    CONTAINER
          the `<clutter-container>' using MANAGER

    ALLOCATION
          the `<clutter-actor-box>' containing the allocated area of
          CONTAINER

    FLAGS
          the allocation flags


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterLayoutMeta,  Next: ClutterListModel,  Prev: ClutterLayoutManager,  Up: Top

42 ClutterLayoutMeta
********************

Wrapper for actors inside a layout manager

42.1 Overview
=============

`<clutter-layout-meta>' is a wrapper object created by
`<clutter-layout-manager>' implementations in order to store
child-specific data and properties.

   A `<clutter-layout-meta>' wraps a `<clutter-actor>' inside a
`<clutter-container>' using a `<clutter-layout-manager>'.

   `<clutter-layout-meta>' is available since Clutter 1.2

42.2 Usage
==========

 -- Function: clutter-layout-meta-get-manager
          (self `<clutter-layout-meta>') => 
          (ret `<clutter-layout-manager>')
 -- Method: get-manager
     Retrieves the actor wrapped by DATA

    DATA
          a `<clutter-layout-meta>'

    RET
          a `<clutter-layout-manager>'.


     Since 1.2



File: guile-gnome-clutter.info,  Node: ClutterListModel,  Next: General,  Prev: ClutterLayoutMeta,  Up: Top

43 ClutterListModel
*******************

List model implementation

43.1 Overview
=============

`<clutter-list-model>' is a `<clutter-model>' implementation provided
by Clutter. `<clutter-list-model>' uses a `<g-sequence>' for storing
the values for each row, so it's optimized for insertion and look up in
sorted lists.

   `<clutter-list-model>' is available since Clutter 0.6

43.2 Usage
==========


File: guile-gnome-clutter.info,  Node: General,  Next: ClutterMedia,  Prev: ClutterListModel,  Up: Top

44 General
**********

Various 'global' clutter functions.

44.1 Overview
=============

Functions to retrieve various global Clutter resources and other utility
functions for mainloops, events and threads

44.2 Threading Model
====================

Clutter is _thread-aware_: all operations performed by Clutter are
assumed to be under the big Clutter lock, which is created when the
threading is initialized through `clutter-init'.

   The code below shows how to correctly initialize Clutter in a
multi-threaded environment. These operations are mandatory for
applications that wish to use threads with Clutter.


     int
     main (int argc, char *argv[])
     {
       /&#x002A; initialize Clutter &#x002A;/
       clutter_init (&argc, &argv);

       /&#x002A; program code &#x002A;/

       /&#x002A; acquire the main lock &#x002A;/
       clutter_threads_enter ();

       /&#x002A; start the main loop &#x002A;/
       clutter_main ();

       /&#x002A; release the main lock &#x002A;/
       clutter_threads_leave ();

       /&#x002A; clean up &#x002A;/
       return 0;
     }

   This threading model has the caveat that it is only safe to call
Clutter's API when the lock has been acquired &#x2014; which happens
between pairs of `clutter-threads-enter' and `clutter-threads-leave'
calls.

   The only safe and portable way to use the Clutter API in a
multi-threaded environment is to never access the API from a thread that
did not call `clutter-init' and `clutter-main'.

   The common pattern for using threads with Clutter is to use worker
threads to perform blocking operations and then install idle or timeout
sources with the result when the thread finished.

   Clutter provides thread-aware variants of `g-idle-add' and
`g-timeout-add' that acquire the Clutter lock before invoking the
provided callback: `clutter-threads-add-idle' and
`clutter-threads-add-timeout'.

   The example below shows how to use a worker thread to perform a
blocking operation, and perform UI updates using the main loop.


44.3 Usage
==========

 -- Function: clutter-main
     Starts the Clutter mainloop.


 -- Function: clutter-main-quit
     Terminates the Clutter mainloop.


 -- Function: clutter-main-level =>  (ret `int')
     Retrieves the depth of the Clutter mainloop.

    RET
          The level of the mainloop.



 -- Function: clutter-get-default-frame-rate =>  (ret `unsigned-int')
     Retrieves the default frame rate. See
     `clutter-set-default-frame-rate'.

    RET
          the default frame rate


     Since 0.6


 -- Function: clutter-get-font-map =>  (ret `<pango-font-map>')
     Retrieves the `<pango-font-map>' instance used by Clutter. You can
     use the global font map object with the COGL Pango API.

    RET
          the `<pango-font-map>' instance. The returned value is owned
          by Clutter and it should never be unreferenced.


     Since 1.0


 -- Function: clutter-get-default-text-direction => 
          (ret `<clutter-text-direction>')
     Retrieves the default direction for the text. The text direction is
     determined by the locale and/or by the "CLUTTER_TEXT_DIRECTION")
     environment variable.

     The default text direction can be overridden on a per-actor basis
     by using `clutter-actor-set-text-direction'.

    RET
          the default text direction


     Since 1.2


 -- Function: clutter-get-accessibility-enabled =>  (ret `bool')
     Returns whether Clutter has accessibility support enabled. As
     least, a value of TRUE means that there are a proper AtkUtil
     implementation available

    RET
          ``#t'' if Clutter has accessibility support enabled


     Since 1.4


 -- Function: clutter-get-keyboard-grab =>  (ret `<clutter-actor>')
     Queries the current keyboard grab of clutter.

    RET
          the actor currently holding the keyboard grab, or NULL if
          there is no grab.


     Since 0.6


 -- Function: clutter-get-pointer-grab =>  (ret `<clutter-actor>')
     Queries the current pointer grab of clutter.

    RET
          the actor currently holding the pointer grab, or NULL if
          there is no grab.


     Since 0.6


 -- Function: clutter-grab-keyboard (actor `<clutter-actor>')
     Grabs keyboard events, after the grab is done keyboard events
     (`<"key-press-event">' and `<"key-release-event">') are delivered
     to this actor directly. The source set in the event will be the
     actor that would have received the event if the keyboard grab was
     not in effect.

     Like pointer grabs, keyboard grabs should only be used as a last
     resource.

     See also `clutter-stage-set-key-focus' and
     `clutter-actor-grab-key-focus' to perform a "soft" key grab and
     assign key focus to a specific actor.

    ACTOR
          a `<clutter-actor>'


     Since 0.6


 -- Function: clutter-grab-pointer (actor `<clutter-actor>')
     Grabs pointer events, after the grab is done all pointer related
     events (press, motion, release, enter, leave and scroll) are
     delivered to this actor directly without passing through both
     capture and bubble phases of the event delivery chain. The source
     set in the event will be the actor that would have received the
     event if the pointer grab was not in effect.

     Grabs completely override the entire event delivery chain done by
     Clutter. Pointer grabs should only be used as a last resource;
     using the `<"captured-event">' signal should always be the
     preferred way to intercept event delivery to reactive actors.

     This function should rarely be used.

     If a grab is required, you are strongly encouraged to use a
     specific input device by calling `clutter-input-device-grab'.

    ACTOR
          a `<clutter-actor>'


     Since 0.6


 -- Function: clutter-ungrab-keyboard
     Removes an existing grab of the keyboard.

     Since 0.6


 -- Function: clutter-ungrab-pointer
     Removes an existing grab of the pointer.

     Since 0.6


 -- Function: clutter-do-event (event `<clutter-event>')
     Processes an event.

     The EVENT must be a valid `<clutter-event>' and have a
     `<clutter-stage>' associated to it.

     This function is only useful when embedding Clutter inside another
     toolkit, and it should never be called by applications.

    EVENT
          a `<clutter-event>'.


     Since 0.4


