Clutter::Path(3) An object describing a path


A Clutter::Path contains a description of a path consisting of straight lines and Bezier curves. This can be used in a Clutter::BehaviourPath to animate an actor moving along the path.

The path consists of a series of nodes; see Clutter::PathNode for more information on the node notation.

You can build a path using the node adding functions such as Clutter::Path::add_line_to() or Clutter::Path::add_curve_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.




path = Clutter::Path->new ()

path = Clutter::Path->new ($description)

path = Clutter::Path->new ($node, ...)

Creates a new path.

The optional arguments can be a stringified definition of the path, using a subset of the SVG path syntax or a list of nodes, e.g.:

    Clutter::Path->new("M 10,10 L 200,200 z");
    # or the equivalent
        [ 'move-to', [ [ 10, 10 ] ] ],
        [ 'line-to', [ [ 200, 200 ] ] ],
        [ 'close' ],


Appends a 'close' node to path

$path->add_curve_to ($x1, $y1, $x2, $y2, $x3, $y3)

Appends a 'curve-to' node to path

$path->add_line_to ($x, $y)

Appends a 'line-to' node to path

$path->add_move_to ($x, $y)

Appends a 'move-to' node to path

$path->add_rel_curve_to ($x1, $y1, $x2, $y2, $x3, $y3)

Appends a 'rel-curve-to' node to path

$path->add_rel_line_to ($x, $y)

Appends a 'rel-line-to' node to path

$path->add_rel_move_to ($x, $y)

Appends a 'rel-move-to' node to path

$path->add_string ($description)

Adds new nodes to the end of the path as described in description.

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 - equivalent 'move-to'/'CLUTTER_PATH_MOVE_TO' =item m - equivalent 'rel-move-to'/'CLUTTER_PATH_REL_MOVE_TO'
Take one pair of coordinates
L - equivalent to 'line-to'/'CLUTTER_PATH_LINE_TO' =item l - equivalent to 'rel-line-to'/'CLUTTER_PATH_REL_LINE_TO'
Take one pair of coordinates
C - equivalent to 'curve-to'/'CLUTTER_PATH_CURVE_TO' =item c - equivalent to 'rel-curve-to'/'CLUTTER_PATH_REL_CURVE_TO'
Take three pairs of coordinates
z - equivalent to 'close'/'CLUTTER_PATH_CLOSE'
No coordinates needed

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

This function may croak on failure.


Clears the path and removes all the nodes inside it

string or undef = $path->get_description

boolean = $path->set_description ($description)

  • $description (string)

Replaces all the nodes in the path with nodes described in description.

See Clutter::Path::add_string() for the format of the path description.

$path->foreach ($func, $data=undef)

  • $func (scalar)
  • $data (scalar)

Invokes the code reference inside func for each node inside path.

The function will have the following parameters:

The current node in the path
The data passed to Clutter::Path::foreach()

$path->insert_node ($index, $node)

  • $index (integer)
  • $node (Clutter::Path::Node)

Inserts the given node at the given index

integer = $path->get_length

Retrieves an approximation of the total length of the path

integer = $path->get_n_nodes

Retrieves the number of nodes inside path

node = $path->get_node ($index)

  • $index (integer)

Retrieves the node at the given index

(nodes) = $path->get_nodes ()

Retrieves a list of all the nodes inside path

index = $path->get_position ($progress)

(index, knot) = $path->get_position ($progress)

  • $progress (double)

Retrieves the index of the node inside path at the relative position expressed as the progress over the current path's length

In array context this method will also return the knot with the position on the path given the value of progress.

The progress is a floating point value between 0.0 and 1.0; it usually comes from a Clutter::Alpha or a Clutter::Interval.

$path->remove_node ($index)

  • $index (integer)

Removes the node at the given index

$path->replace_node ($index, $node)

  • $index (integer)
  • $node (Clutter::Path::Node)

Replaces the current node at the given index with a new node

$path->to_cairo_path ($cr)

  • $cr (Cairo::Context)

Draws path on a Cairo::Context using the Cairo API

This method is useful in case you store a path as Clutter::Path and wish to paint it on a Clutter::CairoTexture


'description' (string : readable / writable / private)
SVG-style description of the path
'length' (Glib::UInt : readable / private)
An approximation of the total length of the path.


Copyright (C) 2006, 2007, 2008 OpenedHand Ltd

Copyright (C) 2009 Intel Corporation

This module is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU Lesser General Public Library version 2.1; or
  • the Artistic License, version 2.0.

See Clutter for the full copyright notice.