ClutterBehaviour

ClutterBehaviour — Class for providing behaviours to actors

Synopsis




                    ClutterBehaviour;
                    ClutterBehaviourClass;
void                clutter_behaviour_apply             (ClutterBehaviour *behave,
                                                         ClutterActor *actor);
void                clutter_behaviour_remove            (ClutterBehaviour *behave,
                                                         ClutterActor *actor);
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
         +----ClutterBehaviourBspline
         +----ClutterBehaviourEllipse
         +----ClutterBehaviourOpacity
         +----ClutterBehaviourPath
         +----ClutterBehaviourRotate
         +----ClutterBehaviourScale

Properties


  "alpha"                    ClutterAlpha          : Read / Write / Construct

Signals


  "apply"                                          : Run First
  "remove"                                         : 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.

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.

Details

ClutterBehaviour

typedef struct _ClutterBehaviour ClutterBehaviour;


ClutterBehaviourClass

typedef struct {
  GObjectClass parent_class;

  /* vfunc, not signal */
  void (*alpha_notify) (ClutterBehaviour *behave,
                        guint32           alpha_value);

  void (*apply)    (ClutterBehaviour *behave,
		    ClutterActor     *actor);
  void (*remove)   (ClutterBehaviour *behave,
		    ClutterActor     *actor);

  /* padding, for future expansion */
  void (*_clutter_behaviour1) (void);
  void (*_clutter_behaviour2) (void);
  void (*_clutter_behaviour3) (void);
  void (*_clutter_behaviour4) (void);
  void (*_clutter_behaviour5) (void);
  void (*_clutter_behaviour6) (void);
} ClutterBehaviourClass;


clutter_behaviour_apply ()

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

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);

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_is_applied ()

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

Check if behave applied to actor.

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

Since 0.3


ClutterBehaviourForeachFunc ()

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

behaviour :
actor :
data :

clutter_behaviour_actors_foreach ()

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

Calls func for every actor driven by behave.

behave : a ClutterBehaviour
func : a function called for each actor
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);

Retrieves all the actors to which behave applies. It is not recommended derived classes 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.

Since 0.2


clutter_behaviour_get_n_actors ()

gint                clutter_behaviour_get_n_actors      (ClutterBehaviour *behave);

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);

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.

Since 0.2


clutter_behaviour_get_alpha ()

ClutterAlpha*       clutter_behaviour_get_alpha         (ClutterBehaviour *behave);

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.

Since 0.2


clutter_behaviour_set_alpha ()

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

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.

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 / Construct

Alpha Object to drive the behaviour.

Signal Details

The "apply" signal

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

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 "remove" signal

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

The ::remove signal is emitted each time an actor has been removed from the group

behaviour : the ClutterBehaviour that received the signal
actor : the actor added to the group
user_data : user data set when the signal handler was connected.