Clutter Reference Manual: ClutterBehaviour

## ClutterBehaviour ClutterBehaviour — Class for providing behaviours to actors |

## Synopsis

                        ClutterBehaviour;
    struct              ClutterBehaviourClass;
    void                clutter_behaviour_apply             (ClutterBehaviour *behave,
                                                             ClutterActor *actor);
    void                clutter_behaviour_remove            (ClutterBehaviour *behave,
                                                             ClutterActor *actor);
    void                clutter_behaviour_remove_all        (ClutterBehaviour *behave);
    gboolean            clutter_behaviour_is_applied        (ClutterBehaviour *behave,
                                                             ClutterActor *actor);
    void                (*ClutterBehaviourForeachFunc)      (ClutterBehaviour *behaviour,
                                                             ClutterActor *actor,
                                                             gpointer data);
    void                clutter_behaviour_actors_foreach    (ClutterBehaviour *behave,
                                                             ClutterBehaviourForeachFunc func,
                                                             gpointer data);
    GSList *            clutter_behaviour_get_actors        (ClutterBehaviour *behave);
    gint                clutter_behaviour_get_n_actors      (ClutterBehaviour *behave);
    ClutterActor *      clutter_behaviour_get_nth_actor     (ClutterBehaviour *behave,
                                                             gint index_);
    ClutterAlpha *      clutter_behaviour_get_alpha         (ClutterBehaviour *behave);
    void                clutter_behaviour_set_alpha         (ClutterBehaviour *behave,
                                                             ClutterAlpha *alpha);

## Object Hierarchy

      GObject
       +----ClutterBehaviour
             +----ClutterBehaviourDepth
             +----ClutterBehaviourEllipse
             +----ClutterBehaviourOpacity
             +----ClutterBehaviourPath
             +----ClutterBehaviourRotate
             +----ClutterBehaviourScale

## Implemented Interfaces

ClutterBehaviour implements ClutterScriptable.

## Properties

      "alpha"                    ClutterAlpha*         : Read / Write

## Signals

      "applied"                                        : Run First
      "removed"                                        : Run First

## Description

ClutterBehaviour is the base class for implementing behaviours. A behaviour is a controller object for ClutterActors; you can use a behaviour to control one or more properties of an actor (such as its opacity, or its position). A ClutterBehaviour is driven by an "alpha function" stored inside a ClutterAlpha object; an alpha function is a function depending solely on time. The alpha function computes a value which is then applied to the properties of the actors driven by a behaviour.

Clutter provides some pre-defined behaviours, like ClutterBehaviourPath, which controls the position of a set of actors making them "walk" along a set of nodes; ClutterBehaviourOpacity, which controls the opacity of a set of actors; ClutterBehaviourScale, which controls the width and height of a set of actors.

To visualize the effects of different alpha functions on a ClutterBehaviour implementation it is possible to take the ClutterBehaviourPath as an example:

Figure 10. Effects of alpha functions on a path

The actors position between the path's end points directly correlates to the ClutterAlpha's current alpha value driving the behaviour. With the ClutterAlpha's function set to a linear ramp the actor will follow the path at a constant velocity, but when changing to a sine wave the actor initially accelerates before quickly decelerating.

In order to implement a new behaviour you should subclass ClutterBehaviour and override the "alpha_notify" virtual function; inside the overridden function you should obtain the alpha value from the ClutterAlpha instance bound to the behaviour and apply it to the desiderd property (or properties) of every actor controlled by the behaviour.

ClutterBehaviour is available since Clutter 0.2.

ClutterBehaviour and its sub-classes have been deprecated since Clutter 1.6. You should see the migration guide for more information on migrating code from using the ClutterBehaviour API to the animation framework API.

## Details

### ClutterBehaviour

    typedef struct _ClutterBehaviour ClutterBehaviour;

### Warning

`ClutterBehaviour` is deprecated and should not be used in newly-written code. 1.6

ClutterBehaviour contains only private data and should be accessed with the functions below.

Since 0.2

### struct ClutterBehaviourClass

    struct ClutterBehaviourClass {
      /* vfunc, not signal */
      void (*alpha_notify) (ClutterBehaviour *behave,
                            gdouble           alpha_value);

      /* signals */
      void (*applied)  (ClutterBehaviour *behave,
    		    ClutterActor     *actor);
      void (*removed)  (ClutterBehaviour *behave,
    		    ClutterActor     *actor);
    };

### Warning

`ClutterBehaviourClass` is deprecated and should not be used in newly-written code. 1.6

Base class for behaviours.

`alpha_notify` () | virtual function, called each time the ClutterAlpha computes a new alpha value; the actors to which the behaviour applies should be changed in this function. Every subclass of ClutterBehaviour must implement this virtual function
`applied` () | signal class handler for the ClutterBehaviour::applied signal
`removed` () | signal class handler for the ClutterBehaviour::removed signal

Since 0.2

### clutter_behaviour_apply ()

    void                clutter_behaviour_apply             (ClutterBehaviour *behave,
                                                             ClutterActor *actor);

### Warning

`clutter_behaviour_apply` is deprecated and should not be used in newly-written code. 1.6

Applies `behave` to `actor`. This function adds a reference on the actor.

`behave` : | a ClutterBehaviour
`actor` : | a ClutterActor

Since 0.2

### clutter_behaviour_remove ()

    void                clutter_behaviour_remove            (ClutterBehaviour *behave,
                                                             ClutterActor *actor);

### Warning

`clutter_behaviour_remove` is deprecated and should not be used in newly-written code. 1.6

Removes `actor` from the list of ClutterActors to which `behave` applies. This function removes a reference on the actor.

`behave` : | a ClutterBehaviour
`actor` : | a ClutterActor

Since 0.2

### clutter_behaviour_remove_all ()

    void                clutter_behaviour_remove_all        (ClutterBehaviour *behave);

### Warning

`clutter_behaviour_remove_all` is deprecated and should not be used in newly-written code. 1.6

Removes every actor from the list that `behave` holds.

`behave` : | a ClutterBehaviour

Since 0.4

### clutter_behaviour_is_applied ()

    gboolean            clutter_behaviour_is_applied        (ClutterBehaviour *behave,
                                                             ClutterActor *actor);

### Warning

`clutter_behaviour_is_applied` is deprecated and should not be used in newly-written code. 1.6

Check if `behave` applied to `actor`.

`behave` : | a ClutterBehaviour
`actor` : | a ClutterActor
Returns : | TRUE if actor has behaviour. FALSE otherwise.

Since 0.4

### ClutterBehaviourForeachFunc ()

    void                (*ClutterBehaviourForeachFunc)      (ClutterBehaviour *behaviour,
                                                             ClutterActor *actor,
                                                             gpointer data);

### Warning

`ClutterBehaviourForeachFunc` is deprecated and should not be used in newly-written code. 1.6

This function is passed to `clutter_behaviour_actors_foreach()` and will be called for each actor driven by `behaviour`.

`behaviour` : | the ClutterBehaviour
`actor` : | an actor driven by `behaviour`
`data` : | optional data passed to the function. [closure]

Since 0.2

### clutter_behaviour_actors_foreach ()

    void                clutter_behaviour_actors_foreach    (ClutterBehaviour *behave,
                                                             ClutterBehaviourForeachFunc func,
                                                             gpointer data);

### Warning

`clutter_behaviour_actors_foreach` is deprecated and should not be used in newly-written code. 1.6

Calls `func` for every actor driven by `behave`.

`behave` : | a ClutterBehaviour
`func` : | a function called for each actor. [scope call]
`data` : | optional data to be passed to the function, or `NULL`

Since 0.2

### clutter_behaviour_get_actors ()

    GSList *            clutter_behaviour_get_actors        (ClutterBehaviour *behave);

### Warning

`clutter_behaviour_get_actors` is deprecated and should not be used in newly-written code. 1.6

Retrieves all the actors to which `behave` applies. It is not recommended for derived classes to use this in there alpha notify method but use clutter_behaviour_actors_foreach as it avoids alot of needless allocations.

`behave` : | a ClutterBehaviour
Returns : | a list of actors. You should free the returned list with `g_slist_free()` when finished using it. [transfer container][element-type Clutter.Actor]

Since 0.2

### clutter_behaviour_get_n_actors ()

    gint                clutter_behaviour_get_n_actors      (ClutterBehaviour *behave);

### Warning

`clutter_behaviour_get_n_actors` is deprecated and should not be used in newly-written code. 1.6

Gets the number of actors this behaviour is applied too.

`behave` : | a ClutterBehaviour
Returns : | The number of applied actors

Since 0.2

### clutter_behaviour_get_nth_actor ()

    ClutterActor *      clutter_behaviour_get_nth_actor     (ClutterBehaviour *behave,
                                                             gint index_);

### Warning

`clutter_behaviour_get_nth_actor` is deprecated and should not be used in newly-written code. 1.6

Gets an actor the behaviour was applied to referenced by index num.

`behave` : | a ClutterBehaviour
`index_` : | the index of an actor this behaviour is applied too.
Returns : | A Clutter actor or NULL if `index_` is invalid. [transfer none]

Since 0.2

### clutter_behaviour_get_alpha ()

    ClutterAlpha *      clutter_behaviour_get_alpha         (ClutterBehaviour *behave);

### Warning

`clutter_behaviour_get_alpha` is deprecated and should not be used in newly-written code. 1.6

Retrieves the ClutterAlpha object bound to `behave`.

`behave` : | a ClutterBehaviour
Returns : | a ClutterAlpha object, or `NULL` if no alpha object has been bound to this behaviour. [transfer none]

Since 0.2

### clutter_behaviour_set_alpha ()

    void                clutter_behaviour_set_alpha         (ClutterBehaviour *behave,
                                                             ClutterAlpha *alpha);

### Warning

`clutter_behaviour_set_alpha` is deprecated and should not be used in newly-written code. 1.6

Binds `alpha` to a ClutterBehaviour. The ClutterAlpha object is what makes a behaviour work: for each tick of the timeline used by ClutterAlpha a new value of the alpha parameter is computed by the alpha function; the value should be used by the ClutterBehaviour to update one or more properties of the actors to which the behaviour applies.

If `alpha` is not `NULL`, the ClutterBehaviour will take ownership of the ClutterAlpha instance.

`behave` : | a ClutterBehaviour
`alpha` : | a ClutterAlpha or `NULL` to unset a previously set alpha

Since 0.2

## Property Details

### The `"alpha"` property

      "alpha"                    ClutterAlpha*         : Read / Write

### Warning

`ClutterBehaviour:alpha` is deprecated and should not be used in newly-written code. 1.6

The ClutterAlpha object used to drive this behaviour. A ClutterAlpha object binds a ClutterTimeline and a function which computes a value (the "alpha") depending on the time. Each time the alpha value changes the alpha-notify virtual function is called.

Since 0.2

## Signal Details

### The `"applied"` signal

    void                user_function                      (ClutterBehaviour *behaviour,
                                                            ClutterActor     *actor,
                                                            gpointer          user_data)      : Run First

### Warning

`ClutterBehaviour::applied` is deprecated and should not be used in newly-written code. 1.6

The ::apply signal is emitted each time the behaviour is applied to an actor.

`behaviour` : | the ClutterBehaviour that received the signal
`actor` : | the actor the behaviour was applied to.
`user_data` : | user data set when the signal handler was connected.

Since 0.4

### The `"removed"` signal

    void                user_function                      (ClutterBehaviour *behaviour,
                                                            ClutterActor     *actor,
                                                            gpointer          user_data)      : Run First

### Warning

`ClutterBehaviour::removed` is deprecated and should not be used in newly-written code. 1.6

The ::removed signal is emitted each time a behaviour is not applied to an actor anymore.

`behaviour` : | the ClutterBehaviour that received the signal
`actor` : | the removed actor
`user_data` : | user data set when the signal handler was connected.

Since 0.4