## ClutterBehaviourPath

ClutterBehaviourPath — A behaviour for moving actors along a ClutterPath

## Synopsis

    struct              ClutterBehaviourPath;
    struct              ClutterBehaviourPathClass;
    ClutterBehaviour *  clutter_behaviour_path_new          (ClutterAlpha *alpha,
                                                             ClutterPath *path);
    ClutterBehaviour *  clutter_behaviour_path_new_with_description
                                                            (ClutterAlpha *alpha,
                                                             const gchar *desc);
    ClutterBehaviour *  clutter_behaviour_path_new_with_knots
                                                            (ClutterAlpha *alpha,
                                                             const ClutterKnot *knots,
                                                             guint n_knots);
    void                clutter_behaviour_path_set_path     (ClutterBehaviourPath *pathb,
                                                             ClutterPath *path);
    ClutterPath *       clutter_behaviour_path_get_path     (ClutterBehaviourPath *pathb);

    struct              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 ClutterScriptable.

## Properties

      "path"                     ClutterPath*          : Read / Write

## Signals

      "knot-reached"                                   : Run Last

## Description

ClutterBehaviourPath interpolates actors along a defined path.

A path is described by a ClutterPath object. The path can contain straight line parts and bezier curves. If the path contains `CLUTTER_PATH_MOVE_TO` parts then the actors will jump to those coordinates. This can be used make disjoint paths.

When creating a path behaviour in a ClutterScript, you can specify the path property directly as a string. For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9

    {
      "id"     : "spline-path",
      "type"   : "ClutterBehaviourPath",
      "path"   : "M 50 50 L 100 100",
      "alpha"  : {
         "timeline" : "main-timeline",
         "function" : "ramp
       }
    }

### Note

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

ClutterBehaviourPath is available since Clutter 0.2

## Details

### struct ClutterBehaviourPath

    struct ClutterBehaviourPath;

The ClutterBehaviourPath structure contains only private data and should be accessed using the provided API

Since 0.2

### struct ClutterBehaviourPathClass

    struct ClutterBehaviourPathClass {
      void (*knot_reached) (ClutterBehaviourPath *pathb,
                            guint                 knot_num);
    };

The ClutterBehaviourPathClass struct contains only private data

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

Since 0.2

### clutter_behaviour_path_new ()

    ClutterBehaviour *  clutter_behaviour_path_new          (ClutterAlpha *alpha,
                                                             ClutterPath *path);

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

This will claim the floating reference on the ClutterPath so you do not need to unref if it.

If `alpha` is not `NULL`, the ClutterBehaviour will take ownership of the ClutterAlpha instance. In the case when `alpha` is `NULL`, it can be set later with `clutter_behaviour_set_alpha()`.

`alpha` : | a ClutterAlpha instance, or `NULL`. [allow-none]
`path` : | a ClutterPath or `NULL` for an empty path
Returns : | a ClutterBehaviour

Since 0.2

### clutter_behaviour_path_new_with_description ()

    ClutterBehaviour *  clutter_behaviour_path_new_with_description
                                                            (ClutterAlpha *alpha,
                                                             const gchar *desc);

Creates a new path behaviour using the path described by `desc`. See `clutter_path_add_string()` for a description of the format.

If `alpha` is not `NULL`, the ClutterBehaviour will take ownership of the ClutterAlpha instance. In the case when `alpha` is `NULL`, it can be set later with `clutter_behaviour_set_alpha()`.

`alpha` : | a ClutterAlpha instance, or `NULL`. [allow-none]
`desc` : | a string description of the path
Returns : | a ClutterBehaviour

Since 1.0

### clutter_behaviour_path_new_with_knots ()

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

Creates a new path behaviour that will make the actors visit all of the given knots in order with straight lines in between.

A path will be created where the first knot is used in a `CLUTTER_PATH_MOVE_TO` and the subsequent knots are used in `CLUTTER_PATH_LINE_TO`s.

If `alpha` is not `NULL`, the ClutterBehaviour will take ownership of the ClutterAlpha instance. In the case when `alpha` is `NULL`, it can be set later with `clutter_behaviour_set_alpha()`.

`alpha` : | a ClutterAlpha instance, or `NULL`. [allow-none]
`knots` : | an array of ClutterKnots
`n_knots` : | number of entries in `knots`
Returns : | a ClutterBehaviour

Since 1.0

### clutter_behaviour_path_set_path ()

    void                clutter_behaviour_path_set_path     (ClutterBehaviourPath *pathb,
                                                             ClutterPath *path);

Change the path that the actors will follow. This will take the floating reference on the ClutterPath so you do not need to unref it.

`pathb` : | the path behaviour
`path` : | the new path to follow

Since 1.0

### clutter_behaviour_path_get_path ()

    ClutterPath *       clutter_behaviour_path_get_path     (ClutterBehaviourPath *pathb);

Get the current path of the behaviour

`pathb` : | a ClutterBehaviourPath instance
Returns : | the path. [transfer none]

Since 1.0

### struct ClutterKnot

    struct ClutterKnot {
      gint x;
      gint y;
    };

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 `"path"` property

      "path"                     ClutterPath*          : Read / Write

The ClutterPath object representing the path to animate along.

## Signal Details

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

    void                user_function                      (ClutterBehaviourPath *pathb,
                                                            guint                 knot_num,
                                                            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_num` : | the index of the ClutterKnot reached
`user_data` : | user data set when the signal handler was connected.

Since 0.2