[docs] Add a Path migration guide
ClutterBehaviourPath has been changed and ClutterBehaviourBspline has been removed; now we use ClutterPath everywhere we need to describe a path. This warrants a chapter in the migration guide.
This commit is contained in:
Emmanuele Bassi
parent
3cc56b2b13
commit
f4e272ee9b
@ -120,7 +120,8 @@ content_files= \
|
||||
clutter-overview.xml \
|
||||
building-clutter.xml \
|
||||
running-clutter.xml \
|
||||
migrating-ClutterEffect.xml
|
||||
migrating-ClutterEffect.xml \
|
||||
migrating-ClutterPath.xml
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
# These files must be listed here *and* in content_files
|
||||
@ -133,7 +134,8 @@ expand_content_files= \
|
||||
clutter-overview.xml \
|
||||
building-clutter.xml \
|
||||
running-clutter.xml \
|
||||
migrating-ClutterEffect.xml
|
||||
migrating-ClutterEffect.xml \
|
||||
migrating-ClutterPath.xml
|
||||
|
||||
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
|
||||
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
|
||||
|
||||
@ -187,6 +187,7 @@
|
||||
</partintro>
|
||||
|
||||
<xi:include href="xml/migrating-ClutterEffect.xml"/>
|
||||
<xi:include href="xml/migrating-ClutterPath.xml"/>
|
||||
|
||||
</part>
|
||||
|
||||
|
||||
167
doc/reference/clutter/migrating-ClutterPath.xml
Normal file
167
doc/reference/clutter/migrating-ClutterPath.xml
Normal file
@ -0,0 +1,167 @@
|
||||
<?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 #ClutterPahtNode<!-- -->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>
|
||||
Loading…
Reference in New Issue
Block a user