mutter/doc/reference/migrating-ClutterPath.xml
Emmanuele Bassi 67bf902022 Move API reference down one level
Since we only have one API reference, we can drop the clutter/
sub-level, and have all the files under doc/reference.
2015-05-19 15:27:30 +01:00

168 lines
6.1 KiB
XML

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC
"-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="migrating-ClutterPath">
<chapterinfo>
<author>
<firstname>Emmanuele</firstname>
<surname>Bassi</surname>
<affiliation>
<address>
<email>ebassi@linux.intel.com</email>
</address>
</affiliation>
</author>
</chapterinfo>
<title>Migrating to ClutterPath</title>
<para>Between Clutter 0.8 and Clutter 1.0 the #ClutterBehaviourPath
behaviour lost all the path manipulation functions and the
<structname>ClutterBehaviourBspline</structname> class was entirely
deprecated.</para>
<para>The class that replaced the path description and manipulation
functionality is called #ClutterPath. A #ClutterPath allows
describing a path using a sequence of #ClutterPathNode<!-- -->s or
using a subset of the SVG path description syntax. A Path instance
also allows describing complex paths, with linear and Bezier segments
and with gaps.</para>
<para>Finally, #ClutterPath also provides integration with Cairo,
by being able to add paths described by the Cairo
<structname>cairo_path_t</structname> data structure and being able
to "replay" a #ClutterPath onto a <structname>cairo_t</structname>
Cairo context.</para>
<section id="creating-paths">
<title>Creating a #ClutterPath</title>
<para>Before Clutter 1.0, all the path-related functions inside
#ClutterBehaviourPath and <structname>ClutterBehaviourBspline</structname>
were replicated, but were also subtly different given the different nature
of the types of path handled by the two #ClutterBehaviour<!-- -->s.</para>
<example id="example-clutter-behaviour-path">
<title>ClutterBehaviourPath example</title>
<para>The following code shows how a #ClutterBehaviourPath was
created prior to the introduction of #ClutterPath. The path described
is a square box between 100, 100 and 200, 200.</para>
<programlisting>
ClutterBehaviour *behaviour;
ClutterKnot knots[] = {
{ 100, 100 },
{ 200, 100 },
{ 200, 200 },
{ 100, 200 },
{ 100, 100 }
};
behaviour = clutter_behaviour_path_new (alpha, knots, G_N_ELEMENTS (knots));
</programlisting>
</example>
<para>The construction for a B-Spline path behaviour was similar, though
the #ClutterKnot<!-- -->s could only describe a curvilinear path.</para>
<example id="example-construct-clutter-path">
<title>Constructing ClutterPath</title>
<para>The following code shows how to construct a #ClutterPath and
assign it to a #ClutterBehaviourPath. The created path is the same as
the example above.</para>
<programlisting>
ClutterBehaviour *behaviour;
ClutterPath *path;
path = clutter_path_new ();
clutter_path_add_move_to (path, 100, 100);
clutter_path_add_line_to (path, 200, 100);
clutter_path_add_line_to (path, 200, 200);
clutter_path_add_line_to (path, 100, 200);
clutter_path_add_close (path);
behaviour = clutter_behaviour_path_new (alpha, path);
</programlisting>
</example>
<para><note>A #ClutterPath object can be shared across behaviours, just
like the #ClutterAlpha objects can.</note></para>
<para>Path can be described by using a subset of the SVG notation for
paths as well as using #ClutterPathNode structures.</para>
<example id="example-describe-clutter-path">
<title>Describing ClutterPath</title>
<para>The SVG path notation subset used by #ClutterPath is in
string format and can be both set as the whole path description
using clutter_path_set_description() or can be added to an
existing #ClutterPath using clutter_path_add_string(). The following
example shows the same path as the two examples above.</para>
<programlisting>
ClutterPath *path = clutter_path_new ();
clutter_path_set_description (path,
"M 100,100 " /* move to */
"L 200,100 " /* line to */
"L 200,200 "
"L 100,200 "
"z" /* close */);
</programlisting>
</example>
<para>A #ClutterPath can describe not only linear, closed paths; it
can also describe paths with Beziér curvers and can add gaps.</para>
<example id="example-describe-mixed-clutter-path">
<title>Describing a mixed ClutterPath</title>
<para>A mixed #ClutterPath, with a Beziér curve between the point
at 200, 200 and 100, 100 and both control points in 100, 200.</para>
<programlisting>
ClutterPath *path = clutter_path_new ();
clutter_path_set_description (path,
"M 100,100 "
"L 200,100 "
"L 200,200 "
"C 100,200 100,200 100,100");
</programlisting>
</example>
</section>
<section id="iterating-paths">
<title>Iterating over a #ClutterPath</title>
<para>It is possible to iterate over all the #ClutterPathNode<!-- -->s
inside a #ClutterPath by using clutter_path_get_nodes(), which will return
a #GSList of #ClutterPathNode<!-- -->s; or by using clutter_path_foreach()
with a function.</para>
<para>The function pointer passed to clutter_path_foreach() should have the
following definition:</para>
<informalexample><programlisting>
static void
foreach_node (ClutterPathNode *path_node,
gpointer user_data)
{
}
</programlisting></informalexample>
</section>
<section id="using-cairo">
<title>Integration with Cairo</title>
<para>A #ClutterPath can use a previously defined
<structname>cairo_path_t</structname> to add new nodes, by using
the clutter_path_add_cairo_path() function.</para>
<para>It is also possible to paint a #ClutterPath on a Cairo context,
by moving the Cairo pen across the nodes of the path using the
clutter_path_to_cairo_path() function.</para>
</section>
</chapter>