doc/reference/clutter/html/ClutterCanvas.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   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">
  13 </head>
  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">
  16 <tr valign="middle">
  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>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#ClutterCanvas.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#ClutterCanvas.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#ClutterCanvas.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29                    |
  30                   <a href="#ClutterCanvas.implemented-interfaces" class="shortcut">Implemented Interfaces</a>
  31                    |
  32                   <a href="#ClutterCanvas.properties" class="shortcut">Properties</a>
  33                    |
  34                   <a href="#ClutterCanvas.signals" class="shortcut">Signals</a>
  35 </td></tr>
  36 </table>
  37 <div class="refentry">
  38 <a name="ClutterCanvas"></a><div class="titlepage"></div>
  39 <div class="refnamediv"><table width="100%"><tr>
  40 <td valign="top">
  41 <h2><span class="refentrytitle"><a name="ClutterCanvas.top_of_page"></a>ClutterCanvas</span></h2>
  42 <p>ClutterCanvas — Content for 2D painting</p>
  43 </td>
  44 <td valign="top" align="right"></td>
  45 </tr></table></div>
  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>);
  54 </pre>
  55 </div>
  56 <div class="refsect1">
  57 <a name="ClutterCanvas.object-hierarchy"></a><h2>Object Hierarchy</h2>
  58 <pre class="synopsis">
  59   GObject
  60    +----ClutterCanvas
  61 </pre>
  62 </div>
  63 <div class="refsect1">
  64 <a name="ClutterCanvas.implemented-interfaces"></a><h2>Implemented Interfaces</h2>
  65 <p>
  66 ClutterCanvas implements
  67  <a class="link" href="ClutterContent.html" title="ClutterContent">ClutterContent</a>.</p>
  68 </div>
  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>"                   <span class="type">gint</span>                  : Read / Write
  73   "<a class="link" href="ClutterCanvas.html#ClutterCanvas--width" title='The "width" property'>width</a>"                    <span class="type">gint</span>                  : Read / Write
  74 </pre>
  75 </div>
  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>"                                           : <code class="literal">No Recursion</code>
  80 </pre>
  81 </div>
  82 <div class="refsect1">
  83 <a name="ClutterCanvas.description"></a><h2>Description</h2>
  84 <p>
  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.
  87 </p>
  88 <p>
  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>.
  93 </p>
  94 <p>
  95 </p>
  96 <div class="informalexample">
  97 <a name="canvas-example"></a><pre class="programlisting">
  98 #include &lt;stdlib.h&gt;
  99 #include &lt;math.h&gt;
 100 #include &lt;cairo.h&gt;
 101 #include &lt;clutter/clutter.h&gt;
 102
 103 static gboolean
 104 draw_clock (ClutterCanvas *canvas,
 105             cairo_t       *cr,
 106             int            width,
 107             int            height)
 108 {
 109   GDateTime *now;
 110   float hours, minutes, seconds;
 111   ClutterColor color;
 112
 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;
 118
 119   cairo_save (cr);
 120
 121   /* clear the contents of the canvas, to avoid painting
 122    * over the previous frame
 123    */
 124   cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
 125   cairo_paint (cr);
 126
 127   cairo_restore (cr);
 128
 129   cairo_set_operator (cr, CAIRO_OPERATOR_OVER);
 130
 131   /* scale the modelview to the size of the surface */
 132   cairo_scale (cr, width, height);
 133
 134   cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
 135   cairo_set_line_width (cr, 0.1);
 136
 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);
 141   cairo_stroke (cr);
 142
 143   /* the seconds indicator */
 144   color = *CLUTTER_COLOR_White;
 145   color.alpha = 128;
 146   clutter_cairo_set_source_color (cr, &amp;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);
 149   cairo_fill (cr);
 150
 151   /* the minutes hand */
 152   color = *CLUTTER_COLOR_DarkChameleon;
 153   color.alpha = 196;
 154   clutter_cairo_set_source_color (cr, &amp;color);
 155   cairo_move_to (cr, 0, 0);
 156   cairo_line_to (cr, sinf (minutes) * 0.4, -cosf (minutes) * 0.4);
 157   cairo_stroke (cr);
 158
 159   /* the hours hand */
 160   cairo_move_to (cr, 0, 0);
 161   cairo_line_to (cr, sinf (hours) * 0.2, -cosf (hours) * 0.2);
 162   cairo_stroke (cr);
 163
 164   g_date_time_unref (now);
 165
 166   /* we're done drawing */
 167   return TRUE;
 168 }
 169
 170 static gboolean
 171 invalidate_clock (gpointer data_)
 172 {
 173   /* invalidate the contents of the canvas */
 174   clutter_content_invalidate (data_);
 175
 176   /* keep the timeout source */
 177   return TRUE;
 178 }
 179
 180 G_MODULE_EXPORT int
 181 test_canvas_main (int argc, char *argv[])
 182 {
 183   ClutterActor *stage, *actor;
 184   ClutterContent *canvas;
 185
 186   /* initialize Clutter */
 187   if (clutter_init (&amp;argc, &amp;argv) != CLUTTER_INIT_SUCCESS)
 188     return EXIT_FAILURE;
 189
 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);
 197
 198   /* our 2D canvas, courtesy of Cairo */
 199   canvas = clutter_canvas_new ();
 200   clutter_canvas_set_size (CLUTTER_CANVAS (canvas), 300, 300);
 201
 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);
 208
 209   /* the actor now owns the canvas */
 210   g_object_unref (canvas);
 211
 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));
 214
 215   /* quit on destroy */
 216   g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
 217
 218   /* connect our drawing code */
 219   g_signal_connect (canvas, "draw", G_CALLBACK (draw_clock), NULL);
 220
 221   /* invalidate the canvas, so that we can draw before the main loop starts */
 222   clutter_content_invalidate (canvas);
 223
 224   /* set up a timer that invalidates the canvas every second */
 225   clutter_threads_add_timeout (1000, invalidate_clock, canvas);
 226
 227   clutter_main ();
 228
 229   return EXIT_SUCCESS;
 230 }
 231
 232 G_MODULE_EXPORT const char *
 233 test_canvas_describe (void)
 234 {
 235   return "Simple 2D clock using the Canvas content";
 236 }
 237
 238   </pre>
 239 </div>
 240 <p>
 241 </p>
 242 <p>
 243 <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a> is available since Clutter 1.10.
 244 </p>
 245 </div>
 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>
 251 <p>
 252 The <span class="structname">ClutterCanvas</span> structure contains
 253 private data and should only be accessed using the provided
 254 API.
 255 </p>
 256 <p class="since">Since 1.10</p>
 257 </div>
 258 <hr>
 259 <div class="refsect2">
 260 <a name="ClutterCanvasClass"></a><h3>struct ClutterCanvasClass</h3>
 261 <pre class="programlisting">struct ClutterCanvasClass {
 262   gboolean (* draw) (ClutterCanvas *canvas,
 263                      cairo_t       *cr,
 264                      int            width,
 265                      int            height);
 266 };
 267 </pre>
 268 <p>
 269 The <span class="structname">ClutterCanvasClass</span> structure contains
 270 private data.
 271 </p>
 272 <div class="variablelist"><table border="0">
 273 <col align="left" valign="top">
 274 <tbody><tr>
 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>
 277 </tr></tbody>
 278 </table></div>
 279 <p class="since">Since 1.10</p>
 280 </div>
 281 <hr>
 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>
 285 <p>
 286 Creates a new instance of <a class="link" href="ClutterCanvas.html" title="ClutterCanvas"><span class="type">ClutterCanvas</span></a>.
 287 </p>
 288 <p>
 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.
 290 </p>
 291 <p>
 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.
 294 </p>
 295 <div class="variablelist"><table border="0">
 296 <col align="left" valign="top">
 297 <tbody><tr>
 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 <code class="function">g_object_unref()</code> when done. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 301 </td>
 302 </tr></tbody>
 303 </table></div>
 304 <p class="since">Since 1.10</p>
 305 </div>
 306 <hr>
 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>
 312 <p>
 313 Sets the size of the <em class="parameter"><code>canvas</code></em>.
 314 </p>
 315 <p>
 316 This function will cause the <em class="parameter"><code>canvas</code></em> to be invalidated.
 317 </p>
 318 <div class="variablelist"><table border="0">
 319 <col align="left" valign="top">
 320 <tbody>
 321 <tr>
 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>
 324 </td>
 325 </tr>
 326 <tr>
 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>
 329 </tr>
 330 <tr>
 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>
 333 </tr>
 334 </tbody>
 335 </table></div>
 336 <p class="since">Since 1.10</p>
 337 </div>
 338 </div>
 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"                   <span class="type">gint</span>                  : Read / Write</pre>
 344 <p>
 345 The height of the canvas.
 346 </p>
 347 <p>Allowed values: &gt;= G_MAXULONG</p>
 348 <p>Default value: -1</p>
 349 <p class="since">Since 1.10</p>
 350 </div>
 351 <hr>
 352 <div class="refsect2">
 353 <a name="ClutterCanvas--width"></a><h3>The <code class="literal">"width"</code> property</h3>
 354 <pre class="programlisting">  "width"                    <span class="type">gint</span>                  : Read / Write</pre>
 355 <p>
 356 The width of the canvas.
 357 </p>
 358 <p>Allowed values: &gt;= G_MAXULONG</p>
 359 <p>Default value: -1</p>
 360 <p class="since">Since 1.10</p>
 361 </div>
 362 </div>
 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"><span class="returnvalue">gboolean</span>            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                                                         <span class="type">gint</span>           width,
 370                                                         <span class="type">gint</span>           height,
 371                                                         <span class="type">gpointer</span>       user_data)      : <code class="literal">No Recursion</code></pre>
 372 <p>
 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
 374 invalidated.
 375 </p>
 376 <p>
 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.
 380 </p>
 381 <div class="variablelist"><table border="0">
 382 <col align="left" valign="top">
 383 <tbody>
 384 <tr>
 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>
 387 </tr>
 388 <tr>
 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>
 391 </tr>
 392 <tr>
 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>
 395 </td>
 396 </tr>
 397 <tr>
 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>
 400 </td>
 401 </tr>
 402 <tr>
 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>
 405 </tr>
 406 <tr>
 407 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 408 <td>
 409 <code class="literal">TRUE</code> if the signal emission should stop, and
 410 <code class="literal">FALSE</code> otherwise</td>
 411 </tr>
 412 </tbody>
 413 </table></div>
 414 <p class="since">Since 1.10</p>
 415 </div>
 416 </div>
 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>
 420 </div>
 421 </div>
 422 <div class="footer">
 423 <hr>
 424           Generated by GTK-Doc V1.18.1</div>
 425 </body>
 426 </html>