ClutterPath: Clutter Reference Manual

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

## Functions

void | (*ClutterPathCallback) ()
ClutterPath * | clutter_path_new ()
ClutterPath * | clutter_path_new_with_description ()
void | clutter_path_add_move_to ()
void | clutter_path_add_rel_move_to ()
void | clutter_path_add_line_to ()
void | clutter_path_add_rel_line_to ()
void | clutter_path_add_curve_to ()
void | clutter_path_add_rel_curve_to ()
void | clutter_path_add_close ()
gboolean | clutter_path_add_string ()
void | clutter_path_add_node ()
void | clutter_path_add_cairo_path ()
guint | clutter_path_get_n_nodes ()
void | clutter_path_get_node ()
GSList * | clutter_path_get_nodes ()
void | clutter_path_foreach ()
void | clutter_path_insert_node ()
void | clutter_path_remove_node ()
void | clutter_path_replace_node ()
gchar * | clutter_path_get_description ()
gboolean | clutter_path_set_description ()
void | clutter_path_to_cairo_path ()
void | clutter_path_clear ()
guint | clutter_path_get_position ()
guint | clutter_path_get_length ()
ClutterPathNode * | clutter_path_node_copy ()
void | clutter_path_node_free ()
gboolean | clutter_path_node_equal ()

## Properties

gchar * | description | Read / Write
guint | length | Read

## Types and Values

| ClutterPath
struct | ClutterPathClass
enum | ClutterPathNodeType
struct | ClutterPathNode

## Object Hierarchy

        GBoxed
        ╰── ClutterPathNode
        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterPath

## 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

## Functions

### 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.

#### Parameters

node | the node |
data | optional data passed to the function. | [closure]

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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:

    1
    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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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` .

#### Parameters

path | a ClutterPath |
index_ | the node number to retrieve |
node | a location to store a copy of the node. | [out]

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.

#### Parameters

path | a ClutterPath |

#### Returns

a list of nodes in the path.

[transfer container][element-type Clutter.PathNode]

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.

#### Parameters

path | a ClutterPath |
callback | the function to call with each node. | [scope call]
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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

path | a ClutterPath |
progress | a position along the path as a fraction of its length |
position | location to store the position. | [out]

#### 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.

#### Parameters

path | a ClutterPath |

#### Returns

the length of the path.

Since: 1.0

### clutter_path_node_copy ()

    ClutterPathNode *
    clutter_path_node_copy (const ClutterPathNode *node);

Makes an allocated copy of a node.

#### Parameters

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.

#### Parameters

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.

#### Parameters

node_a | First node |
node_b | Second node |

#### Returns

`TRUE` if the nodes are the same.

Since: 1.0

## Types and Values

### ClutterPath

    typedef struct _ClutterPath ClutterPath;

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

Since: 1.0

### struct ClutterPathClass

    struct ClutterPathClass {
    };

The ClutterPathClass struct contains only private data.

Since: 1.0

### enum ClutterPathNodeType

Types of nodes in a ClutterPath.

#### Members

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

### struct ClutterPathNode

    struct ClutterPathNode {
      ClutterPathNodeType type;

      ClutterKnot points[3];
    };

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 one pair of coordinates, `CLUTTER_PATH_CURVE_TO` uses all three and `CLUTTER_PATH_CLOSE` uses none.

#### Members

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

Since: 1.0

## Property Details

### The `“description”` property

      “description”              gchar *

SVG-style description of the path.

Owner: ClutterPath

Flags: Read / Write

Default value: ""

### The `“length”` property

      “length”                   guint

An approximation of the total length of the path.

Owner: ClutterPath

Flags: Read

Default value: 0