1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>ClutterCanvas</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="index.html" title="Clutter Reference Manual">
8 <link rel="up" href="ch07.html" title="Content">
9 <link rel="prev" href="ch07.html" title="Content">
10 <link rel="next" href="clutter-ClutterImage.html" title="ClutterImage">
11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17 <td><a accesskey="p" href="ch07.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="ch07.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">Clutter Reference Manual</th>
21 <td><a accesskey="n" href="clutter-ClutterImage.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#ClutterCanvas.synopsis" class="shortcut">Top</a>
26 <a href="#ClutterCanvas.description" class="shortcut">Description</a>
28 <a href="#ClutterCanvas.object-hierarchy" class="shortcut">Object Hierarchy</a>
30 <a href="#ClutterCanvas.implemented-interfaces" class="shortcut">Implemented Interfaces</a>
32 <a href="#ClutterCanvas.properties" class="shortcut">Properties</a>
34 <a href="#ClutterCanvas.signals" class="shortcut">Signals</a>
37 <div class="refentry">
38 <a name="ClutterCanvas"></a><div class="titlepage"></div>
39 <div class="refnamediv"><table width="100%"><tr>
41 <h2><span class="refentrytitle"><a name="ClutterCanvas.top_of_page"></a>ClutterCanvas</span></h2>
42 <p>ClutterCanvas — Content for 2D painting</p>
44 <td valign="top" align="right"></td>
46 <div class="refsynopsisdiv">
47 <a name="ClutterCanvas.synopsis"></a><h2>Synopsis</h2>
48 <pre class="synopsis">struct <a class="link" href="ClutterCanvas.html#ClutterCanvas-struct" title="struct ClutterCanvas">ClutterCanvas</a>;
49 struct <a class="link" href="ClutterCanvas.html#ClutterCanvasClass" title="struct ClutterCanvasClass">ClutterCanvasClass</a>;
50 <a class="link" href="ClutterContent.html" title="ClutterContent"><span class="returnvalue">ClutterContent</span></a> * <a class="link" href="ClutterCanvas.html#clutter-canvas-new" title="clutter_canvas_new ()">clutter_canvas_new</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
51 <span class="returnvalue">void</span> <a class="link" href="ClutterCanvas.html#clutter-canvas-set-size" title="clutter_canvas_set_size ()">clutter_canvas_set_size</a> (<em class="parameter"><code><a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> *canvas</code></em>,
52 <em class="parameter"><code><span class="type">int</span> width</code></em>,
53 <em class="parameter"><code><span class="type">int</span> height</code></em>);
56 <div class="refsect1">
57 <a name="ClutterCanvas.object-hierarchy"></a><h2>Object Hierarchy</h2>
58 <pre class="synopsis">
59 <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
63 <div class="refsect1">
64 <a name="ClutterCanvas.implemented-interfaces"></a><h2>Implemented Interfaces</h2>
66 ClutterCanvas implements
67 <a class="link" href="ClutterContent.html" title="ClutterContent">ClutterContent</a>.</p>
69 <div class="refsect1">
70 <a name="ClutterCanvas.properties"></a><h2>Properties</h2>
71 <pre class="synopsis">
72 "<a class="link" href="ClutterCanvas.html#ClutterCanvas--height" title='The "height" property'>height</a>" <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write
73 "<a class="link" href="ClutterCanvas.html#ClutterCanvas--width" title='The "width" property'>width</a>" <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write
76 <div class="refsect1">
77 <a name="ClutterCanvas.signals"></a><h2>Signals</h2>
78 <pre class="synopsis">
79 "<a class="link" href="ClutterCanvas.html#ClutterCanvas-draw" title='The "draw" signal'>draw</a>" : <a href="../gobject/gobject-Signals.html#G-SIGNAL-NO-RECURSE:CAPS"><code class="literal">No Recursion</code></a>
82 <div class="refsect1">
83 <a name="ClutterCanvas.description"></a><h2>Description</h2>
85 The <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> class is a <a class="link" href="ClutterContent.html" title="ClutterContent"><span class="type">ClutterContent</span></a> implementation that allows
86 drawing using the Cairo API on a 2D surface.
89 In order to draw on a <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a>, you should connect a handler to the
90 <a class="link" href="ClutterCanvas.html#ClutterCanvas-draw" title='The "draw" signal'><span class="type">"draw"</span></a> signal; the signal will receive a <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-t"><span class="type">cairo_t</span></a> context
91 that can be used to draw. <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> will emit the <a class="link" href="ClutterCanvas.html#ClutterCanvas-draw" title='The "draw" signal'><span class="type">"draw"</span></a>
92 signal when invalidated using <a class="link" href="ClutterContent.html#clutter-content-invalidate" title="clutter_content_invalidate ()"><code class="function">clutter_content_invalidate()</code></a>.
96 <div class="informalexample">
97 <a name="canvas-example"></a><pre class="programlisting">
98 #include <stdlib.h>
99 #include <math.h>
100 #include <cairo.h>
101 #include <clutter/clutter.h>
104 draw_clock (ClutterCanvas *canvas,
110 float hours, minutes, seconds;
113 /* get the current time and compute the angles */
114 now = g_date_time_new_now_local ();
115 seconds = g_date_time_get_second (now) * G_PI / 30;
116 minutes = g_date_time_get_minute (now) * G_PI / 30;
117 hours = g_date_time_get_hour (now) * G_PI / 6;
121 /* clear the contents of the canvas, to avoid painting
122 * over the previous frame
124 cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
129 cairo_set_operator (cr, CAIRO_OPERATOR_OVER);
131 /* scale the modelview to the size of the surface */
132 cairo_scale (cr, width, height);
134 cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
135 cairo_set_line_width (cr, 0.1);
137 /* the black rail that holds the seconds indicator */
138 clutter_cairo_set_source_color (cr, CLUTTER_COLOR_Black);
139 cairo_translate (cr, 0.5, 0.5);
140 cairo_arc (cr, 0, 0, 0.4, 0, G_PI * 2);
143 /* the seconds indicator */
144 color = *CLUTTER_COLOR_White;
146 clutter_cairo_set_source_color (cr, &color);
147 cairo_move_to (cr, 0, 0);
148 cairo_arc (cr, sinf (seconds) * 0.4, - cosf (seconds) * 0.4, 0.05, 0, G_PI * 2);
151 /* the minutes hand */
152 color = *CLUTTER_COLOR_DarkChameleon;
154 clutter_cairo_set_source_color (cr, &color);
155 cairo_move_to (cr, 0, 0);
156 cairo_line_to (cr, sinf (minutes) * 0.4, -cosf (minutes) * 0.4);
160 cairo_move_to (cr, 0, 0);
161 cairo_line_to (cr, sinf (hours) * 0.2, -cosf (hours) * 0.2);
164 g_date_time_unref (now);
166 /* we're done drawing */
171 invalidate_clock (gpointer data_)
173 /* invalidate the contents of the canvas */
174 clutter_content_invalidate (data_);
176 /* keep the timeout source */
181 test_canvas_main (int argc, char *argv[])
183 ClutterActor *stage, *actor;
184 ClutterContent *canvas;
186 /* initialize Clutter */
187 if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
190 /* create a resizable stage */
191 stage = clutter_stage_new ();
192 clutter_stage_set_title (CLUTTER_STAGE (stage), "2D Clock");
193 clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
194 clutter_actor_set_background_color (stage, CLUTTER_COLOR_LightSkyBlue);
195 clutter_actor_set_size (stage, 300, 300);
196 clutter_actor_show (stage);
198 /* our 2D canvas, courtesy of Cairo */
199 canvas = clutter_canvas_new ();
200 clutter_canvas_set_size (CLUTTER_CANVAS (canvas), 300, 300);
202 actor = clutter_actor_new ();
203 clutter_actor_set_content (actor, canvas);
204 clutter_actor_set_content_scaling_filters (actor,
205 CLUTTER_SCALING_FILTER_TRILINEAR,
206 CLUTTER_SCALING_FILTER_LINEAR);
207 clutter_actor_add_child (stage, actor);
209 /* the actor now owns the canvas */
210 g_object_unref (canvas);
212 /* bind the size of the actor to that of the stage */
213 clutter_actor_add_constraint (actor, clutter_bind_constraint_new (stage, CLUTTER_BIND_SIZE, 0));
215 /* quit on destroy */
216 g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
218 /* connect our drawing code */
219 g_signal_connect (canvas, "draw", G_CALLBACK (draw_clock), NULL);
221 /* invalidate the canvas, so that we can draw before the main loop starts */
222 clutter_content_invalidate (canvas);
224 /* set up a timer that invalidates the canvas every second */
225 clutter_threads_add_timeout (1000, invalidate_clock, canvas);
232 G_MODULE_EXPORT const char *
233 test_canvas_describe (void)
235 return "Simple 2D clock using the Canvas content";
243 <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> is available since Clutter 1.10.
246 <div class="refsect1">
247 <a name="ClutterCanvas.details"></a><h2>Details</h2>
248 <div class="refsect2">
249 <a name="ClutterCanvas-struct"></a><h3>struct ClutterCanvas</h3>
250 <pre class="programlisting">struct ClutterCanvas;</pre>
252 The <span class="structname">ClutterCanvas</span> structure contains
253 private data and should only be accessed using the provided
256 <p class="since">Since 1.10</p>
259 <div class="refsect2">
260 <a name="ClutterCanvasClass"></a><h3>struct ClutterCanvasClass</h3>
261 <pre class="programlisting">struct ClutterCanvasClass {
262 gboolean (* draw) (ClutterCanvas *canvas,
269 The <span class="structname">ClutterCanvasClass</span> structure contains
272 <div class="variablelist"><table border="0">
273 <col align="left" valign="top">
275 <td><p><span class="term"><em class="structfield"><code><a name="ClutterCanvasClass.draw"></a>draw</code></em> ()</span></p></td>
276 <td>class handler for the <a class="link" href="ClutterCanvas.html#ClutterCanvas-draw" title='The "draw" signal'><span class="type">"draw"</span></a> signal</td>
279 <p class="since">Since 1.10</p>
282 <div class="refsect2">
283 <a name="clutter-canvas-new"></a><h3>clutter_canvas_new ()</h3>
284 <pre class="programlisting"><a class="link" href="ClutterContent.html" title="ClutterContent"><span class="returnvalue">ClutterContent</span></a> * clutter_canvas_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
286 Creates a new instance of <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a>.
289 You should call <a class="link" href="ClutterCanvas.html#clutter-canvas-set-size" title="clutter_canvas_set_size ()"><code class="function">clutter_canvas_set_size()</code></a> to set the size of the canvas.
292 You should call <a class="link" href="ClutterContent.html#clutter-content-invalidate" title="clutter_content_invalidate ()"><code class="function">clutter_content_invalidate()</code></a> every time you wish to
293 draw the contents of the canvas.
295 <div class="variablelist"><table border="0">
296 <col align="left" valign="top">
298 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
299 <td>The newly allocated instance of
300 <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a>. Use <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> when done. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
304 <p class="since">Since 1.10</p>
307 <div class="refsect2">
308 <a name="clutter-canvas-set-size"></a><h3>clutter_canvas_set_size ()</h3>
309 <pre class="programlisting"><span class="returnvalue">void</span> clutter_canvas_set_size (<em class="parameter"><code><a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> *canvas</code></em>,
310 <em class="parameter"><code><span class="type">int</span> width</code></em>,
311 <em class="parameter"><code><span class="type">int</span> height</code></em>);</pre>
313 Sets the size of the <em class="parameter"><code>canvas</code></em>.
316 This function will cause the <em class="parameter"><code>canvas</code></em> to be invalidated.
318 <div class="variablelist"><table border="0">
319 <col align="left" valign="top">
322 <td><p><span class="term"><em class="parameter"><code>canvas</code></em> :</span></p></td>
323 <td>a <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a>
327 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
328 <td>the width of the canvas, in pixels</td>
331 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
332 <td>the height of the canvas, in pixels</td>
336 <p class="since">Since 1.10</p>
339 <div class="refsect1">
340 <a name="ClutterCanvas.property-details"></a><h2>Property Details</h2>
341 <div class="refsect2">
342 <a name="ClutterCanvas--height"></a><h3>The <code class="literal">"height"</code> property</h3>
343 <pre class="programlisting"> "height" <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write</pre>
345 The height of the canvas.
347 <p>Allowed values: >= G_MAXULONG</p>
348 <p>Default value: -1</p>
349 <p class="since">Since 1.10</p>
352 <div class="refsect2">
353 <a name="ClutterCanvas--width"></a><h3>The <code class="literal">"width"</code> property</h3>
354 <pre class="programlisting"> "width" <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write</pre>
356 The width of the canvas.
358 <p>Allowed values: >= G_MAXULONG</p>
359 <p>Default value: -1</p>
360 <p class="since">Since 1.10</p>
363 <div class="refsect1">
364 <a name="ClutterCanvas.signal-details"></a><h2>Signal Details</h2>
365 <div class="refsect2">
366 <a name="ClutterCanvas-draw"></a><h3>The <code class="literal">"draw"</code> signal</h3>
367 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> user_function (<a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> *canvas,
368 <span class="type">CairoContext</span> *cr,
369 <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> width,
370 <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> height,
371 <a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data) : <a href="../gobject/gobject-Signals.html#G-SIGNAL-NO-RECURSE:CAPS"><code class="literal">No Recursion</code></a></pre>
373 The <a class="link" href="ClutterCanvas.html#ClutterCanvas-draw" title='The "draw" signal'><span class="type">"draw"</span></a> signal is emitted each time a canvas is
377 It is safe to connect multiple handlers to this signal: each
378 handler invocation will be automatically protected by <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-save"><code class="function">cairo_save()</code></a>
379 and <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-restore"><code class="function">cairo_restore()</code></a> pairs.
381 <div class="variablelist"><table border="0">
382 <col align="left" valign="top">
385 <td><p><span class="term"><em class="parameter"><code>canvas</code></em> :</span></p></td>
386 <td>the <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> that emitted the signal</td>
389 <td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
390 <td>the Cairo context used to draw</td>
393 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
394 <td>the width of the <em class="parameter"><code>canvas</code></em>
398 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
399 <td>the height of the <em class="parameter"><code>canvas</code></em>
403 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
404 <td>user data set when the signal handler was connected.</td>
407 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
409 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the signal emission should stop, and
410 <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</td>
414 <p class="since">Since 1.10</p>
417 <div class="refsect1">
418 <a name="ClutterCanvas.see-also"></a><h2>See Also</h2>
419 <a class="link" href="ClutterContent.html" title="ClutterContent"><span class="type">ClutterContent</span></a>
424 Generated by GTK-Doc V1.18.1</div>