Next: , Previous: ClutterPathConstraint, Up: Top

53 ClutterPath

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

53.1 Overview

A <clutter-path> contains a description of a path consisting of straight lines and bezier curves. This can be used in a <clutter-behaviour-path> 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_LINE_TO

CLUTTER_PATH_CURVE_TO

CLUTTER_PATH_CLOSE

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.

Creates a straight line from the previous point to the given point.

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.

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.

<clutter-path> is available since Clutter 1.0

53.2 Usage

— Function: clutter-path-new ⇒  (ret <clutter-path>)

Creates a new <clutter-path> instance with no nodes.

The object has a floating reference so if you add it to a <clutter-behaviour-path> then you do not need to unref it.

ret
the newly created <clutter-path>

Since 1.0

— Function: clutter-path-new-with-description (desc mchars) ⇒  (ret <clutter-path>)

Creates a new <clutter-path> 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 <clutter-behaviour-path> then you do not need to unref it.

desc
a string describing the path
ret
the newly created <clutter-path>

Since 1.0

— Function: clutter-path-add-move-to (self <clutter-path>) (x int) (y int)
— Method: add-move-to

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 <clutter-path>
x
the x coordinate
y
the y coordinate

Since 1.0

— Function: clutter-path-add-rel-move-to (self <clutter-path>) (x int) (y int)
— Method: add-rel-move-to

Same as clutter-path-add-move-to except the coordinates are relative to the previous node.

path
a <clutter-path>
x
the x coordinate
y
the y coordinate

Since 1.0

— Function: clutter-path-add-line-to (self <clutter-path>) (x int) (y int)
— Method: add-line-to

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 <clutter-path>
x
the x coordinate
y
the y coordinate

Since 1.0

— Function: clutter-path-add-rel-line-to (self <clutter-path>) (x int) (y int)
— Method: add-rel-line-to

Same as clutter-path-add-line-to except the coordinates are relative to the previous node.

path
a <clutter-path>
x
the x coordinate
y
the y coordinate

Since 1.0

— Function: clutter-path-add-curve-to (self <clutter-path>) (x_1 int) (y_1 int) (x_2 int) (y_2 int) (x_3 int) (y_3 int)
— Method: add-curve-to

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 <clutter-path>
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

— Function: clutter-path-add-rel-curve-to (self <clutter-path>) (x_1 int) (y_1 int) (x_2 int) (y_2 int) (x_3 int) (y_3 int)
— Method: add-rel-curve-to

Same as clutter-path-add-curve-to except the coordinates are relative to the previous node.

path
a <clutter-path>
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

— Function: clutter-path-add-close (self <clutter-path>)
— Method: add-close

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 <clutter-path>

Since 1.0

— Function: clutter-path-add-string (self <clutter-path>) (str mchars) ⇒  (ret bool)
— Method: add-string

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:

L

C

z

Adds a ‘CLUTTER_PATH_MOVE_TO’ node. Takes one pair of coordinates.

Adds a ‘CLUTTER_PATH_LINE_TO’ node. Takes one pair of coordinates.

Adds a ‘CLUTTER_PATH_CURVE_TO’ node. Takes three pairs of coordinates.

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 ‘#f’ will be returned and no nodes will be added.

path
a <clutter-path>
str
a string describing the new nodes
ret
‘#t’ is the path description was valid or ‘#f’ otherwise.

Since 1.0

— Function: clutter-path-add-node (self <clutter-path>) (node <clutter-path-node>)
— Method: add-node

Adds node to the end of the path.

path
a <clutter-path>
node
a <clutter-path-node>

Since 1.0

— Function: clutter-path-add-cairo-path (self <clutter-path>) (cpath cairo-path-t)
— Method: add-cairo-path

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

path
a <clutter-path>
cpath
a Cairo path

Since 1.0

— Function: clutter-path-get-n-nodes (self <clutter-path>) ⇒  (ret unsigned-int)
— Method: get-n-nodes

Retrieves the number of nodes in the path.

path
a <clutter-path>
ret
the number of nodes.

Since 1.0

— Function: clutter-path-get-node (self <clutter-path>) (index_ unsigned-int) (node <clutter-path-node>)
— Method: get-node

Retrieves the node of the path indexed by index.

path
a <clutter-path>
index
the node number to retrieve
node
a location to store a copy of the node.

Since 1.0

— Function: clutter-path-get-nodes (self <clutter-path>) ⇒  (ret gslist-of)
— Method: get-nodes

Returns a <gs-list> of <clutter-path-node>s. 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 <clutter-path>
ret
a list of nodes in the path.

Since 1.0

— Function: clutter-path-insert-node (self <clutter-path>) (index_ int) (node <clutter-path-node>)
— Method: insert-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 <clutter-path>
index
offset of where to insert the node
node
the node to insert

Since 1.0

— Function: clutter-path-remove-node (self <clutter-path>) (index_ unsigned-int)
— Method: remove-node

Removes the node at the given offset from the path.

path
a <clutter-path>
index
index of the node to remove

Since 1.0

— Function: clutter-path-replace-node (self <clutter-path>) (index_ unsigned-int) (node <clutter-path-node>)
— Method: replace-node

Replaces the node at offset index with node.

path
a <clutter-path>
index
index to the existing node
node
the replacement node

Since 1.0

— Function: clutter-path-get-description (self <clutter-path>) ⇒  (ret mchars)
— Method: get-description

Returns a newly allocated string describing the path in the same format as used by clutter-path-add-string.

path
a <clutter-path>
ret
a string description of the path. Free with g-free.

Since 1.0

— Function: clutter-path-set-description (self <clutter-path>) (str mchars) ⇒  (ret bool)
— Method: set-description

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 ‘#f’ is returned and the path is unaltered.

path
a <clutter-path>
str
a string describing the path
ret
‘#t’ is the path was valid, ‘#f’ otherwise.

Since 1.0

— Function: clutter-path-to-cairo-path (self <clutter-path>) (cr cairo-t)
— Method: to-cairo-path

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

path
a <clutter-path>
cr
a Cairo context

Since 1.0

— Function: clutter-path-clear (self <clutter-path>)
— Method: clear

Removes all nodes from the path.

path
a <clutter-path>

Since 1.0

— Function: clutter-path-get-position (self <clutter-path>) (progress double) (position <clutter-knot>) ⇒  (ret unsigned-int)
— Method: get-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 <clutter-path>
progress
a position along the path as a fraction of its length
position
location to store the position.
ret
index of the node used to calculate the position.

Since 1.0

— Function: clutter-path-get-length (self <clutter-path>) ⇒  (ret unsigned-int)
— Method: get-length

Retrieves an approximation of the total length of the path.

path
a <clutter-path>
ret
the length of the path.

Since 1.0

— Function: clutter-path-node-equal (self <clutter-path-node>) (node_b <clutter-path-node>) ⇒  (ret bool)

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

node-a
First node
node-b
Second node
ret
‘#t’ if the nodes are the same.

Since 1.0