1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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 #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>
|
