ClutterPath

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

Synopsis

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

struct              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

struct ClutterPathClass

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. [closure]

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: 

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.

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

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.

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.

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

path :

 a ClutterPath

Returns :

 the length of the path.

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.

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

Generated by GTK-Doc V1.19.1