## ClutterBehaviourPath

ClutterBehaviourPath — A behaviour interpolating position along a path

## Synopsis

                        ClutterBehaviourPath;
                        ClutterBehaviourPathClass;
    ClutterBehaviour*   clutter_behaviour_path_new          (ClutterAlpha *alpha,
                                                             const ClutterKnot *knots,
                                                             guint n_knots);
    GSList*             clutter_behaviour_path_get_knots    (ClutterBehaviourPath *pathb);
    void                clutter_behaviour_path_append_knot  (ClutterBehaviourPath *pathb,
                                                             const ClutterKnot *knot);
    void                clutter_behaviour_path_append_knots (ClutterBehaviourPath *pathb,
                                                             const ClutterKnot *first_knot,
                                                             ...);
    void                clutter_behaviour_path_insert_knot  (ClutterBehaviourPath *pathb,
                                                             guint offset,
                                                             const ClutterKnot *knot);
    void                clutter_behaviour_path_remove_knot  (ClutterBehaviourPath *pathb,
                                                             guint offset);
    void                clutter_behaviour_path_clear        (ClutterBehaviourPath *pathb);

                        ClutterKnot;
    ClutterKnot*        clutter_knot_copy                   (const ClutterKnot *knot);
    void                clutter_knot_free                   (ClutterKnot *knot);
    gboolean            clutter_knot_equal                  (const ClutterKnot *knot_a,
                                                             const ClutterKnot *knot_b);

## Object Hierarchy

      GObject
       +----ClutterBehaviour
             +----ClutterBehaviourPath

## Implemented Interfaces

ClutterBehaviourPath implements

## Properties

      "knot"                     ClutterKnot*          : Write

## Signals

      "knot-reached"                                   : Run Last

## Description

ClutterBehaviourPath interpolates actors along a defined path.

A path is a set of ClutterKnots object given when creating a new ClutterBehaviourPath instance. Knots can be also added to the path using `clutter_behaviour_path_append_knot()`. The whole path can be cleared using `clutter_behaviour_path_clear()`. Each time the behaviour reaches a knot in the path, the "knot-reached" signal is emitted.

This first knot in the path is reached with the lower bound value provided by the ClutterAlpha objectused by the behaviour; the last knot in the path is reached with the upper bound value provided by the ClutterAlpha object used by the behaviour.

### Note

If the alpha function is a periodic function, i.e. it returns to 0 after reaching `CLUTTER_ALPHA_MAX_ALPHA`, then the actors will walk the path back to the starting ClutterKnot.

ClutterBehaviourPath is available since Clutter 0.2

## Details

### ClutterBehaviourPath

    typedef struct _ClutterBehaviourPath ClutterBehaviourPath;

### ClutterBehaviourPathClass

    typedef struct {
      void (*knot_reached) (ClutterBehaviourPath *pathb,
                            const ClutterKnot    *knot);
    } ClutterBehaviourPathClass;

Since 0.2

`knot_reached` () | signal class handler for the ClutterBehaviourPath::knot_reached signal

### clutter_behaviour_path_new ()

    ClutterBehaviour*   clutter_behaviour_path_new          (ClutterAlpha *alpha,
                                                             const ClutterKnot *knots,
                                                             guint n_knots);

Creates a new path behaviour. You can use this behaviour to drive actors along the nodes of a path, described by the `knots`.

`alpha` : | a ClutterAlpha, or `NULL`
`knots` : | a list of ClutterKnots, or `NULL` for an empty path
`n_knots` : | the number of nodes in the path
Returns : | a ClutterBehaviour

Since 0.2

### clutter_behaviour_path_get_knots ()

    GSList*             clutter_behaviour_path_get_knots    (ClutterBehaviourPath *pathb);

Returns a copy of the list of knots contained by `pathb`

`pathb` : | a ClutterBehvaiourPath
Returns : | a GSList of the paths knots.

Since 0.2

### clutter_behaviour_path_append_knot ()

    void                clutter_behaviour_path_append_knot  (ClutterBehaviourPath *pathb,
                                                             const ClutterKnot *knot);

Appends a ClutterKnot to the path

`pathb` : | a ClutterBehvaiourPath
`knot` : | a ClutterKnot to append.

Since 0.2

### clutter_behaviour_path_append_knots ()

    void                clutter_behaviour_path_append_knots (ClutterBehaviourPath *pathb,
                                                             const ClutterKnot *first_knot,
                                                             ...);

Adds a NULL-terminated list of knots to a path. This function is equivalent to calling `clutter_behaviour_path_append_knot()` for each member of the list.

`pathb` : | a ClutterBehvaiourPath
`first_knot` : | the ClutterKnot knot to add to the path
`...` : | additional knots to add to the path

Since 0.2

### clutter_behaviour_path_insert_knot ()

    void                clutter_behaviour_path_insert_knot  (ClutterBehaviourPath *pathb,
                                                             guint offset,
                                                             const ClutterKnot *knot);

Inserts a ClutterKnot in the path at specified position. Values greater than total number of knots will append the knot at the end of path.

`pathb` : | a ClutterBehvaiourPath
`offset` : | position in path to insert knot.
`knot` : | a ClutterKnot to append.

Since 0.2

### clutter_behaviour_path_remove_knot ()

    void                clutter_behaviour_path_remove_knot  (ClutterBehaviourPath *pathb,
                                                             guint offset);

Removes a ClutterKnot in the path at specified offset.

`pathb` : | a ClutterBehvaiourPath
`offset` : | position in path to remove knot.

Since 0.2

### clutter_behaviour_path_clear ()

    void                clutter_behaviour_path_clear        (ClutterBehaviourPath *pathb);

Removes all knots from a path

`pathb` : | a ClutterBehvaiourPath

Since 0.2

### ClutterKnot

    typedef struct {
      gint x;
      gint y;
    } ClutterKnot;

Point in a path behaviour.

gint `x`; | X coordinate of the knot
gint `y`; | Y coordinate of the knot

Since 0.2

### clutter_knot_copy ()

    ClutterKnot*        clutter_knot_copy                   (const ClutterKnot *knot);

Makes an allocated copy of a knot.

`knot` : | a ClutterKnot
Returns : | the copied knot.

Since 0.2

### clutter_knot_free ()

    void                clutter_knot_free                   (ClutterKnot *knot);

Frees the memory of an allocated knot.

`knot` : | a ClutterKnot

Since 0.2

### clutter_knot_equal ()

    gboolean            clutter_knot_equal                  (const ClutterKnot *knot_a,
                                                             const ClutterKnot *knot_b);

Compares to knot and checks if the point to the same location.

`knot_a` : | First knot
`knot_b` : | Second knot
Returns : | `TRUE` if the knots point to the same location.

Since 0.2

## Property Details

### The `"knot"` property

      "knot"                     ClutterKnot*          : Write

This property can be used to append a new knot to the path.

Since 0.2

## Signal Details

### The `"knot-reached"` signal

    void                user_function                      (ClutterBehaviourPath *pathb,
                                                            ClutterKnot          *knot,
                                                            gpointer              user_data)      : Run Last

This signal is emitted each time a node defined inside the path is reached.

`pathb` : | the object which received the signal
`knot` : | the ClutterKnot reached
`user_data` : | user data set when the signal handler was connected.

Since 0.2