doc/reference/clutter/html/clutter-General.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>General</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="ch11.html" title="General purpose API">
   9 <link rel="prev" href="ClutterInputDevice.html" title="ClutterInputDevice">
  10 <link rel="next" href="ClutterPath.html" title="ClutterPath">
  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="ClutterInputDevice.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="ch11.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="ClutterPath.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="#clutter-General.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#clutter-General.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="clutter-General"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="clutter-General.top_of_page"></a>General</span></h2>
  34 <p>General — Various 'global' clutter functions.</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="clutter-General.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">#define             <a class="link" href="clutter-General.html#CLUTTER-PRIORITY-REDRAW:CAPS" title="CLUTTER_PRIORITY_REDRAW">CLUTTER_PRIORITY_REDRAW</a>
  41
  42 enum                <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError">ClutterInitError</a>;
  43 <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="returnvalue">ClutterInitError</span></a>    <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()">clutter_init</a>                        (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
  44                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>);
  45 <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="returnvalue">ClutterInitError</span></a>    <a class="link" href="clutter-General.html#clutter-init-with-args" title="clutter_init_with_args ()">clutter_init_with_args</a>              (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
  46                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>,
  47                                                          <em class="parameter"><code>const <span class="type">char</span> *parameter_string</code></em>,
  48                                                          <em class="parameter"><code><a href="../glib/glib-Commandline-option-parser.html#GOptionEntry"><span class="type">GOptionEntry</span></a> *entries</code></em>,
  49                                                          <em class="parameter"><code>const <span class="type">char</span> *translation_domain</code></em>,
  50                                                          <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  51 <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="returnvalue">GOptionGroup</span></a> *      <a class="link" href="clutter-General.html#clutter-get-option-group" title="clutter_get_option_group ()">clutter_get_option_group</a>            (<em class="parameter"><code><span class="type">void</span></code></em>);
  52 <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="returnvalue">GOptionGroup</span></a> *      <a class="link" href="clutter-General.html#clutter-get-option-group-without-init" title="clutter_get_option_group_without_init ()">clutter_get_option_group_without_init</a>
  53                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);
  54
  55 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-main" title="clutter_main ()">clutter_main</a>                        (<em class="parameter"><code><span class="type">void</span></code></em>);
  56 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-main-quit" title="clutter_main_quit ()">clutter_main_quit</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
  57 <a href="../glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a>                <a class="link" href="clutter-General.html#clutter-main-level" title="clutter_main_level ()">clutter_main_level</a>                  (<em class="parameter"><code><span class="type">void</span></code></em>);
  58
  59 <a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="clutter-General.html#clutter-get-debug-enabled" title="clutter_get_debug_enabled ()">clutter_get_debug_enabled</a>           (<em class="parameter"><code><span class="type">void</span></code></em>);
  60 <a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="clutter-General.html#clutter-get-show-fps" title="clutter_get_show_fps ()">clutter_get_show_fps</a>                (<em class="parameter"><code><span class="type">void</span></code></em>);
  61 <a href="../glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>              <a class="link" href="clutter-General.html#clutter-get-timestamp" title="clutter_get_timestamp ()">clutter_get_timestamp</a>               (<em class="parameter"><code><span class="type">void</span></code></em>);
  62 <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      <a class="link" href="clutter-General.html#clutter-get-actor-by-gid" title="clutter_get_actor_by_gid ()">clutter_get_actor_by_gid</a>            (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint32"><span class="type">guint32</span></a> id_</code></em>);
  63 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-set-default-frame-rate" title="clutter_set_default_frame_rate ()">clutter_set_default_frame_rate</a>      (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> frames_per_sec</code></em>);
  64 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-get-default-frame-rate" title="clutter_get_default_frame_rate ()">clutter_get_default_frame_rate</a>      (<em class="parameter"><code><span class="type">void</span></code></em>);
  65 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-set-motion-events-enabled" title="clutter_set_motion_events_enabled ()">clutter_set_motion_events_enabled</a>   (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> enable</code></em>);
  66 <a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="clutter-General.html#clutter-get-motion-events-enabled" title="clutter_get_motion_events_enabled ()">clutter_get_motion_events_enabled</a>   (<em class="parameter"><code><span class="type">void</span></code></em>);
  67 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-clear-glyph-cache" title="clutter_clear_glyph_cache ()">clutter_clear_glyph_cache</a>           (<em class="parameter"><code><span class="type">void</span></code></em>);
  68 enum                <a class="link" href="clutter-General.html#ClutterFontFlags" title="enum ClutterFontFlags">ClutterFontFlags</a>;
  69 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-set-font-flags" title="clutter_set_font_flags ()">clutter_set_font_flags</a>              (<em class="parameter"><code><a class="link" href="clutter-General.html#ClutterFontFlags" title="enum ClutterFontFlags"><span class="type">ClutterFontFlags</span></a> flags</code></em>);
  70 <a class="link" href="clutter-General.html#ClutterFontFlags" title="enum ClutterFontFlags"><span class="returnvalue">ClutterFontFlags</span></a>    <a class="link" href="clutter-General.html#clutter-get-font-flags" title="clutter_get_font_flags ()">clutter_get_font_flags</a>              (<em class="parameter"><code><span class="type">void</span></code></em>);
  71 <a href="../pango/pango-Fonts.html#PangoFontMap"><span class="returnvalue">PangoFontMap</span></a> *      <a class="link" href="clutter-General.html#clutter-get-font-map" title="clutter_get_font_map ()">clutter_get_font_map</a>                (<em class="parameter"><code><span class="type">void</span></code></em>);
  72 enum                <a class="link" href="clutter-General.html#ClutterTextDirection" title="enum ClutterTextDirection">ClutterTextDirection</a>;
  73 <a class="link" href="clutter-General.html#ClutterTextDirection" title="enum ClutterTextDirection"><span class="returnvalue">ClutterTextDirection</span></a> <a class="link" href="clutter-General.html#clutter-get-default-text-direction" title="clutter_get_default_text_direction ()">clutter_get_default_text_direction</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
  74 <a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="clutter-General.html#clutter-get-accessibility-enabled" title="clutter_get_accessibility_enabled ()">clutter_get_accessibility_enabled</a>   (<em class="parameter"><code><span class="type">void</span></code></em>);
  75
  76 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-threads-set-lock-functions" title="clutter_threads_set_lock_functions ()">clutter_threads_set_lock_functions</a>  (<em class="parameter"><code><a href="../gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> enter_fn</code></em>,
  77                                                          <em class="parameter"><code><a href="../gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> leave_fn</code></em>);
  78 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-threads-init" title="clutter_threads_init ()">clutter_threads_init</a>                (<em class="parameter"><code><span class="type">void</span></code></em>);
  79 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-threads-enter" title="clutter_threads_enter ()">clutter_threads_enter</a>               (<em class="parameter"><code><span class="type">void</span></code></em>);
  80 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-threads-leave" title="clutter_threads_leave ()">clutter_threads_leave</a>               (<em class="parameter"><code><span class="type">void</span></code></em>);
  81 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-idle" title="clutter_threads_add_idle ()">clutter_threads_add_idle</a>            (<em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  82                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  83 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-idle-full" title="clutter_threads_add_idle_full ()">clutter_threads_add_idle_full</a>       (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
  84                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  85                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
  86                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
  87 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-timeout" title="clutter_threads_add_timeout ()">clutter_threads_add_timeout</a>         (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> interval</code></em>,
  88                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  89                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  90 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-timeout-full" title="clutter_threads_add_timeout_full ()">clutter_threads_add_timeout_full</a>    (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
  91                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> interval</code></em>,
  92                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  93                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
  94                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
  95 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-frame-source" title="clutter_threads_add_frame_source ()">clutter_threads_add_frame_source</a>    (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> fps</code></em>,
  96                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  97                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);
  98 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-frame-source-full" title="clutter_threads_add_frame_source_full ()">clutter_threads_add_frame_source_full</a>
  99                                                         (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
 100                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> fps</code></em>,
 101                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
 102                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
 103                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
 104 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-repaint-func" title="clutter_threads_add_repaint_func ()">clutter_threads_add_repaint_func</a>    (<em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
 105                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
 106                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
 107 enum                <a class="link" href="clutter-General.html#ClutterRepaintFlags" title="enum ClutterRepaintFlags">ClutterRepaintFlags</a>;
 108 <a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               <a class="link" href="clutter-General.html#clutter-threads-add-repaint-func-full" title="clutter_threads_add_repaint_func_full ()">clutter_threads_add_repaint_func_full</a>
 109                                                         (<em class="parameter"><code><a class="link" href="clutter-General.html#ClutterRepaintFlags" title="enum ClutterRepaintFlags"><span class="type">ClutterRepaintFlags</span></a> flags</code></em>,
 110                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
 111                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
 112                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
 113 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-threads-remove-repaint-func" title="clutter_threads_remove_repaint_func ()">clutter_threads_remove_repaint_func</a> (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> handle_id</code></em>);
 114
 115 <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      <a class="link" href="clutter-General.html#clutter-get-keyboard-grab" title="clutter_get_keyboard_grab ()">clutter_get_keyboard_grab</a>           (<em class="parameter"><code><span class="type">void</span></code></em>);
 116 <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      <a class="link" href="clutter-General.html#clutter-get-pointer-grab" title="clutter_get_pointer_grab ()">clutter_get_pointer_grab</a>            (<em class="parameter"><code><span class="type">void</span></code></em>);
 117 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-grab-keyboard" title="clutter_grab_keyboard ()">clutter_grab_keyboard</a>               (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>);
 118 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-grab-pointer" title="clutter_grab_pointer ()">clutter_grab_pointer</a>                (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>);
 119 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-ungrab-keyboard" title="clutter_ungrab_keyboard ()">clutter_ungrab_keyboard</a>             (<em class="parameter"><code><span class="type">void</span></code></em>);
 120 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-ungrab-pointer" title="clutter_ungrab_pointer ()">clutter_ungrab_pointer</a>              (<em class="parameter"><code><span class="type">void</span></code></em>);
 121 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-grab-pointer-for-device" title="clutter_grab_pointer_for_device ()">clutter_grab_pointer_for_device</a>     (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>,
 122                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> id_</code></em>);
 123 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-ungrab-pointer-for-device" title="clutter_ungrab_pointer_for_device ()">clutter_ungrab_pointer_for_device</a>   (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> id_</code></em>);
 124
 125 <span class="returnvalue">void</span>                <a class="link" href="clutter-General.html#clutter-do-event" title="clutter_do_event ()">clutter_do_event</a>                    (<em class="parameter"><code><a class="link" href="clutter-Events.html#ClutterEvent" title="union ClutterEvent"><span class="type">ClutterEvent</span></a> *event</code></em>);
 126 </pre>
 127 </div>
 128 <div class="refsect1">
 129 <a name="clutter-General.description"></a><h2>Description</h2>
 130 <p>
 131 Functions to retrieve various global Clutter resources and other utility
 132 functions for mainloops, events and threads
 133 </p>
 134 <p>
 135 </p>
 136 <div class="refsect2">
 137 <a name="clutter-Threading-Model"></a><h3>Threading Model</h3>
 138 <p>Clutter is <span class="emphasis"><em>thread-aware</em></span>: all operations
 139   performed by Clutter are assumed to be under the big Clutter lock,
 140   which is created when the threading is initialized through
 141   <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>.</p>
 142 <div class="example">
 143 <a name="example-Thread-Init"></a><p class="title"><b>Example 15. Thread Initialization</b></p>
 144 <div class="example-contents">
 145 <p>The code below shows how to correctly initialize Clutter
 146     in a multi-threaded environment. These operations are mandatory for
 147     applications that wish to use threads with Clutter.</p>
 148 <pre class="programlisting">
 149 int
 150 main (int argc, char *argv[])
 151 {
 152   /* initialize Clutter */
 153   clutter_init (&amp;argc, &amp;argv);
 154
 155   /* program code */
 156
 157   /* acquire the main lock */
 158   clutter_threads_enter ();
 159
 160   /* start the main loop */
 161   clutter_main ();
 162
 163   /* release the main lock */
 164   clutter_threads_leave ();
 165
 166   /* clean up */
 167   return 0;
 168 }
 169     </pre>
 170 </div>
 171 </div>
 172 <br class="example-break"><p>This threading model has the caveat that it is only safe to call
 173   Clutter's API when the lock has been acquired — which happens
 174   between pairs of <a class="link" href="clutter-General.html#clutter-threads-enter" title="clutter_threads_enter ()"><code class="function">clutter_threads_enter()</code></a> and <a class="link" href="clutter-General.html#clutter-threads-leave" title="clutter_threads_leave ()"><code class="function">clutter_threads_leave()</code></a>
 175   calls.</p>
 176 <p>The only safe and portable way to use the Clutter API in a
 177   multi-threaded environment is to never access the API from a thread that
 178   did not call <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a> and <a class="link" href="clutter-General.html#clutter-main" title="clutter_main ()"><code class="function">clutter_main()</code></a>.</p>
 179 <p>The common pattern for using threads with Clutter is to use worker
 180   threads to perform blocking operations and then install idle or timeout
 181   sources with the result when the thread finished.</p>
 182 <p>Clutter provides thread-aware variants of <a href="../glib/glib-The-Main-Event-Loop.html#g-idle-add"><code class="function">g_idle_add()</code></a> and
 183   <a href="../glib/glib-The-Main-Event-Loop.html#g-timeout-add"><code class="function">g_timeout_add()</code></a> that acquire the Clutter lock before invoking the provided
 184   callback: <a class="link" href="clutter-General.html#clutter-threads-add-idle" title="clutter_threads_add_idle ()"><code class="function">clutter_threads_add_idle()</code></a> and
 185   <a class="link" href="clutter-General.html#clutter-threads-add-timeout" title="clutter_threads_add_timeout ()"><code class="function">clutter_threads_add_timeout()</code></a>.</p>
 186 <p>The example below shows how to use a worker thread to perform a
 187   blocking operation, and perform UI updates using the main loop.</p>
 188 <div class="example">
 189 <a name="worker-thread-example"></a><p class="title"><b>Example 16. A worker thread example</b></p>
 190 <div class="example-contents">
 191   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 192     <tbody>
 193       <tr>
 194         <td class="listing_lines" align="right"><pre>1</pre></td>
 195         <td class="listing_code"><pre class="programlisting"><span class="normal">FIXME</span><span class="symbol">:</span><span class="normal"> MISSING XINCLUDE CONTENT</span></pre></td>
 196       </tr>
 197     </tbody>
 198   </table>
 199 </div>
 200
 201 </div>
 202 <br class="example-break">
 203 </div>
 204 <p>
 205 </p>
 206 </div>
 207 <div class="refsect1">
 208 <a name="clutter-General.details"></a><h2>Details</h2>
 209 <div class="refsect2">
 210 <a name="CLUTTER-PRIORITY-REDRAW:CAPS"></a><h3>CLUTTER_PRIORITY_REDRAW</h3>
 211 <pre class="programlisting">#define CLUTTER_PRIORITY_REDRAW         (G_PRIORITY_HIGH_IDLE + 50)
 212 </pre>
 213 <p>
 214 Priority of the redraws. This is chosen to be lower than the GTK+
 215 redraw and resize priorities, because in application with both
 216 GTK+ and Clutter it's more likely that the Clutter part will be
 217 continually animating (and thus able to starve GTK+) than
 218 vice-versa.
 219 </p>
 220 <p class="since">Since 0.8</p>
 221 </div>
 222 <hr>
 223 <div class="refsect2">
 224 <a name="ClutterInitError"></a><h3>enum ClutterInitError</h3>
 225 <pre class="programlisting">typedef enum {
 226   CLUTTER_INIT_SUCCESS        =  1,
 227   CLUTTER_INIT_ERROR_UNKNOWN  =  0,
 228   CLUTTER_INIT_ERROR_THREADS  = -1,
 229   CLUTTER_INIT_ERROR_BACKEND  = -2,
 230   CLUTTER_INIT_ERROR_INTERNAL = -3
 231 } ClutterInitError;
 232 </pre>
 233 <p>
 234 Error conditions returned by <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a> and <a class="link" href="clutter-General.html#clutter-init-with-args" title="clutter_init_with_args ()"><code class="function">clutter_init_with_args()</code></a>.
 235 </p>
 236 <div class="variablelist"><table border="0">
 237 <col align="left" valign="top">
 238 <tbody>
 239 <tr>
 240 <td><p><a name="CLUTTER-INIT-SUCCESS:CAPS"></a><span class="term"><code class="literal">CLUTTER_INIT_SUCCESS</code></span></p></td>
 241 <td>Initialisation successful
 242 </td>
 243 </tr>
 244 <tr>
 245 <td><p><a name="CLUTTER-INIT-ERROR-UNKNOWN:CAPS"></a><span class="term"><code class="literal">CLUTTER_INIT_ERROR_UNKNOWN</code></span></p></td>
 246 <td>Unknown error
 247 </td>
 248 </tr>
 249 <tr>
 250 <td><p><a name="CLUTTER-INIT-ERROR-THREADS:CAPS"></a><span class="term"><code class="literal">CLUTTER_INIT_ERROR_THREADS</code></span></p></td>
 251 <td>Thread initialisation failed
 252 </td>
 253 </tr>
 254 <tr>
 255 <td><p><a name="CLUTTER-INIT-ERROR-BACKEND:CAPS"></a><span class="term"><code class="literal">CLUTTER_INIT_ERROR_BACKEND</code></span></p></td>
 256 <td>Backend initialisation failed
 257 </td>
 258 </tr>
 259 <tr>
 260 <td><p><a name="CLUTTER-INIT-ERROR-INTERNAL:CAPS"></a><span class="term"><code class="literal">CLUTTER_INIT_ERROR_INTERNAL</code></span></p></td>
 261 <td>Internal error
 262 </td>
 263 </tr>
 264 </tbody>
 265 </table></div>
 266 <p class="since">Since 0.2</p>
 267 </div>
 268 <hr>
 269 <div class="refsect2">
 270 <a name="clutter-init"></a><h3>clutter_init ()</h3>
 271 <pre class="programlisting"><a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="returnvalue">ClutterInitError</span></a>    clutter_init                        (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
 272                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>);</pre>
 273 <p>
 274 Initialises everything needed to operate with Clutter and parses some
 275 standard command line options; <em class="parameter"><code>argc</code></em> and <em class="parameter"><code>argv</code></em> are adjusted accordingly
 276 so your own code will never see those standard arguments.
 277 </p>
 278 <p>
 279 It is safe to call this function multiple times.
 280 </p>
 281 <p>
 282 </p>
 283 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 284 <h3 class="title">Note</h3>This function will not abort in case of errors during
 285 initialization; <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a> will print out the error message on
 286 stderr, and will return an error code. It is up to the application
 287 code to handle this case. If you need to display the error message
 288 yourself, you can use <a class="link" href="clutter-General.html#clutter-init-with-args" title="clutter_init_with_args ()"><code class="function">clutter_init_with_args()</code></a>, which takes a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
 289 pointer.</div>
 290 <p>
 291 </p>
 292 <p>
 293 If this function fails, and returns an error code, any subsequent
 294 Clutter API will have undefined behaviour - including segmentation
 295 faults and assertion failures. Make sure to handle the returned
 296 <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="type">ClutterInitError</span></a> enumeration value.
 297 </p>
 298 <div class="variablelist"><table border="0">
 299 <col align="left" valign="top">
 300 <tbody>
 301 <tr>
 302 <td><p><span class="term"><em class="parameter"><code>argc</code></em> :</span></p></td>
 303 <td>The number of arguments in <em class="parameter"><code>argv</code></em>. <span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span>
 304 </td>
 305 </tr>
 306 <tr>
 307 <td><p><span class="term"><em class="parameter"><code>argv</code></em> :</span></p></td>
 308 <td>A pointer to an array
 309 of arguments. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 310 </td>
 311 </tr>
 312 <tr>
 313 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 314 <td>a <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="type">ClutterInitError</span></a> value</td>
 315 </tr>
 316 </tbody>
 317 </table></div>
 318 </div>
 319 <hr>
 320 <div class="refsect2">
 321 <a name="clutter-init-with-args"></a><h3>clutter_init_with_args ()</h3>
 322 <pre class="programlisting"><a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="returnvalue">ClutterInitError</span></a>    clutter_init_with_args              (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
 323                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>,
 324                                                          <em class="parameter"><code>const <span class="type">char</span> *parameter_string</code></em>,
 325                                                          <em class="parameter"><code><a href="../glib/glib-Commandline-option-parser.html#GOptionEntry"><span class="type">GOptionEntry</span></a> *entries</code></em>,
 326                                                          <em class="parameter"><code>const <span class="type">char</span> *translation_domain</code></em>,
 327                                                          <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 328 <p>
 329 This function does the same work as <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>. Additionally,
 330 it allows you to add your own command line options, and it
 331 automatically generates nicely formatted <code class="option">--help</code>
 332 output. Note that your program will be terminated after writing
 333 out the help output. Also note that, in case of error, the
 334 error message will be placed inside <em class="parameter"><code>error</code></em> instead of being
 335 printed on the display.
 336 </p>
 337 <p>
 338 Just like <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>, if this function returns an error code then
 339 any subsequent call to any other Clutter API will result in undefined
 340 behaviour - including segmentation faults.
 341 </p>
 342 <div class="variablelist"><table border="0">
 343 <col align="left" valign="top">
 344 <tbody>
 345 <tr>
 346 <td><p><span class="term"><em class="parameter"><code>argc</code></em> :</span></p></td>
 347 <td>a pointer to the number of command line arguments. <span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span>
 348 </td>
 349 </tr>
 350 <tr>
 351 <td><p><span class="term"><em class="parameter"><code>argv</code></em> :</span></p></td>
 352 <td>a pointer to the array
 353 of command line arguments. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 354 </td>
 355 </tr>
 356 <tr>
 357 <td><p><span class="term"><em class="parameter"><code>parameter_string</code></em> :</span></p></td>
 358 <td>a string which is displayed in the
 359 first line of <code class="option">--help</code> output, after
 360 <code class="literal"><em class="replaceable"><code>programname</code></em> [OPTION...]</code>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 361 </td>
 362 </tr>
 363 <tr>
 364 <td><p><span class="term"><em class="parameter"><code>entries</code></em> :</span></p></td>
 365 <td>a <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a> terminated array of <a href="../glib/glib-Commandline-option-parser.html#GOptionEntry"><span class="type">GOptionEntry</span></a>s
 366 describing the options of your program. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 367 </td>
 368 </tr>
 369 <tr>
 370 <td><p><span class="term"><em class="parameter"><code>translation_domain</code></em> :</span></p></td>
 371 <td>a translation domain to use for
 372 translating the <code class="option">--help</code> output for the options in
 373 <em class="parameter"><code>entries</code></em> with <code class="function">gettext()</code>, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 374 </td>
 375 </tr>
 376 <tr>
 377 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 378 <td>a return location for a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 379 </td>
 380 </tr>
 381 <tr>
 382 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 383 <td>
 384 <a class="link" href="clutter-General.html#CLUTTER-INIT-SUCCESS:CAPS"><code class="literal">CLUTTER_INIT_SUCCESS</code></a> if Clutter has been successfully
 385 initialised, or other values or <a class="link" href="clutter-General.html#ClutterInitError" title="enum ClutterInitError"><span class="type">ClutterInitError</span></a> in case of
 386 error.</td>
 387 </tr>
 388 </tbody>
 389 </table></div>
 390 <p class="since">Since 0.2</p>
 391 </div>
 392 <hr>
 393 <div class="refsect2">
 394 <a name="clutter-get-option-group"></a><h3>clutter_get_option_group ()</h3>
 395 <pre class="programlisting"><a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="returnvalue">GOptionGroup</span></a> *      clutter_get_option_group            (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 396 <p>
 397 Returns a <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> for the command line arguments recognized
 398 by Clutter. You should add this group to your <a href="../glib/glib-Commandline-option-parser.html#GOptionContext"><span class="type">GOptionContext</span></a> with
 399 <a href="../glib/glib-Commandline-option-parser.html#g-option-context-add-group"><code class="function">g_option_context_add_group()</code></a>, if you are using <a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse"><code class="function">g_option_context_parse()</code></a>
 400 to parse your commandline arguments.
 401 </p>
 402 <p>
 403 Calling <a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse"><code class="function">g_option_context_parse()</code></a> with Clutter's <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> will result
 404 in Clutter's initialization. That is, the following code:
 405 </p>
 406 <p>
 407 </p>
 408 <div class="informalexample">
 409   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 410     <tbody>
 411       <tr>
 412         <td class="listing_lines" align="right"><pre>1
 413 2</pre></td>
 414         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="../glib/glib-Commandline-option-parser.html#g-option-context-set-main-group">g_option_context_set_main_group</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="clutter-General.html#clutter-get-option-group">clutter_get_option_group</a></span><span class="normal"> </span><span class="symbol">());</span>
 415 <span class="normal">res </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse">g_option_context_parse</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span></pre></td>
 416       </tr>
 417     </tbody>
 418   </table>
 419 </div>
 420
 421 <p>
 422 </p>
 423 <p>
 424 is functionally equivalent to:
 425 </p>
 426 <p>
 427 </p>
 428 <div class="informalexample">
 429   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 430     <tbody>
 431       <tr>
 432         <td class="listing_lines" align="right"><pre>1</pre></td>
 433         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="clutter-General.html#clutter-init">clutter_init</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">argv</span><span class="symbol">);</span></pre></td>
 434       </tr>
 435     </tbody>
 436   </table>
 437 </div>
 438
 439 <p>
 440 </p>
 441 <p>
 442 After <a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse"><code class="function">g_option_context_parse()</code></a> on a <a href="../glib/glib-Commandline-option-parser.html#GOptionContext"><span class="type">GOptionContext</span></a> containing the
 443 Clutter <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> has returned <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, Clutter is guaranteed to be
 444 initialized.
 445 </p>
 446 <div class="variablelist"><table border="0">
 447 <col align="left" valign="top">
 448 <tbody><tr>
 449 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 450 <td>a <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> for the commandline arguments
 451 recognized by Clutter. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 452 </td>
 453 </tr></tbody>
 454 </table></div>
 455 <p class="since">Since 0.2</p>
 456 </div>
 457 <hr>
 458 <div class="refsect2">
 459 <a name="clutter-get-option-group-without-init"></a><h3>clutter_get_option_group_without_init ()</h3>
 460 <pre class="programlisting"><a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="returnvalue">GOptionGroup</span></a> *      clutter_get_option_group_without_init
 461                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 462 <p>
 463 Returns a <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> for the command line arguments recognized
 464 by Clutter. You should add this group to your <a href="../glib/glib-Commandline-option-parser.html#GOptionContext"><span class="type">GOptionContext</span></a> with
 465 <a href="../glib/glib-Commandline-option-parser.html#g-option-context-add-group"><code class="function">g_option_context_add_group()</code></a>, if you are using <a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse"><code class="function">g_option_context_parse()</code></a>
 466 to parse your commandline arguments.
 467 </p>
 468 <p>
 469 Unlike <a class="link" href="clutter-General.html#clutter-get-option-group" title="clutter_get_option_group ()"><code class="function">clutter_get_option_group()</code></a>, calling <a href="../glib/glib-Commandline-option-parser.html#g-option-context-parse"><code class="function">g_option_context_parse()</code></a> with
 470 the <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> returned by this function requires a subsequent explicit
 471 call to <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>; use this function when needing to set foreign
 472 display connection with <a class="link" href="clutter-X11-Specific-Support.html#clutter-x11-set-display" title="clutter_x11_set_display ()"><code class="function">clutter_x11_set_display()</code></a>, or with
 473 <code class="function"><a href="../clutter-gtk-1.0/clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init"><code class="function">gtk_clutter_init()</code></a></code>.
 474 </p>
 475 <div class="variablelist"><table border="0">
 476 <col align="left" valign="top">
 477 <tbody><tr>
 478 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 479 <td>a <a href="../glib/glib-Commandline-option-parser.html#GOptionGroup"><span class="type">GOptionGroup</span></a> for the commandline arguments
 480 recognized by Clutter. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 481 </td>
 482 </tr></tbody>
 483 </table></div>
 484 <p class="since">Since 0.8.2</p>
 485 </div>
 486 <hr>
 487 <div class="refsect2">
 488 <a name="clutter-main"></a><h3>clutter_main ()</h3>
 489 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_main                        (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 490 <p>
 491 Starts the Clutter mainloop.
 492 </p>
 493 </div>
 494 <hr>
 495 <div class="refsect2">
 496 <a name="clutter-main-quit"></a><h3>clutter_main_quit ()</h3>
 497 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_main_quit                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 498 <p>
 499 Terminates the Clutter mainloop.
 500 </p>
 501 </div>
 502 <hr>
 503 <div class="refsect2">
 504 <a name="clutter-main-level"></a><h3>clutter_main_level ()</h3>
 505 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a>                clutter_main_level                  (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 506 <p>
 507 Retrieves the depth of the Clutter mainloop.
 508 </p>
 509 <div class="variablelist"><table border="0">
 510 <col align="left" valign="top">
 511 <tbody><tr>
 512 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 513 <td>The level of the mainloop.</td>
 514 </tr></tbody>
 515 </table></div>
 516 </div>
 517 <hr>
 518 <div class="refsect2">
 519 <a name="clutter-get-debug-enabled"></a><h3>clutter_get_debug_enabled ()</h3>
 520 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            clutter_get_debug_enabled           (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 521 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 522 <h3 class="title">Warning</h3>
 523 <p><code class="literal">clutter_get_debug_enabled</code> has been deprecated since version 1.10 and should not be used in newly-written code. This function does not do anything.</p>
 524 </div>
 525 <p>
 526 Check if Clutter has debugging enabled.
 527 </p>
 528 <div class="variablelist"><table border="0">
 529 <col align="left" valign="top">
 530 <tbody><tr>
 531 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 532 <td><a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></td>
 533 </tr></tbody>
 534 </table></div>
 535 </div>
 536 <hr>
 537 <div class="refsect2">
 538 <a name="clutter-get-show-fps"></a><h3>clutter_get_show_fps ()</h3>
 539 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            clutter_get_show_fps                (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 540 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 541 <h3 class="title">Warning</h3>
 542 <p><code class="literal">clutter_get_show_fps</code> has been deprecated since version 1.10 and should not be used in newly-written code. This function does not do anything. Use the environment
 543   variable or the configuration file to determine whether Clutter should
 544   print out the FPS counter on the console.</p>
 545 </div>
 546 <p>
 547 Returns whether Clutter should print out the frames per second on the
 548 console. You can enable this setting either using the
 549 <code class="literal">CLUTTER_SHOW_FPS</code> environment variable or passing
 550 the <code class="literal">--clutter-show-fps</code> command line argument. *
 551 </p>
 552 <div class="variablelist"><table border="0">
 553 <col align="left" valign="top">
 554 <tbody><tr>
 555 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 556 <td>
 557 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if Clutter should show the FPS.</td>
 558 </tr></tbody>
 559 </table></div>
 560 <p class="since">Since 0.4</p>
 561 </div>
 562 <hr>
 563 <div class="refsect2">
 564 <a name="clutter-get-timestamp"></a><h3>clutter_get_timestamp ()</h3>
 565 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>              clutter_get_timestamp               (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 566 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 567 <h3 class="title">Warning</h3>
 568 <p><code class="literal">clutter_get_timestamp</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a href="../glib/glib-Timers.html#GTimer"><span class="type">GTimer</span></a> or <a href="../glib/glib-Date-and-Time-Functions.html#g-get-monotonic-time"><code class="function">g_get_monotonic_time()</code></a> for a proper
 569   timing source</p>
 570 </div>
 571 <p>
 572 Returns the approximate number of microseconds passed since Clutter was
 573 intialised.
 574 </p>
 575 <p>
 576 This function shdould not be used by application code.
 577 </p>
 578 <p>
 579 The output of this function depends on whether Clutter was configured to
 580 enable its debugging code paths, so it's less useful than intended.
 581 </p>
 582 <p>
 583 Since Clutter 1.10, this function is an alias to <a href="../glib/glib-Date-and-Time-Functions.html#g-get-monotonic-time"><code class="function">g_get_monotonic_time()</code></a>
 584 if Clutter was configured to enable the debugging code paths.
 585 </p>
 586 <div class="variablelist"><table border="0">
 587 <col align="left" valign="top">
 588 <tbody><tr>
 589 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 590 <td>Number of microseconds since <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a> was called, or
 591 zero if Clutter was not configured with debugging code paths.</td>
 592 </tr></tbody>
 593 </table></div>
 594 </div>
 595 <hr>
 596 <div class="refsect2">
 597 <a name="clutter-get-actor-by-gid"></a><h3>clutter_get_actor_by_gid ()</h3>
 598 <pre class="programlisting"><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      clutter_get_actor_by_gid            (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint32"><span class="type">guint32</span></a> id_</code></em>);</pre>
 599 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 600 <h3 class="title">Warning</h3>
 601 <p><code class="literal">clutter_get_actor_by_gid</code> has been deprecated since version 1.8 and should not be used in newly-written code. The id is not used any longer.</p>
 602 </div>
 603 <p>
 604 Retrieves the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> with <em class="parameter"><code>id_</code></em>.
 605 </p>
 606 <div class="variablelist"><table border="0">
 607 <col align="left" valign="top">
 608 <tbody>
 609 <tr>
 610 <td><p><span class="term"><em class="parameter"><code>id_</code></em> :</span></p></td>
 611 <td>a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> unique id.</td>
 612 </tr>
 613 <tr>
 614 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 615 <td>the actor with the passed id or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>.
 616 The returned actor does not have its reference count increased. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 617 </td>
 618 </tr>
 619 </tbody>
 620 </table></div>
 621 <p class="since">Since 0.6</p>
 622 </div>
 623 <hr>
 624 <div class="refsect2">
 625 <a name="clutter-set-default-frame-rate"></a><h3>clutter_set_default_frame_rate ()</h3>
 626 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_set_default_frame_rate      (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> frames_per_sec</code></em>);</pre>
 627 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 628 <h3 class="title">Warning</h3>
 629 <p><code class="literal">clutter_set_default_frame_rate</code> has been deprecated since version 1.10 and should not be used in newly-written code. This function does not do anything any more.</p>
 630 </div>
 631 <p>
 632 Sets the default frame rate. This frame rate will be used to limit
 633 the number of frames drawn if Clutter is not able to synchronize
 634 with the vertical refresh rate of the display. When synchronization
 635 is possible, this value is ignored.
 636 </p>
 637 <div class="variablelist"><table border="0">
 638 <col align="left" valign="top">
 639 <tbody><tr>
 640 <td><p><span class="term"><em class="parameter"><code>frames_per_sec</code></em> :</span></p></td>
 641 <td>the new default frame rate</td>
 642 </tr></tbody>
 643 </table></div>
 644 <p class="since">Since 0.6</p>
 645 </div>
 646 <hr>
 647 <div class="refsect2">
 648 <a name="clutter-get-default-frame-rate"></a><h3>clutter_get_default_frame_rate ()</h3>
 649 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_get_default_frame_rate      (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 650 <p>
 651 Retrieves the default frame rate. See <a class="link" href="clutter-General.html#clutter-set-default-frame-rate" title="clutter_set_default_frame_rate ()"><code class="function">clutter_set_default_frame_rate()</code></a>.
 652 </p>
 653 <div class="variablelist"><table border="0">
 654 <col align="left" valign="top">
 655 <tbody><tr>
 656 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 657 <td>the default frame rate</td>
 658 </tr></tbody>
 659 </table></div>
 660 <p class="since">Since 0.6</p>
 661 </div>
 662 <hr>
 663 <div class="refsect2">
 664 <a name="clutter-set-motion-events-enabled"></a><h3>clutter_set_motion_events_enabled ()</h3>
 665 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_set_motion_events_enabled   (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> enable</code></em>);</pre>
 666 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 667 <h3 class="title">Warning</h3>
 668 <p><code class="literal">clutter_set_motion_events_enabled</code> has been deprecated since version 1.8 and should not be used in newly-written code. Use <a class="link" href="ClutterStage.html#clutter-stage-set-motion-events-enabled" title="clutter_stage_set_motion_events_enabled ()"><code class="function">clutter_stage_set_motion_events_enabled()</code></a> instead.</p>
 669 </div>
 670 <p>
 671 Sets whether per-actor motion events should be enabled or not on
 672 all <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>s managed by Clutter.
 673 </p>
 674 <p>
 675 If <em class="parameter"><code>enable</code></em> is <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> the following events will not work:
 676 </p>
 677 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 678 <li class="listitem"><p>ClutterActor::motion-event, unless on the
 679     <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a></p></li>
 680 <li class="listitem"><p>ClutterActor::enter-event</p></li>
 681 <li class="listitem"><p>ClutterActor::leave-event</p></li>
 682 </ul></div>
 683 <p>
 684 </p>
 685 <div class="variablelist"><table border="0">
 686 <col align="left" valign="top">
 687 <tbody><tr>
 688 <td><p><span class="term"><em class="parameter"><code>enable</code></em> :</span></p></td>
 689 <td>
 690 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> to enable per-actor motion events</td>
 691 </tr></tbody>
 692 </table></div>
 693 <p class="since">Since 0.6</p>
 694 </div>
 695 <hr>
 696 <div class="refsect2">
 697 <a name="clutter-get-motion-events-enabled"></a><h3>clutter_get_motion_events_enabled ()</h3>
 698 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            clutter_get_motion_events_enabled   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 699 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 700 <h3 class="title">Warning</h3>
 701 <p><code class="literal">clutter_get_motion_events_enabled</code> has been deprecated since version 1.8 and should not be used in newly-written code. Use <a class="link" href="ClutterStage.html#clutter-stage-get-motion-events-enabled" title="clutter_stage_get_motion_events_enabled ()"><code class="function">clutter_stage_get_motion_events_enabled()</code></a> instead.</p>
 702 </div>
 703 <p>
 704 Gets whether the per-actor motion events are enabled.
 705 </p>
 706 <div class="variablelist"><table border="0">
 707 <col align="left" valign="top">
 708 <tbody><tr>
 709 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 710 <td>
 711 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the motion events are enabled</td>
 712 </tr></tbody>
 713 </table></div>
 714 <p class="since">Since 0.6</p>
 715 </div>
 716 <hr>
 717 <div class="refsect2">
 718 <a name="clutter-clear-glyph-cache"></a><h3>clutter_clear_glyph_cache ()</h3>
 719 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_clear_glyph_cache           (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 720 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 721 <h3 class="title">Warning</h3>
 722 <p><code class="literal">clutter_clear_glyph_cache</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a class="link" href="clutter-General.html#clutter-get-font-map" title="clutter_get_font_map ()"><code class="function">clutter_get_font_map()</code></a> and
 723   <code class="function">cogl_pango_font_map_clear_glyph_cache()</code> instead.</p>
 724 </div>
 725 <p>
 726 Clears the internal cache of glyphs used by the Pango
 727 renderer. This will free up some memory and GL texture
 728 resources. The cache will be automatically refilled as more text is
 729 drawn.
 730 </p>
 731 <p class="since">Since 0.8</p>
 732 </div>
 733 <hr>
 734 <div class="refsect2">
 735 <a name="ClutterFontFlags"></a><h3>enum ClutterFontFlags</h3>
 736 <pre class="programlisting">typedef enum {
 737  /*&lt; prefix=CLUTTER_FONT &gt;*/
 738   CLUTTER_FONT_MIPMAPPING = (1 &lt;&lt; 0),
 739   CLUTTER_FONT_HINTING    = (1 &lt;&lt; 1)
 740 } ClutterFontFlags;
 741 </pre>
 742 <p>
 743 Runtime flags to change the font quality. To be used with
 744 <a class="link" href="clutter-General.html#clutter-set-font-flags" title="clutter_set_font_flags ()"><code class="function">clutter_set_font_flags()</code></a>.
 745 </p>
 746 <div class="variablelist"><table border="0">
 747 <col align="left" valign="top">
 748 <tbody>
 749 <tr>
 750 <td><p><a name="CLUTTER-FONT-MIPMAPPING:CAPS"></a><span class="term"><code class="literal">CLUTTER_FONT_MIPMAPPING</code></span></p></td>
 751 <td>Set to use mipmaps for the glyph cache textures.
 752 </td>
 753 </tr>
 754 <tr>
 755 <td><p><a name="CLUTTER-FONT-HINTING:CAPS"></a><span class="term"><code class="literal">CLUTTER_FONT_HINTING</code></span></p></td>
 756 <td>Set to enable hinting on the glyphs.
 757 </td>
 758 </tr>
 759 </tbody>
 760 </table></div>
 761 <p class="since">Since 1.0</p>
 762 </div>
 763 <hr>
 764 <div class="refsect2">
 765 <a name="clutter-set-font-flags"></a><h3>clutter_set_font_flags ()</h3>
 766 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_set_font_flags              (<em class="parameter"><code><a class="link" href="clutter-General.html#ClutterFontFlags" title="enum ClutterFontFlags"><span class="type">ClutterFontFlags</span></a> flags</code></em>);</pre>
 767 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 768 <h3 class="title">Warning</h3>
 769 <p><code class="literal">clutter_set_font_flags</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a class="link" href="ClutterBackend.html#clutter-backend-set-font-options" title="clutter_backend_set_font_options ()"><code class="function">clutter_backend_set_font_options()</code></a> and the
 770   <span class="type">cairo_font_option_t</span> API.</p>
 771 </div>
 772 <p>
 773 Sets the font quality options for subsequent text rendering
 774 operations.
 775 </p>
 776 <p>
 777 Using mipmapped textures will improve the quality for scaled down
 778 text but will use more texture memory.
 779 </p>
 780 <p>
 781 Enabling hinting improves text quality for static text but may
 782 introduce some artifacts if the text is animated.
 783 </p>
 784 <div class="variablelist"><table border="0">
 785 <col align="left" valign="top">
 786 <tbody><tr>
 787 <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td>
 788 <td>The new flags</td>
 789 </tr></tbody>
 790 </table></div>
 791 <p class="since">Since 1.0</p>
 792 </div>
 793 <hr>
 794 <div class="refsect2">
 795 <a name="clutter-get-font-flags"></a><h3>clutter_get_font_flags ()</h3>
 796 <pre class="programlisting"><a class="link" href="clutter-General.html#ClutterFontFlags" title="enum ClutterFontFlags"><span class="returnvalue">ClutterFontFlags</span></a>    clutter_get_font_flags              (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 797 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 798 <h3 class="title">Warning</h3>
 799 <p><code class="literal">clutter_get_font_flags</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a class="link" href="ClutterBackend.html#clutter-backend-get-font-options" title="clutter_backend_get_font_options ()"><code class="function">clutter_backend_get_font_options()</code></a> and the
 800   <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/cairo/cairo-cairo-font-options-t.html#cairo-font-options-t"><span class="type">cairo_font_options_t</span></a> API.</p>
 801 </div>
 802 <p>
 803 Gets the current font flags for rendering text. See
 804 <a class="link" href="clutter-General.html#clutter-set-font-flags" title="clutter_set_font_flags ()"><code class="function">clutter_set_font_flags()</code></a>.
 805 </p>
 806 <div class="variablelist"><table border="0">
 807 <col align="left" valign="top">
 808 <tbody><tr>
 809 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 810 <td>The font flags</td>
 811 </tr></tbody>
 812 </table></div>
 813 <p class="since">Since 1.0</p>
 814 </div>
 815 <hr>
 816 <div class="refsect2">
 817 <a name="clutter-get-font-map"></a><h3>clutter_get_font_map ()</h3>
 818 <pre class="programlisting"><a href="../pango/pango-Fonts.html#PangoFontMap"><span class="returnvalue">PangoFontMap</span></a> *      clutter_get_font_map                (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 819 <p>
 820 Retrieves the <a href="../pango/pango-Fonts.html#PangoFontMap"><span class="type">PangoFontMap</span></a> instance used by Clutter.
 821 You can use the global font map object with the COGL
 822 Pango API.
 823 </p>
 824 <div class="variablelist"><table border="0">
 825 <col align="left" valign="top">
 826 <tbody><tr>
 827 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 828 <td>the <a href="../pango/pango-Fonts.html#PangoFontMap"><span class="type">PangoFontMap</span></a> instance. The returned
 829 value is owned by Clutter and it should never be unreferenced. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 830 </td>
 831 </tr></tbody>
 832 </table></div>
 833 <p class="since">Since 1.0</p>
 834 </div>
 835 <hr>
 836 <div class="refsect2">
 837 <a name="ClutterTextDirection"></a><h3>enum ClutterTextDirection</h3>
 838 <pre class="programlisting">typedef enum {
 839   CLUTTER_TEXT_DIRECTION_DEFAULT,
 840   CLUTTER_TEXT_DIRECTION_LTR,
 841   CLUTTER_TEXT_DIRECTION_RTL
 842 } ClutterTextDirection;
 843 </pre>
 844 <p>
 845 The text direction to be used by <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s
 846 </p>
 847 <div class="variablelist"><table border="0">
 848 <col align="left" valign="top">
 849 <tbody>
 850 <tr>
 851 <td><p><a name="CLUTTER-TEXT-DIRECTION-DEFAULT:CAPS"></a><span class="term"><code class="literal">CLUTTER_TEXT_DIRECTION_DEFAULT</code></span></p></td>
 852 <td>Use the default setting, as returned
 853   by <a class="link" href="clutter-General.html#clutter-get-default-text-direction" title="clutter_get_default_text_direction ()"><code class="function">clutter_get_default_text_direction()</code></a>
 854 </td>
 855 </tr>
 856 <tr>
 857 <td><p><a name="CLUTTER-TEXT-DIRECTION-LTR:CAPS"></a><span class="term"><code class="literal">CLUTTER_TEXT_DIRECTION_LTR</code></span></p></td>
 858 <td>Use left-to-right text direction
 859 </td>
 860 </tr>
 861 <tr>
 862 <td><p><a name="CLUTTER-TEXT-DIRECTION-RTL:CAPS"></a><span class="term"><code class="literal">CLUTTER_TEXT_DIRECTION_RTL</code></span></p></td>
 863 <td>Use right-to-left text direction
 864 </td>
 865 </tr>
 866 </tbody>
 867 </table></div>
 868 <p class="since">Since 1.2</p>
 869 </div>
 870 <hr>
 871 <div class="refsect2">
 872 <a name="clutter-get-default-text-direction"></a><h3>clutter_get_default_text_direction ()</h3>
 873 <pre class="programlisting"><a class="link" href="clutter-General.html#ClutterTextDirection" title="enum ClutterTextDirection"><span class="returnvalue">ClutterTextDirection</span></a> clutter_get_default_text_direction (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 874 <p>
 875 Retrieves the default direction for the text. The text direction is
 876 determined by the locale and/or by the <code class="varname">CLUTTER_TEXT_DIRECTION</code>
 877 environment variable.
 878 </p>
 879 <p>
 880 The default text direction can be overridden on a per-actor basis by using
 881 <a class="link" href="ClutterActor.html#clutter-actor-set-text-direction" title="clutter_actor_set_text_direction ()"><code class="function">clutter_actor_set_text_direction()</code></a>.
 882 </p>
 883 <div class="variablelist"><table border="0">
 884 <col align="left" valign="top">
 885 <tbody><tr>
 886 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 887 <td>the default text direction</td>
 888 </tr></tbody>
 889 </table></div>
 890 <p class="since">Since 1.2</p>
 891 </div>
 892 <hr>
 893 <div class="refsect2">
 894 <a name="clutter-get-accessibility-enabled"></a><h3>clutter_get_accessibility_enabled ()</h3>
 895 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            clutter_get_accessibility_enabled   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 896 <p>
 897 Returns whether Clutter has accessibility support enabled.  As
 898 least, a value of TRUE means that there are a proper AtkUtil
 899 implementation available
 900 </p>
 901 <div class="variablelist"><table border="0">
 902 <col align="left" valign="top">
 903 <tbody><tr>
 904 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 905 <td>
 906 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if Clutter has accessibility support enabled</td>
 907 </tr></tbody>
 908 </table></div>
 909 <p class="since">Since 1.4</p>
 910 </div>
 911 <hr>
 912 <div class="refsect2">
 913 <a name="clutter-threads-set-lock-functions"></a><h3>clutter_threads_set_lock_functions ()</h3>
 914 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_threads_set_lock_functions  (<em class="parameter"><code><a href="../gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> enter_fn</code></em>,
 915                                                          <em class="parameter"><code><a href="../gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> leave_fn</code></em>);</pre>
 916 <p>
 917 Allows the application to replace the standard method that
 918 Clutter uses to protect its data structures. Normally, Clutter
 919 creates a single <a href="../glib/glib-Threads.html#GMutex"><span class="type">GMutex</span></a> that is locked by <a class="link" href="clutter-General.html#clutter-threads-enter" title="clutter_threads_enter ()"><code class="function">clutter_threads_enter()</code></a>,
 920 and released by <a class="link" href="clutter-General.html#clutter-threads-leave" title="clutter_threads_leave ()"><code class="function">clutter_threads_leave()</code></a>; using this function an
 921 application provides, instead, a function <em class="parameter"><code>enter_fn</code></em> that is
 922 called by <a class="link" href="clutter-General.html#clutter-threads-enter" title="clutter_threads_enter ()"><code class="function">clutter_threads_enter()</code></a> and a function <em class="parameter"><code>leave_fn</code></em> that is
 923 called by <a class="link" href="clutter-General.html#clutter-threads-leave" title="clutter_threads_leave ()"><code class="function">clutter_threads_leave()</code></a>.
 924 </p>
 925 <p>
 926 The functions must provide at least same locking functionality
 927 as the default implementation, but can also do extra application
 928 specific processing.
 929 </p>
 930 <p>
 931 As an example, consider an application that has its own recursive
 932 lock that when held, holds the Clutter lock as well. When Clutter
 933 unlocks the Clutter lock when entering a recursive main loop, the
 934 application must temporarily release its lock as well.
 935 </p>
 936 <p>
 937 Most threaded Clutter apps won't need to use this method.
 938 </p>
 939 <p>
 940 This method must be called before <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>, and cannot
 941 be called multiple times.
 942 </p>
 943 <div class="variablelist"><table border="0">
 944 <col align="left" valign="top">
 945 <tbody>
 946 <tr>
 947 <td><p><span class="term"><em class="parameter"><code>enter_fn</code></em> :</span></p></td>
 948 <td>function called when aquiring the Clutter main lock</td>
 949 </tr>
 950 <tr>
 951 <td><p><span class="term"><em class="parameter"><code>leave_fn</code></em> :</span></p></td>
 952 <td>function called when releasing the Clutter main lock</td>
 953 </tr>
 954 </tbody>
 955 </table></div>
 956 <p class="since">Since 0.4</p>
 957 </div>
 958 <hr>
 959 <div class="refsect2">
 960 <a name="clutter-threads-init"></a><h3>clutter_threads_init ()</h3>
 961 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_threads_init                (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 962 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 963 <h3 class="title">Warning</h3>
 964 <p><code class="literal">clutter_threads_init</code> has been deprecated since version 1.10 and should not be used in newly-written code. This function does not do anything. Threading support
 965   is initialized when Clutter is initialized.</p>
 966 </div>
 967 <p>
 968 Initialises the Clutter threading mechanism, so that Clutter API can be
 969 called by multiple threads, using <a class="link" href="clutter-General.html#clutter-threads-enter" title="clutter_threads_enter ()"><code class="function">clutter_threads_enter()</code></a> and
 970 <a class="link" href="clutter-General.html#clutter-threads-leave" title="clutter_threads_leave ()"><code class="function">clutter_threads_leave()</code></a> to mark the critical sections.
 971 </p>
 972 <p>
 973 You must call <a href="../glib/glib-Deprecated-Thread-APIs.html#g-thread-init"><code class="function">g_thread_init()</code></a> before this function.
 974 </p>
 975 <p>
 976 This function must be called before <a class="link" href="clutter-General.html#clutter-init" title="clutter_init ()"><code class="function">clutter_init()</code></a>.
 977 </p>
 978 <p>
 979 It is safe to call this function multiple times.
 980 </p>
 981 <p class="since">Since 0.4</p>
 982 </div>
 983 <hr>
 984 <div class="refsect2">
 985 <a name="clutter-threads-enter"></a><h3>clutter_threads_enter ()</h3>
 986 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_threads_enter               (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 987 <p>
 988 Locks the Clutter thread lock.
 989 </p>
 990 <p class="since">Since 0.4</p>
 991 </div>
 992 <hr>
 993 <div class="refsect2">
 994 <a name="clutter-threads-leave"></a><h3>clutter_threads_leave ()</h3>
 995 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_threads_leave               (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 996 <p>
 997 Unlocks the Clutter thread lock.
 998 </p>
 999 <p class="since">Since 0.4</p>
1000 </div>
1001 <hr>
1002 <div class="refsect2">
1003 <a name="clutter-threads-add-idle"></a><h3>clutter_threads_add_idle ()</h3>
1004 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_idle            (<em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1005                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
1006 <p>
1007 Simple wrapper around <a class="link" href="clutter-General.html#clutter-threads-add-idle-full" title="clutter_threads_add_idle_full ()"><code class="function">clutter_threads_add_idle_full()</code></a> using the
1008 default priority.
1009 </p>
1010 <div class="variablelist"><table border="0">
1011 <col align="left" valign="top">
1012 <tbody>
1013 <tr>
1014 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1015 <td>function to call</td>
1016 </tr>
1017 <tr>
1018 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1019 <td>data to pass to the function</td>
1020 </tr>
1021 <tr>
1022 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1023 <td>the ID (greater than 0) of the event source.</td>
1024 </tr>
1025 </tbody>
1026 </table></div>
1027 <p class="since">Since 0.4</p>
1028 </div>
1029 <hr>
1030 <div class="refsect2">
1031 <a name="clutter-threads-add-idle-full"></a><h3>clutter_threads_add_idle_full ()</h3>
1032 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_idle_full       (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
1033                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1034                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
1035                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
1036 <p>
1037 Adds a function to be called whenever there are no higher priority
1038 events pending. If the function returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> it is automatically
1039 removed from the list of event sources and will not be called again.
1040 </p>
1041 <p>
1042 This function can be considered a thread-safe variant of <a href="../glib/glib-The-Main-Event-Loop.html#g-idle-add-full"><code class="function">g_idle_add_full()</code></a>:
1043 it will call <em class="parameter"><code>function</code></em> while holding the Clutter lock. It is logically
1044 equivalent to the following implementation:
1045 </p>
1046 <p>
1047 </p>
1048 <div class="informalexample">
1049   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1050     <tbody>
1051       <tr>
1052         <td class="listing_lines" align="right"><pre>1
1053 2
1054 3
1055 4
1056 5
1057 6
1058 7
1059 8
1060 9
1061 10
1062 11
1063 12
1064 13
1065 14
1066 15
1067 16
1068 17
1069 18
1070 19
1071 20
1072 21
1073 22
1074 23
1075 24
1076 25
1077 26
1078 27
1079 28
1080 29
1081 30
1082 31
1083 32
1084 33</pre></td>
1085         <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span>
1086 <span class="function">idle_safe_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span>
1087 <span class="cbracket">{</span>
1088 <span class="normal">   </span><span class="usertype">SafeClosure</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">closure </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
1089 <span class="normal">   </span><span class="usertype">gboolean</span><span class="normal"> res </span><span class="symbol">=</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
1090
1091 <span class="normal">   </span><span class="comment">/* mark the critical section */</span>
1092
1093 <span class="normal">   </span><span class="function"><a href="clutter-General.html#clutter-threads-enter">clutter_threads_enter</a></span><span class="symbol">();</span>
1094
1095 <span class="normal">   </span><span class="comment">/* the callback does not need to acquire the Clutter</span>
1096 <span class="comment">    * lock itself, as it is held by the this proxy handler</span>
1097 <span class="comment">    */</span>
1098 <span class="normal">   res </span><span class="symbol">=</span><span class="normal"> closure</span><span class="symbol">-&gt;</span><span class="function">callback</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">closure</span><span class="symbol">-&gt;</span><span class="normal">data</span><span class="symbol">);</span>
1099
1100 <span class="normal">   </span><span class="function"><a href="clutter-General.html#clutter-threads-leave">clutter_threads_leave</a></span><span class="symbol">();</span>
1101
1102 <span class="normal">   </span><span class="keyword">return</span><span class="normal"> res</span><span class="symbol">;</span>
1103 <span class="cbracket">}</span>
1104 <span class="keyword">static</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gulong">gulong</a></span>
1105 <span class="function">add_safe_idle</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GSourceFunc</span><span class="normal"> callback</span><span class="symbol">,</span>
1106 <span class="normal">               </span><span class="usertype">gpointer</span><span class="normal">    data</span><span class="symbol">)</span>
1107 <span class="cbracket">{</span>
1108 <span class="normal">  </span><span class="usertype">SafeClosure</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">closure </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib/glib-Memory-Allocation.html#g-new0">g_new0</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">SafeClosure</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
1109
1110 <span class="normal">  closure</span><span class="symbol">-&gt;</span><span class="normal">callback </span><span class="symbol">=</span><span class="normal"> callback</span><span class="symbol">;</span>
1111 <span class="normal">  closure</span><span class="symbol">-&gt;</span><span class="normal">data </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
1112
1113 <span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="../glib/glib-The-Main-Event-Loop.html#g-idle-add-full">g_idle_add_full</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE:CAPS">G_PRIORITY_DEFAULT_IDLE</a></span><span class="symbol">,</span>
1114 <span class="normal">                          idle_safe_callback</span><span class="symbol">,</span>
1115 <span class="normal">                          closure</span><span class="symbol">,</span>
1116 <span class="normal">                          <a href="../glib/glib-Memory-Allocation.html#g-free">g_free</a></span><span class="symbol">)</span>
1117 <span class="cbracket">}</span></pre></td>
1118       </tr>
1119     </tbody>
1120   </table>
1121 </div>
1122
1123 <p>
1124 </p>
1125 <p>
1126 This function should be used by threaded applications to make sure
1127 that <em class="parameter"><code>func</code></em> is emitted under the Clutter threads lock and invoked
1128 from the same thread that started the Clutter main loop. For instance,
1129 it can be used to update the UI using the results from a worker
1130 thread:
1131 </p>
1132 <p>
1133 </p>
1134 <div class="informalexample">
1135   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1136     <tbody>
1137       <tr>
1138         <td class="listing_lines" align="right"><pre>1
1139 2
1140 3
1141 4
1142 5
1143 6
1144 7
1145 8
1146 9
1147 10
1148 11
1149 12
1150 13
1151 14
1152 15
1153 16
1154 17
1155 18
1156 19
1157 20
1158 21
1159 22
1160 23
1161 24
1162 25
1163 26
1164 27
1165 28</pre></td>
1166         <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span>
1167 <span class="function">update_ui</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span>
1168 <span class="cbracket">{</span>
1169 <span class="normal">  </span><span class="usertype">SomeClosure</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">closure </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
1170
1171 <span class="normal">  </span><span class="comment">/* it is safe to call Clutter API from this function because</span>
1172 <span class="comment">   * it is invoked from the same thread that started the main</span>
1173 <span class="comment">   * loop and under the Clutter thread lock</span>
1174 <span class="comment">   */</span>
1175 <span class="normal">  </span><span class="function">clutter_label_set_text</span><span class="normal"> </span><span class="symbol">(</span><span class="function">CLUTTER_LABEL</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">closure</span><span class="symbol">-&gt;</span><span class="normal">label</span><span class="symbol">),</span>
1176 <span class="normal">                          closure</span><span class="symbol">-&gt;</span><span class="normal">text</span><span class="symbol">);</span>
1177
1178 <span class="normal">  </span><span class="function"><a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">closure</span><span class="symbol">-&gt;</span><span class="normal">label</span><span class="symbol">);</span>
1179 <span class="normal">  </span><span class="function"><a href="../glib/glib-Memory-Allocation.html#g-free">g_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">closure</span><span class="symbol">);</span>
1180
1181 <span class="normal">  </span><span class="keyword">return</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
1182 <span class="cbracket">}</span>
1183
1184 <span class="normal">  </span><span class="comment">/* within another thread */</span>
1185 <span class="normal">  closure </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib/glib-Memory-Allocation.html#g-new0">g_new0</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">SomeClosure</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
1186 <span class="normal">  </span><span class="comment">/* always take a reference on GObject instances */</span>
1187 <span class="normal">  closure</span><span class="symbol">-&gt;</span><span class="normal">label </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../gobject/gobject-The-Base-Object-Type.html#g-object-ref">g_object_ref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">my_application</span><span class="symbol">-&gt;</span><span class="normal">label</span><span class="symbol">);</span>
1188 <span class="normal">  closure</span><span class="symbol">-&gt;</span><span class="normal">text </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib/glib-String-Utility-Functions.html#g-strdup">g_strdup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">processed_text_to_update_the_label</span><span class="symbol">);</span>
1189
1190 <span class="normal">  </span><span class="function"><a href="clutter-General.html#clutter-threads-add-idle-full">clutter_threads_add_idle_full</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH-IDLE:CAPS">G_PRIORITY_HIGH_IDLE</a></span><span class="symbol">,</span>
1191 <span class="normal">                                 update_ui</span><span class="symbol">,</span>
1192 <span class="normal">                                 closure</span><span class="symbol">,</span>
1193 <span class="normal">                                 <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span></pre></td>
1194       </tr>
1195     </tbody>
1196   </table>
1197 </div>
1198
1199 <p>
1200 </p>
1201 <p>
1202 Rename to: clutter_threads_add_idle
1203 </p>
1204 <div class="variablelist"><table border="0">
1205 <col align="left" valign="top">
1206 <tbody>
1207 <tr>
1208 <td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
1209 <td>the priority of the timeout source. Typically this will be in the
1210 range between <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE:CAPS"><span class="type">G_PRIORITY_DEFAULT_IDLE</span></a> and <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH-IDLE:CAPS"><span class="type">G_PRIORITY_HIGH_IDLE</span></a>
1211 </td>
1212 </tr>
1213 <tr>
1214 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1215 <td>function to call</td>
1216 </tr>
1217 <tr>
1218 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1219 <td>data to pass to the function</td>
1220 </tr>
1221 <tr>
1222 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
1223 <td>functio to call when the idle source is removed</td>
1224 </tr>
1225 <tr>
1226 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1227 <td>the ID (greater than 0) of the event source.</td>
1228 </tr>
1229 </tbody>
1230 </table></div>
1231 <p class="since">Since 0.4</p>
1232 </div>
1233 <hr>
1234 <div class="refsect2">
1235 <a name="clutter-threads-add-timeout"></a><h3>clutter_threads_add_timeout ()</h3>
1236 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_timeout         (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> interval</code></em>,
1237                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1238                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
1239 <p>
1240 Simple wrapper around <a class="link" href="clutter-General.html#clutter-threads-add-timeout-full" title="clutter_threads_add_timeout_full ()"><code class="function">clutter_threads_add_timeout_full()</code></a>.
1241 </p>
1242 <div class="variablelist"><table border="0">
1243 <col align="left" valign="top">
1244 <tbody>
1245 <tr>
1246 <td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
1247 <td>the time between calls to the function, in milliseconds</td>
1248 </tr>
1249 <tr>
1250 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1251 <td>function to call</td>
1252 </tr>
1253 <tr>
1254 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1255 <td>data to pass to the function</td>
1256 </tr>
1257 <tr>
1258 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1259 <td>the ID (greater than 0) of the event source.</td>
1260 </tr>
1261 </tbody>
1262 </table></div>
1263 <p class="since">Since 0.4</p>
1264 </div>
1265 <hr>
1266 <div class="refsect2">
1267 <a name="clutter-threads-add-timeout-full"></a><h3>clutter_threads_add_timeout_full ()</h3>
1268 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_timeout_full    (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
1269                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> interval</code></em>,
1270                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1271                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
1272                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
1273 <p>
1274 Sets a function to be called at regular intervals holding the Clutter
1275 threads lock, with the given priority. The function is called repeatedly
1276 until it returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, at which point the timeout is automatically
1277 removed and the function will not be called again. The <em class="parameter"><code>notify</code></em> function
1278 is called when the timeout is removed.
1279 </p>
1280 <p>
1281 The first call to the function will be at the end of the first <em class="parameter"><code>interval</code></em>.
1282 </p>
1283 <p>
1284 It is important to note that, due to how the Clutter main loop is
1285 implemented, the timing will not be accurate and it will not try to
1286 "keep up" with the interval.
1287 </p>
1288 <p>
1289 See also <a class="link" href="clutter-General.html#clutter-threads-add-idle-full" title="clutter_threads_add_idle_full ()"><code class="function">clutter_threads_add_idle_full()</code></a>.
1290 </p>
1291 <p>
1292 Rename to: clutter_threads_add_timeout
1293 </p>
1294 <div class="variablelist"><table border="0">
1295 <col align="left" valign="top">
1296 <tbody>
1297 <tr>
1298 <td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
1299 <td>the priority of the timeout source. Typically this will be in the
1300 range between <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><span class="type">G_PRIORITY_DEFAULT</span></a> and <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH:CAPS"><span class="type">G_PRIORITY_HIGH</span></a>.</td>
1301 </tr>
1302 <tr>
1303 <td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
1304 <td>the time between calls to the function, in milliseconds</td>
1305 </tr>
1306 <tr>
1307 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1308 <td>function to call</td>
1309 </tr>
1310 <tr>
1311 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1312 <td>data to pass to the function</td>
1313 </tr>
1314 <tr>
1315 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
1316 <td>function to call when the timeout source is removed</td>
1317 </tr>
1318 <tr>
1319 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1320 <td>the ID (greater than 0) of the event source.</td>
1321 </tr>
1322 </tbody>
1323 </table></div>
1324 <p class="since">Since 0.4</p>
1325 </div>
1326 <hr>
1327 <div class="refsect2">
1328 <a name="clutter-threads-add-frame-source"></a><h3>clutter_threads_add_frame_source ()</h3>
1329 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_frame_source    (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> fps</code></em>,
1330                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1331                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
1332 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1333 <h3 class="title">Warning</h3>
1334 <p><code class="literal">clutter_threads_add_frame_source</code> is deprecated and should not be used in newly-written code. 1.6</p>
1335 </div>
1336 <p>
1337 Simple wrapper around <a class="link" href="clutter-General.html#clutter-threads-add-frame-source-full" title="clutter_threads_add_frame_source_full ()"><code class="function">clutter_threads_add_frame_source_full()</code></a>.
1338 </p>
1339 <div class="variablelist"><table border="0">
1340 <col align="left" valign="top">
1341 <tbody>
1342 <tr>
1343 <td><p><span class="term"><em class="parameter"><code>fps</code></em> :</span></p></td>
1344 <td>the number of times per second to call the function</td>
1345 </tr>
1346 <tr>
1347 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1348 <td>function to call</td>
1349 </tr>
1350 <tr>
1351 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1352 <td>data to pass to the function</td>
1353 </tr>
1354 <tr>
1355 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1356 <td>the ID (greater than 0) of the event source.</td>
1357 </tr>
1358 </tbody>
1359 </table></div>
1360 <p class="since">Since 0.8</p>
1361 </div>
1362 <hr>
1363 <div class="refsect2">
1364 <a name="clutter-threads-add-frame-source-full"></a><h3>clutter_threads_add_frame_source_full ()</h3>
1365 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_frame_source_full
1366                                                         (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>,
1367                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> fps</code></em>,
1368                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1369                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
1370                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
1371 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1372 <h3 class="title">Warning</h3>
1373 <p><code class="literal">clutter_threads_add_frame_source_full</code> is deprecated and should not be used in newly-written code. 1.6</p>
1374 </div>
1375 <p>
1376 Sets a function to be called at regular intervals holding the Clutter
1377 threads lock, with the given priority. The function is called repeatedly
1378 until it returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, at which point the timeout is automatically
1379 removed and the function will not be called again. The <em class="parameter"><code>notify</code></em> function
1380 is called when the timeout is removed.
1381 </p>
1382 <p>
1383 This function is similar to <a class="link" href="clutter-General.html#clutter-threads-add-timeout-full" title="clutter_threads_add_timeout_full ()"><code class="function">clutter_threads_add_timeout_full()</code></a>
1384 except that it will try to compensate for delays. For example, if
1385 <em class="parameter"><code>func</code></em> takes half the interval time to execute then the function
1386 will be called again half the interval time after it finished. In
1387 contrast <a class="link" href="clutter-General.html#clutter-threads-add-timeout-full" title="clutter_threads_add_timeout_full ()"><code class="function">clutter_threads_add_timeout_full()</code></a> would not fire until a
1388 full interval after the function completes so the delay between
1389 calls would be <em class="parameter"><code>interval</code></em> * 1.5. This function does not however try
1390 to invoke the function multiple times to catch up missing frames if
1391 <em class="parameter"><code>func</code></em> takes more than <em class="parameter"><code>interval</code></em> ms to execute.
1392 </p>
1393 <p>
1394 See also <a class="link" href="clutter-General.html#clutter-threads-add-idle-full" title="clutter_threads_add_idle_full ()"><code class="function">clutter_threads_add_idle_full()</code></a>.
1395 </p>
1396 <p>
1397 Rename to: clutter_threads_add_frame_source
1398 </p>
1399 <div class="variablelist"><table border="0">
1400 <col align="left" valign="top">
1401 <tbody>
1402 <tr>
1403 <td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
1404 <td>the priority of the frame source. Typically this will be in the
1405 range between <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a> and <a href="../glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH:CAPS"><code class="literal">G_PRIORITY_HIGH</code></a>.</td>
1406 </tr>
1407 <tr>
1408 <td><p><span class="term"><em class="parameter"><code>fps</code></em> :</span></p></td>
1409 <td>the number of times per second to call the function</td>
1410 </tr>
1411 <tr>
1412 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1413 <td>function to call</td>
1414 </tr>
1415 <tr>
1416 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1417 <td>data to pass to the function</td>
1418 </tr>
1419 <tr>
1420 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
1421 <td>function to call when the timeout source is removed</td>
1422 </tr>
1423 <tr>
1424 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1425 <td>the ID (greater than 0) of the event source.</td>
1426 </tr>
1427 </tbody>
1428 </table></div>
1429 <p class="since">Since 0.8</p>
1430 </div>
1431 <hr>
1432 <div class="refsect2">
1433 <a name="clutter-threads-add-repaint-func"></a><h3>clutter_threads_add_repaint_func ()</h3>
1434 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_repaint_func    (<em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1435                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
1436                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
1437 <p>
1438 Adds a function to be called whenever Clutter is processing a new
1439 frame.
1440 </p>
1441 <p>
1442 If the function returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> it is automatically removed from the
1443 list of repaint functions and will not be called again.
1444 </p>
1445 <p>
1446 This function is guaranteed to be called from within the same thread
1447 that called <a class="link" href="clutter-General.html#clutter-main" title="clutter_main ()"><code class="function">clutter_main()</code></a>, and while the Clutter lock is being held;
1448 the function will be called within the main loop, so it is imperative
1449 that it does not block, otherwise the frame time budget may be lost.
1450 </p>
1451 <p>
1452 A repaint function is useful to ensure that an update of the scenegraph
1453 is performed before the scenegraph is repainted; for instance, uploading
1454 a frame from a video into a <a class="link" href="ClutterTexture.html" title="ClutterTexture"><span class="type">ClutterTexture</span></a>. By default, a repaint
1455 function added using this function will be invoked prior to the frame
1456 being processed.
1457 </p>
1458 <p>
1459 Adding a repaint function does not automatically ensure that a new
1460 frame will be queued.
1461 </p>
1462 <p>
1463 When the repaint function is removed (either because it returned <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>
1464 or because <a class="link" href="clutter-General.html#clutter-threads-remove-repaint-func" title="clutter_threads_remove_repaint_func ()"><code class="function">clutter_threads_remove_repaint_func()</code></a> has been called) the
1465 <em class="parameter"><code>notify</code></em> function will be called, if any is set.
1466 </p>
1467 <p>
1468 See also: <a class="link" href="clutter-General.html#clutter-threads-add-repaint-func-full" title="clutter_threads_add_repaint_func_full ()"><code class="function">clutter_threads_add_repaint_func_full()</code></a>
1469 </p>
1470 <div class="variablelist"><table border="0">
1471 <col align="left" valign="top">
1472 <tbody>
1473 <tr>
1474 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1475 <td>the function to be called within the paint cycle</td>
1476 </tr>
1477 <tr>
1478 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1479 <td>data to be passed to the function, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>
1480 </td>
1481 </tr>
1482 <tr>
1483 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
1484 <td>function to be called when removing the repaint
1485 function, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>
1486 </td>
1487 </tr>
1488 <tr>
1489 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1490 <td>the ID (greater than 0) of the repaint function. You
1491 can use the returned integer to remove the repaint function by
1492 calling <a class="link" href="clutter-General.html#clutter-threads-remove-repaint-func" title="clutter_threads_remove_repaint_func ()"><code class="function">clutter_threads_remove_repaint_func()</code></a>.</td>
1493 </tr>
1494 </tbody>
1495 </table></div>
1496 <p class="since">Since 1.0</p>
1497 </div>
1498 <hr>
1499 <div class="refsect2">
1500 <a name="ClutterRepaintFlags"></a><h3>enum ClutterRepaintFlags</h3>
1501 <pre class="programlisting">typedef enum {
1502   CLUTTER_REPAINT_FLAGS_PRE_PAINT = 1 &lt;&lt; 0,
1503   CLUTTER_REPAINT_FLAGS_POST_PAINT = 1 &lt;&lt; 1,
1504   CLUTTER_REPAINT_FLAGS_QUEUE_REDRAW_ON_ADD = 1 &lt;&lt; 2
1505 } ClutterRepaintFlags;
1506 </pre>
1507 <p>
1508 Flags to pass to <a class="link" href="clutter-General.html#clutter-threads-add-repaint-func-full" title="clutter_threads_add_repaint_func_full ()"><code class="function">clutter_threads_add_repaint_func_full()</code></a>.
1509 </p>
1510 <div class="variablelist"><table border="0">
1511 <col align="left" valign="top">
1512 <tbody>
1513 <tr>
1514 <td><p><a name="CLUTTER-REPAINT-FLAGS-PRE-PAINT:CAPS"></a><span class="term"><code class="literal">CLUTTER_REPAINT_FLAGS_PRE_PAINT</code></span></p></td>
1515 <td>Run the repaint function prior to
1516   painting the stages
1517 </td>
1518 </tr>
1519 <tr>
1520 <td><p><a name="CLUTTER-REPAINT-FLAGS-POST-PAINT:CAPS"></a><span class="term"><code class="literal">CLUTTER_REPAINT_FLAGS_POST_PAINT</code></span></p></td>
1521 <td>Run the repaint function after
1522   painting the stages
1523 </td>
1524 </tr>
1525 <tr>
1526 <td><p><a name="CLUTTER-REPAINT-FLAGS-QUEUE-REDRAW-ON-ADD:CAPS"></a><span class="term"><code class="literal">CLUTTER_REPAINT_FLAGS_QUEUE_REDRAW_ON_ADD</code></span></p></td>
1527 <td>Ensure that a new frame
1528   is queued after adding the repaint function
1529 </td>
1530 </tr>
1531 </tbody>
1532 </table></div>
1533 <p class="since">Since 1.10</p>
1534 </div>
1535 <hr>
1536 <div class="refsect2">
1537 <a name="clutter-threads-add-repaint-func-full"></a><h3>clutter_threads_add_repaint_func_full ()</h3>
1538 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a>               clutter_threads_add_repaint_func_full
1539                                                         (<em class="parameter"><code><a class="link" href="clutter-General.html#ClutterRepaintFlags" title="enum ClutterRepaintFlags"><span class="type">ClutterRepaintFlags</span></a> flags</code></em>,
1540                                                          <em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
1541                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
1542                                                          <em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
1543 <p>
1544 Adds a function to be called whenever Clutter is processing a new
1545 frame.
1546 </p>
1547 <p>
1548 If the function returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> it is automatically removed from the
1549 list of repaint functions and will not be called again.
1550 </p>
1551 <p>
1552 This function is guaranteed to be called from within the same thread
1553 that called <a class="link" href="clutter-General.html#clutter-main" title="clutter_main ()"><code class="function">clutter_main()</code></a>, and while the Clutter lock is being held;
1554 the function will be called within the main loop, so it is imperative
1555 that it does not block, otherwise the frame time budget may be lost.
1556 </p>
1557 <p>
1558 A repaint function is useful to ensure that an update of the scenegraph
1559 is performed before the scenegraph is repainted; for instance, uploading
1560 a frame from a video into a <a class="link" href="ClutterTexture.html" title="ClutterTexture"><span class="type">ClutterTexture</span></a>. The <em class="parameter"><code>flags</code></em> passed to this
1561 function will determine the section of the frame processing that will
1562 result in <em class="parameter"><code>func</code></em> being called.
1563 </p>
1564 <p>
1565 Adding a repaint function does not automatically ensure that a new
1566 frame will be queued.
1567 </p>
1568 <p>
1569 When the repaint function is removed (either because it returned <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>
1570 or because <a class="link" href="clutter-General.html#clutter-threads-remove-repaint-func" title="clutter_threads_remove_repaint_func ()"><code class="function">clutter_threads_remove_repaint_func()</code></a> has been called) the
1571 <em class="parameter"><code>notify</code></em> function will be called, if any is set.
1572 </p>
1573 <div class="variablelist"><table border="0">
1574 <col align="left" valign="top">
1575 <tbody>
1576 <tr>
1577 <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td>
1578 <td>flags for the repaint function</td>
1579 </tr>
1580 <tr>
1581 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1582 <td>the function to be called within the paint cycle</td>
1583 </tr>
1584 <tr>
1585 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1586 <td>data to be passed to the function, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>
1587 </td>
1588 </tr>
1589 <tr>
1590 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
1591 <td>function to be called when removing the repaint
1592 function, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>
1593 </td>
1594 </tr>
1595 <tr>
1596 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1597 <td>the ID (greater than 0) of the repaint function. You
1598 can use the returned integer to remove the repaint function by
1599 calling <a class="link" href="clutter-General.html#clutter-threads-remove-repaint-func" title="clutter_threads_remove_repaint_func ()"><code class="function">clutter_threads_remove_repaint_func()</code></a>.</td>
1600 </tr>
1601 </tbody>
1602 </table></div>
1603 <p class="since">Since 1.10</p>
1604 </div>
1605 <hr>
1606 <div class="refsect2">
1607 <a name="clutter-threads-remove-repaint-func"></a><h3>clutter_threads_remove_repaint_func ()</h3>
1608 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_threads_remove_repaint_func (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> handle_id</code></em>);</pre>
1609 <p>
1610 Removes the repaint function with <em class="parameter"><code>handle_id</code></em> as its id
1611 </p>
1612 <div class="variablelist"><table border="0">
1613 <col align="left" valign="top">
1614 <tbody><tr>
1615 <td><p><span class="term"><em class="parameter"><code>handle_id</code></em> :</span></p></td>
1616 <td>an unsigned integer greater than zero</td>
1617 </tr></tbody>
1618 </table></div>
1619 <p class="since">Since 1.0</p>
1620 </div>
1621 <hr>
1622 <div class="refsect2">
1623 <a name="clutter-get-keyboard-grab"></a><h3>clutter_get_keyboard_grab ()</h3>
1624 <pre class="programlisting"><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      clutter_get_keyboard_grab           (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1625 <p>
1626 Queries the current keyboard grab of clutter.
1627 </p>
1628 <div class="variablelist"><table border="0">
1629 <col align="left" valign="top">
1630 <tbody><tr>
1631 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1632 <td>the actor currently holding the keyboard grab, or NULL if there is no grab. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
1633 </td>
1634 </tr></tbody>
1635 </table></div>
1636 <p class="since">Since 0.6</p>
1637 </div>
1638 <hr>
1639 <div class="refsect2">
1640 <a name="clutter-get-pointer-grab"></a><h3>clutter_get_pointer_grab ()</h3>
1641 <pre class="programlisting"><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="returnvalue">ClutterActor</span></a> *      clutter_get_pointer_grab            (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1642 <p>
1643 Queries the current pointer grab of clutter.
1644 </p>
1645 <div class="variablelist"><table border="0">
1646 <col align="left" valign="top">
1647 <tbody><tr>
1648 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1649 <td>the actor currently holding the pointer grab, or NULL if there is no grab. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
1650 </td>
1651 </tr></tbody>
1652 </table></div>
1653 <p class="since">Since 0.6</p>
1654 </div>
1655 <hr>
1656 <div class="refsect2">
1657 <a name="clutter-grab-keyboard"></a><h3>clutter_grab_keyboard ()</h3>
1658 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_grab_keyboard               (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>);</pre>
1659 <p>
1660 Grabs keyboard events, after the grab is done keyboard
1661 events (<a class="link" href="ClutterActor.html#ClutterActor-key-press-event" title='The "key-press-event" signal'><span class="type">"key-press-event"</span></a> and <a class="link" href="ClutterActor.html#ClutterActor-key-release-event" title='The "key-release-event" signal'><span class="type">"key-release-event"</span></a>)
1662 are delivered to this actor directly. The source set in the event will be
1663 the actor that would have received the event if the keyboard grab was not
1664 in effect.
1665 </p>
1666 <p>
1667 Like pointer grabs, keyboard grabs should only be used as a last
1668 resource.
1669 </p>
1670 <p>
1671 See also <a class="link" href="ClutterStage.html#clutter-stage-set-key-focus" title="clutter_stage_set_key_focus ()"><code class="function">clutter_stage_set_key_focus()</code></a> and <a class="link" href="ClutterActor.html#clutter-actor-grab-key-focus" title="clutter_actor_grab_key_focus ()"><code class="function">clutter_actor_grab_key_focus()</code></a>
1672 to perform a "soft" key grab and assign key focus to a specific actor.
1673 </p>
1674 <div class="variablelist"><table border="0">
1675 <col align="left" valign="top">
1676 <tbody><tr>
1677 <td><p><span class="term"><em class="parameter"><code>actor</code></em> :</span></p></td>
1678 <td>a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>
1679 </td>
1680 </tr></tbody>
1681 </table></div>
1682 <p class="since">Since 0.6</p>
1683 </div>
1684 <hr>
1685 <div class="refsect2">
1686 <a name="clutter-grab-pointer"></a><h3>clutter_grab_pointer ()</h3>
1687 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_grab_pointer                (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>);</pre>
1688 <p>
1689 Grabs pointer events, after the grab is done all pointer related events
1690 (press, motion, release, enter, leave and scroll) are delivered to this
1691 actor directly without passing through both capture and bubble phases of
1692 the event delivery chain. The source set in the event will be the actor
1693 that would have received the event if the pointer grab was not in effect.
1694 </p>
1695 <p>
1696 </p>
1697 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
1698 <h3 class="title">Note</h3>
1699 <p>Grabs completely override the entire event delivery chain
1700 done by Clutter. Pointer grabs should only be used as a last resource;
1701 using the <a class="link" href="ClutterActor.html#ClutterActor-captured-event" title='The "captured-event" signal'><span class="type">"captured-event"</span></a> signal should always be the
1702 preferred way to intercept event delivery to reactive actors.</p>
1703 </div>
1704 <p>
1705 </p>
1706 <p>
1707 This function should rarely be used.
1708 </p>
1709 <p>
1710 If a grab is required, you are strongly encouraged to use a specific
1711 input device by calling <a class="link" href="ClutterInputDevice.html#clutter-input-device-grab" title="clutter_input_device_grab ()"><code class="function">clutter_input_device_grab()</code></a>.
1712 </p>
1713 <div class="variablelist"><table border="0">
1714 <col align="left" valign="top">
1715 <tbody><tr>
1716 <td><p><span class="term"><em class="parameter"><code>actor</code></em> :</span></p></td>
1717 <td>a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>
1718 </td>
1719 </tr></tbody>
1720 </table></div>
1721 <p class="since">Since 0.6</p>
1722 </div>
1723 <hr>
1724 <div class="refsect2">
1725 <a name="clutter-ungrab-keyboard"></a><h3>clutter_ungrab_keyboard ()</h3>
1726 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_ungrab_keyboard             (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1727 <p>
1728 Removes an existing grab of the keyboard.
1729 </p>
1730 <p class="since">Since 0.6</p>
1731 </div>
1732 <hr>
1733 <div class="refsect2">
1734 <a name="clutter-ungrab-pointer"></a><h3>clutter_ungrab_pointer ()</h3>
1735 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_ungrab_pointer              (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1736 <p>
1737 Removes an existing grab of the pointer.
1738 </p>
1739 <p class="since">Since 0.6</p>
1740 </div>
1741 <hr>
1742 <div class="refsect2">
1743 <a name="clutter-grab-pointer-for-device"></a><h3>clutter_grab_pointer_for_device ()</h3>
1744 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_grab_pointer_for_device     (<em class="parameter"><code><a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> *actor</code></em>,
1745                                                          <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> id_</code></em>);</pre>
1746 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1747 <h3 class="title">Warning</h3>
1748 <p><code class="literal">clutter_grab_pointer_for_device</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a class="link" href="ClutterInputDevice.html#clutter-input-device-grab" title="clutter_input_device_grab ()"><code class="function">clutter_input_device_grab()</code></a> instead.</p>
1749 </div>
1750 <p>
1751 Grabs all the pointer events coming from the device <em class="parameter"><code>id</code></em> for <em class="parameter"><code>actor</code></em>.
1752 </p>
1753 <p>
1754 If <em class="parameter"><code>id</code></em> is -1 then this function is equivalent to <a class="link" href="clutter-General.html#clutter-grab-pointer" title="clutter_grab_pointer ()"><code class="function">clutter_grab_pointer()</code></a>.
1755 </p>
1756 <div class="variablelist"><table border="0">
1757 <col align="left" valign="top">
1758 <tbody>
1759 <tr>
1760 <td><p><span class="term"><em class="parameter"><code>actor</code></em> :</span></p></td>
1761 <td>a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>
1762 </td>
1763 </tr>
1764 <tr>
1765 <td><p><span class="term"><em class="parameter"><code>id_</code></em> :</span></p></td>
1766 <td>a device id, or -1</td>
1767 </tr>
1768 </tbody>
1769 </table></div>
1770 <p class="since">Since 0.8</p>
1771 </div>
1772 <hr>
1773 <div class="refsect2">
1774 <a name="clutter-ungrab-pointer-for-device"></a><h3>clutter_ungrab_pointer_for_device ()</h3>
1775 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_ungrab_pointer_for_device   (<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> id_</code></em>);</pre>
1776 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1777 <h3 class="title">Warning</h3>
1778 <p><code class="literal">clutter_ungrab_pointer_for_device</code> has been deprecated since version 1.10 and should not be used in newly-written code. Use <a class="link" href="ClutterInputDevice.html#clutter-input-device-ungrab" title="clutter_input_device_ungrab ()"><code class="function">clutter_input_device_ungrab()</code></a> instead.</p>
1779 </div>
1780 <p>
1781 Removes an existing grab of the pointer events for device <em class="parameter"><code>id_</code></em>.
1782 </p>
1783 <div class="variablelist"><table border="0">
1784 <col align="left" valign="top">
1785 <tbody><tr>
1786 <td><p><span class="term"><em class="parameter"><code>id_</code></em> :</span></p></td>
1787 <td>a device id</td>
1788 </tr></tbody>
1789 </table></div>
1790 <p class="since">Since 0.8</p>
1791 </div>
1792 <hr>
1793 <div class="refsect2">
1794 <a name="clutter-do-event"></a><h3>clutter_do_event ()</h3>
1795 <pre class="programlisting"><span class="returnvalue">void</span>                clutter_do_event                    (<em class="parameter"><code><a class="link" href="clutter-Events.html#ClutterEvent" title="union ClutterEvent"><span class="type">ClutterEvent</span></a> *event</code></em>);</pre>
1796 <p>
1797 Processes an event.
1798 </p>
1799 <p>
1800 The <em class="parameter"><code>event</code></em> must be a valid <a class="link" href="clutter-Events.html#ClutterEvent" title="union ClutterEvent"><span class="type">ClutterEvent</span></a> and have a <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>
1801 associated to it.
1802 </p>
1803 <p>
1804 This function is only useful when embedding Clutter inside another
1805 toolkit, and it should never be called by applications.
1806 </p>
1807 <div class="variablelist"><table border="0">
1808 <col align="left" valign="top">
1809 <tbody><tr>
1810 <td><p><span class="term"><em class="parameter"><code>event</code></em> :</span></p></td>
1811 <td>a <a class="link" href="clutter-Events.html#ClutterEvent" title="union ClutterEvent"><span class="type">ClutterEvent</span></a>.</td>
1812 </tr></tbody>
1813 </table></div>
1814 <p class="since">Since 0.4</p>
1815 </div>
1816 </div>
1817 </div>
1818 <div class="footer">
1819 <hr>
1820           Generated by GTK-Doc V1.18.1</div>
1821 </body>
1822 </html>