From f4e272ee9b6224cddc7eca54172025c5232e37bf Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 9 Sep 2009 16:01:07 +0100 Subject: [PATCH] [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. --- doc/reference/clutter/Makefile.am | 6 +- doc/reference/clutter/clutter-docs.xml.in | 1 + .../clutter/migrating-ClutterPath.xml | 167 ++++++++++++++++++ 3 files changed, 172 insertions(+), 2 deletions(-) create mode 100644 doc/reference/clutter/migrating-ClutterPath.xml 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 @@ + 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 @@ + + + + + + + Emmanuele + Bassi + +
+ ebassi@linux.intel.com +
+ + + + + Migrating to ClutterPath + + Between Clutter 0.8 and Clutter 1.0 the #ClutterBehaviourPath + behaviour lost all the path manipulation functions and the + ClutterBehaviourBspline class was entirely + deprecated. + + The class that replaced the path description and manipulation + functionality is called #ClutterPath. A #ClutterPath allows + describing a path using a sequence of #ClutterPahtNodes 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. + + Finally, #ClutterPath also provides integration with Cairo, + by being able to add paths described by the Cairo + cairo_path_t data structure and being able + to "replay" a #ClutterPath onto a cairo_t + Cairo context. + +
+ Creating a #ClutterPath + + Before Clutter 1.0, all the path-related functions inside + #ClutterBehaviourPath and ClutterBehaviourBspline + were replicated, but were also subtly different given the different nature + of the types of path handled by the two #ClutterBehaviours. + + + ClutterBehaviourPath example + 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. + + 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)); + + + + The construction for a B-Spline path behaviour was similar, though + the #ClutterKnots could only describe a curvilinear path. + + + Constructing ClutterPath + 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. + + 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); + + + + A #ClutterPath object can be shared across behaviours, just + like the #ClutterAlpha objects can. + + Path can be described by using a subset of the SVG notation for + paths as well as using #ClutterPathNode structures. + + + Describing ClutterPath + 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. + + 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 */); + + + + A #ClutterPath can describe not only linear, closed paths; it + can also describe paths with Beziér curvers and can add gaps. + + + Describing a mixed ClutterPath + A mixed #ClutterPath, with a Beziér curve between the point + at 200, 200 and 100, 100 and both control points in 100, 200. + + 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"); + + + +
+ +
+ Iterating over a #ClutterPath + + It is possible to iterate over all the #ClutterPathNodes + inside a #ClutterPath by using clutter_path_get_nodes(), which will return + a #GSList of #ClutterPathNodes; or by using clutter_path_foreach() + with a function. + + The function pointer passed to clutter_path_foreach() should have the + following definition: + + + static void + foreach_node (ClutterPathNode *path_node, + gpointer user_data) + { + } + +
+ +
+ Integration with Cairo + + A #ClutterPath can use a previously defined + cairo_path_t to add new nodes, by using + the clutter_path_add_cairo_path() function. + + 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. +
+ +