ClutterPath

## ClutterPath ClutterPath — An object describing a path with straight lines and bezier curves. |

## Synopsis

                        ClutterPath;
                        ClutterPathClass;
    void                (*ClutterPathCallback)              (const ClutterPathNode *node,
                                                             gpointer data);
    enum                ClutterPathNodeType;
    ClutterPath *       clutter_path_new                    (void);
    ClutterPath *       clutter_path_new_with_description   (const gchar *desc);

    void                clutter_path_add_move_to            (ClutterPath *path,
                                                             gint x,
                                                             gint y);
    void                clutter_path_add_rel_move_to        (ClutterPath *path,
                                                             gint x,
                                                             gint y);
    void                clutter_path_add_line_to            (ClutterPath *path,
                                                             gint x,
                                                             gint y);
    void                clutter_path_add_rel_line_to        (ClutterPath *path,
                                                             gint x,
                                                             gint y);
    void                clutter_path_add_curve_to           (ClutterPath *path,
                                                             gint x_1,
                                                             gint y_1,
                                                             gint x_2,
                                                             gint y_2,
                                                             gint x_3,
                                                             gint y_3);
    void                clutter_path_add_rel_curve_to       (ClutterPath *path,
                                                             gint x_1,
                                                             gint y_1,
                                                             gint x_2,
                                                             gint y_2,
                                                             gint x_3,
                                                             gint y_3);
    void                clutter_path_add_close              (ClutterPath *path);
    gboolean            clutter_path_add_string             (ClutterPath *path,
                                                             const gchar *str);
    void                clutter_path_add_node               (ClutterPath *path,
                                                             const ClutterPathNode *node);
    void                clutter_path_add_cairo_path         (ClutterPath *path,
                                                             const cairo_path_t *cpath);

    guint               clutter_path_get_n_nodes            (ClutterPath *path);
    void                clutter_path_get_node               (ClutterPath *path,
                                                             guint index_,
                                                             ClutterPathNode *node);
    GSList *            clutter_path_get_nodes              (ClutterPath *path);
    void                clutter_path_foreach                (ClutterPath *path,
                                                             ClutterPathCallback callback,
                                                             gpointer user_data);
    void                clutter_path_insert_node            (ClutterPath *path,
                                                             gint index_,
                                                             const ClutterPathNode *node);
    void                clutter_path_remove_node            (ClutterPath *path,
                                                             guint index_);
    void                clutter_path_replace_node           (ClutterPath *path,
                                                             guint index_,
                                                             const ClutterPathNode *node);
    gchar *             clutter_path_get_description        (ClutterPath *path);
    gboolean            clutter_path_set_description        (ClutterPath *path,
                                                             const gchar *str);
    void                clutter_path_to_cairo_path          (ClutterPath *path,
                                                             cairo_t *cr);
    void                clutter_path_clear                  (ClutterPath *path);
    guint               clutter_path_get_position           (ClutterPath *path,
                                                             gdouble progress,
                                                             ClutterKnot *position);
    guint               clutter_path_get_length             (ClutterPath *path);

                        ClutterPathNode;
    ClutterPathNode *   clutter_path_node_copy              (const ClutterPathNode *node);
    void                clutter_path_node_free              (ClutterPathNode *node);
    gboolean            clutter_path_node_equal             (const ClutterPathNode *node_a,
                                                             const ClutterPathNode *node_b);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterPath

## Properties

      "description"              gchar*                : Read / Write
      "length"                   guint                 : Read

## Description

A ClutterPath contains a description of a path consisting of straight lines and bezier curves. This can be used in a ClutterBehaviourPath to animate an actor moving along the path.

The path consists of a series of nodes. Each node is one of the following four types:

`CLUTTER_PATH_MOVE_TO` | Changes the position of the path to the given pair of coordinates. This is usually used as the first node of a path to mark the start position. If it is used in the middle of a path then the path will be disjoint and the actor will appear to jump to the new position when animated.
`CLUTTER_PATH_LINE_TO` | Creates a straight line from the previous point to the given point.
`CLUTTER_PATH_CURVE_TO` | Creates a bezier curve. The end of the last node is used as the first control point and the three subsequent coordinates given in the node as used as the other three.
`CLUTTER_PATH_CLOSE` | Creates a straight line from the last node to the last `CLUTTER_PATH_MOVE_TO` node. This can be used to close a path so that it will appear as a loop when animated.

The first three types have the corresponding relative versions `CLUTTER_PATH_REL_MOVE_TO`, `CLUTTER_PATH_REL_LINE_TO` and `CLUTTER_PATH_REL_CURVE_TO`. These are exactly the same except the coordinates are given relative to the previous node instead of as direct screen positions.

You can build a path using the node adding functions such as `clutter_path_add_line_to()`. Alternatively the path can be described in a string using a subset of the SVG path syntax. See `clutter_path_add_string()` for details.

ClutterPath is available since Clutter 1.0

## Details

### ClutterPath

    typedef struct _ClutterPath ClutterPath;

The ClutterPath struct contains only private data and should be accessed with the functions below.

Since 1.0

### ClutterPathClass

    typedef struct {
    } ClutterPathClass;

The ClutterPathClass struct contains only private data.

Since 1.0

### ClutterPathCallback ()

    void                (*ClutterPathCallback)              (const ClutterPathNode *node,
                                                             gpointer data);

This function is passed to `clutter_path_foreach()` and will be called for each node contained in the path.

`node` : | the node
`data` : | optional data passed to the function

Since 1.0

### enum ClutterPathNodeType

    typedef enum {
      CLUTTER_PATH_MOVE_TO      = 0,
      CLUTTER_PATH_LINE_TO      = 1,
      CLUTTER_PATH_CURVE_TO     = 2,
      CLUTTER_PATH_CLOSE        = 3,

      CLUTTER_PATH_REL_MOVE_TO  = CLUTTER_PATH_MOVE_TO | CLUTTER_PATH_RELATIVE,
      CLUTTER_PATH_REL_LINE_TO  = CLUTTER_PATH_LINE_TO | CLUTTER_PATH_RELATIVE,
      CLUTTER_PATH_REL_CURVE_TO = CLUTTER_PATH_CURVE_TO | CLUTTER_PATH_RELATIVE
    } ClutterPathNodeType;

Types of nodes in a ClutterPath.

`CLUTTER_PATH_MOVE_TO` | jump to the given position
`CLUTTER_PATH_LINE_TO` | create a line from the last node to the given position
`CLUTTER_PATH_CURVE_TO` | bezier curve using the last position and three control points.
`CLUTTER_PATH_CLOSE` | create a line from the last node to the last `CLUTTER_PATH_MOVE_TO` node.
`CLUTTER_PATH_REL_MOVE_TO` | same as `CLUTTER_PATH_MOVE_TO` but with coordinates relative to the last node.
`CLUTTER_PATH_REL_LINE_TO` | same as `CLUTTER_PATH_LINE_TO` but with coordinates relative to the last node.
`CLUTTER_PATH_REL_CURVE_TO` | same as `CLUTTER_PATH_CURVE_TO` but with coordinates relative to the last node.

Since 1.0

### clutter_path_new ()

    ClutterPath *       clutter_path_new                    (void);

Creates a new ClutterPath instance with no nodes.

The object has a floating reference so if you add it to a ClutterBehaviourPath then you do not need to unref it.

Returns : | the newly created ClutterPath

Since 1.0

### clutter_path_new_with_description ()

    ClutterPath *       clutter_path_new_with_description   (const gchar *desc);

Creates a new ClutterPath instance with the nodes described in `desc`. See `clutter_path_add_string()` for details of the format of the string.

The object has a floating reference so if you add it to a ClutterBehaviourPath then you do not need to unref it.

`desc` : | a string describing the path
Returns : | the newly created ClutterPath

Since 1.0

### clutter_path_add_move_to ()

    void                clutter_path_add_move_to            (ClutterPath *path,
                                                             gint x,
                                                             gint y);

Adds a CLUTTER_PATH_MOVE_TO type node to the path. This is usually used as the first node in a path. It can also be used in the middle of the path to cause the actor to jump to the new coordinate.

`path` : | a ClutterPath
`x` : | the x coordinate
`y` : | the y coordinate

Since 1.0

### clutter_path_add_rel_move_to ()

    void                clutter_path_add_rel_move_to        (ClutterPath *path,
                                                             gint x,
                                                             gint y);

Same as `clutter_path_add_move_to()` except the coordinates are relative to the previous node.

`path` : | a ClutterPath
`x` : | the x coordinate
`y` : | the y coordinate

Since 1.0

### clutter_path_add_line_to ()

    void                clutter_path_add_line_to            (ClutterPath *path,
                                                             gint x,
                                                             gint y);

Adds a CLUTTER_PATH_LINE_TO type node to the path. This causes the actor to move to the new coordinates in a straight line.

`path` : | a ClutterPath
`x` : | the x coordinate
`y` : | the y coordinate

Since 1.0

### clutter_path_add_rel_line_to ()

    void                clutter_path_add_rel_line_to        (ClutterPath *path,
                                                             gint x,
                                                             gint y);

Same as `clutter_path_add_line_to()` except the coordinates are relative to the previous node.

`path` : | a ClutterPath
`x` : | the x coordinate
`y` : | the y coordinate

Since 1.0

### clutter_path_add_curve_to ()

    void                clutter_path_add_curve_to           (ClutterPath *path,
                                                             gint x_1,
                                                             gint y_1,
                                                             gint x_2,
                                                             gint y_2,
                                                             gint x_3,
                                                             gint y_3);

Adds a CLUTTER_PATH_CURVE_TO type node to the path. This causes the actor to follow a bezier from the last node to (`x_3`, `y_3`) using (`x_1`, `y_1`) and (`x_2`,`y_2`) as control points.

`path` : | a ClutterPath
`x_1` : | the x coordinate of the first control point
`y_1` : | the y coordinate of the first control point
`x_2` : | the x coordinate of the second control point
`y_2` : | the y coordinate of the second control point
`x_3` : | the x coordinate of the third control point
`y_3` : | the y coordinate of the third control point

Since 1.0

### clutter_path_add_rel_curve_to ()

    void                clutter_path_add_rel_curve_to       (ClutterPath *path,
                                                             gint x_1,
                                                             gint y_1,
                                                             gint x_2,
                                                             gint y_2,
                                                             gint x_3,
                                                             gint y_3);

Same as `clutter_path_add_curve_to()` except the coordinates are relative to the previous node.

`path` : | a ClutterPath
`x_1` : | the x coordinate of the first control point
`y_1` : | the y coordinate of the first control point
`x_2` : | the x coordinate of the second control point
`y_2` : | the y coordinate of the second control point
`x_3` : | the x coordinate of the third control point
`y_3` : | the y coordinate of the third control point

Since 1.0

### clutter_path_add_close ()

    void                clutter_path_add_close              (ClutterPath *path);

Adds a CLUTTER_PATH_CLOSE type node to the path. This creates a straight line from the last node to the last CLUTTER_PATH_MOVE_TO type node.

`path` : | a ClutterPath

Since 1.0

### clutter_path_add_string ()

    gboolean            clutter_path_add_string             (ClutterPath *path,
                                                             const gchar *str);

Adds new nodes to the end of the path as described in `str`. The format is a subset of the SVG path format. Each node is represented by a letter and is followed by zero, one or three pairs of coordinates. The coordinates can be separated by spaces or a comma. The types are:

M | Adds a `CLUTTER_PATH_MOVE_TO` node. Takes one pair of coordinates.
L | Adds a `CLUTTER_PATH_LINE_TO` node. Takes one pair of coordinates.
C | Adds a `CLUTTER_PATH_CURVE_TO` node. Takes three pairs of coordinates.
z | Adds a `CLUTTER_PATH_CLOSE` node. No coordinates are needed.

The M, L and C commands can also be specified in lower case which means the coordinates are relative to the previous node.

For example, to move an actor in a 100 by 100 pixel square centered on the point 300,300 you could use the following path:

      M 250,350 l 0 -100 L 350,250 l 0 100 z

If the path description isn't valid `FALSE` will be returned and no nodes will be added.

`path` : | a ClutterPath
`str` : | a string describing the new nodes
Returns : | `TRUE` is the path description was valid or `FALSE` otherwise.

Since 1.0

### clutter_path_add_node ()

    void                clutter_path_add_node               (ClutterPath *path,
                                                             const ClutterPathNode *node);

Adds `node` to the end of the path.

`path` : | a ClutterPath
`node` : | a ClutterPathNode

Since 1.0

### clutter_path_add_cairo_path ()

    void                clutter_path_add_cairo_path         (ClutterPath *path,
                                                             const cairo_path_t *cpath);

Add the nodes of the Cairo path to the end of `path`.

`path` : | a ClutterPath
`cpath` : | a Cairo path

Since 1.0

### clutter_path_get_n_nodes ()

    guint               clutter_path_get_n_nodes            (ClutterPath *path);

Retrieves the number of nodes in the path.

`path` : | a ClutterPath
Returns : | the number of nodes.

Since 1.0

### clutter_path_get_node ()

    void                clutter_path_get_node               (ClutterPath *path,
                                                             guint index_,
                                                             ClutterPathNode *node);

Retrieves the node of the path indexed by `index`.

`path` : | a ClutterPath
`index_` : | the node number to retrieve
`node` : | a location to store a copy of the node

Since 1.0

### clutter_path_get_nodes ()

    GSList *            clutter_path_get_nodes              (ClutterPath *path);

Returns a GSList of ClutterPathNodes. The list should be freed with `g_slist_free()`. The nodes are owned by the path and should not be freed. Altering the path may cause the nodes in the list to become invalid so you should copy them if you want to keep the list.

`path` : | a ClutterPath
Returns : | a list of nodes in the path.. transfer container. element-type ClutterPathNode.

Since 1.0

### clutter_path_foreach ()

    void                clutter_path_foreach                (ClutterPath *path,
                                                             ClutterPathCallback callback,
                                                             gpointer user_data);

Calls a function for each node of the path.

`path` : | a ClutterPath
`callback` : | the function to call with each node
`user_data` : | user data to pass to the function

Since 1.0

### clutter_path_insert_node ()

    void                clutter_path_insert_node            (ClutterPath *path,
                                                             gint index_,
                                                             const ClutterPathNode *node);

Inserts `node` into the path before the node at the given offset. If `index_` is negative it will append the node to the end of the path.

`path` : | a ClutterPath
`index_` : | offset of where to insert the node
`node` : | the node to insert

Since 1.0

### clutter_path_remove_node ()

    void                clutter_path_remove_node            (ClutterPath *path,
                                                             guint index_);

Removes the node at the given offset from the path.

`path` : | a ClutterPath
`index_` : | index of the node to remove

Since 1.0

### clutter_path_replace_node ()

    void                clutter_path_replace_node           (ClutterPath *path,
                                                             guint index_,
                                                             const ClutterPathNode *node);

Replaces the node at offset `index_` with `node`.

`path` : | a ClutterPath
`index_` : | index to the existing node
`node` : | the replacement node

Since 1.0

### clutter_path_get_description ()

    gchar *             clutter_path_get_description        (ClutterPath *path);

Returns a newly allocated string describing the path in the same format as used by `clutter_path_add_string()`.

`path` : | a ClutterPath
Returns : | a string description of the path. Free with `g_free()`.

Since 1.0

### clutter_path_set_description ()

    gboolean            clutter_path_set_description        (ClutterPath *path,
                                                             const gchar *str);

Replaces all of the nodes in the path with nodes described by `str`. See `clutter_path_add_string()` for details of the format.

If the string is invalid then `FALSE` is returned and the path is unaltered.

`path` : | a ClutterPath
`str` : | a string describing the path
Returns : | `TRUE` is the path was valid, `FALSE` otherwise.

Since 1.0

### clutter_path_to_cairo_path ()

    void                clutter_path_to_cairo_path          (ClutterPath *path,
                                                             cairo_t *cr);

Add the nodes of the ClutterPath to the path in the Cairo context.

`path` : | a ClutterPath
`cr` : | a Cairo context

Since 1.0

### clutter_path_clear ()

    void                clutter_path_clear                  (ClutterPath *path);

Removes all nodes from the path.

`path` : | a ClutterPath

Since 1.0

### clutter_path_get_position ()

    guint               clutter_path_get_position           (ClutterPath *path,
                                                             gdouble progress,
                                                             ClutterKnot *position);

The value in `progress` represents a position along the path where 0.0 is the beginning and 1.0 is the end of the path. An interpolated position is then stored in `position`.

`path` : | a ClutterPath
`progress` : | a position along the path as a fraction of its length
`position` : | location to store the position
Returns : | index of the node used to calculate the position.

Since 1.0

### clutter_path_get_length ()

    guint               clutter_path_get_length             (ClutterPath *path);

Retrieves an approximation of the total length of the path.

`path` : | a ClutterPath
Returns : | the length of the path.

Since 1.0

### ClutterPathNode

    typedef struct {
      ClutterPathNodeType type;

      ClutterKnot points[3];
    } ClutterPathNode;

Represents a single node of a ClutterPath.

Some of the coordinates in `points` may be unused for some node types. `CLUTTER_PATH_MOVE_TO` and `CLUTTER_PATH_LINE_TO` use only two pairs of coordinates, `CLUTTER_PATH_CURVE_TO` uses all three and `CLUTTER_PATH_CLOSE` uses none.

ClutterPathNodeType `type`; | the node's type
ClutterKnot `points`[3]; | the coordinates of the node

Since 1.0

### clutter_path_node_copy ()

    ClutterPathNode *   clutter_path_node_copy              (const ClutterPathNode *node);

Makes an allocated copy of a node.

`node` : | a ClutterPathNode
Returns : | the copied node.

Since 1.0

### clutter_path_node_free ()

    void                clutter_path_node_free              (ClutterPathNode *node);

Frees the memory of an allocated node.

`node` : | a ClutterPathNode

Since 1.0

### clutter_path_node_equal ()

    gboolean            clutter_path_node_equal             (const ClutterPathNode *node_a,
                                                             const ClutterPathNode *node_b);

Compares two nodes and checks if they are the same type with the same coordinates.

`node_a` : | First node
`node_b` : | Second node
Returns : | `TRUE` if the nodes are the same.

Since 1.0

## Property Details

### The `"description"` property

      "description"              gchar*                : Read / Write

SVG-style description of the path.

Default value: ""

### The `"length"` property

      "length"                   guint                 : Read

An approximation of the total length of the path.

Default value: 0