diff --git a/doc/reference/clutter/Makefile.am b/doc/reference/clutter/Makefile.am index 31eaa93ea..ebaef2b7c 100644 --- a/doc/reference/clutter/Makefile.am +++ b/doc/reference/clutter/Makefile.am @@ -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 diff --git a/doc/reference/clutter/clutter-docs.xml.in b/doc/reference/clutter/clutter-docs.xml.in index 5e43d3b29..8632a5026 100644 --- a/doc/reference/clutter/clutter-docs.xml.in +++ b/doc/reference/clutter/clutter-docs.xml.in @@ -187,6 +187,7 @@ </partintro> <xi:include href="xml/migrating-ClutterEffect.xml"/> + <xi:include href="xml/migrating-ClutterPath.xml"/> </part> diff --git a/doc/reference/clutter/migrating-ClutterPath.xml b/doc/reference/clutter/migrating-ClutterPath.xml new file mode 100644 index 000000000..8323d5863 --- /dev/null +++ b/doc/reference/clutter/migrating-ClutterPath.xml @@ -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>