Clutter Reference Manual: General

## General General — Various 'global' Clutter functions. |

## Functions

#define | CLUTTER_PRIORITY_REDRAW
ClutterInitError | clutter_init ()
ClutterInitError | clutter_init_with_args ()
GOptionGroup * | clutter_get_option_group ()
GOptionGroup * | clutter_get_option_group_without_init ()
void | clutter_main ()
void | clutter_main_quit ()
gint | clutter_main_level ()
gboolean | clutter_get_debug_enabled ()
gboolean | clutter_get_show_fps ()
gulong | clutter_get_timestamp ()
ClutterActor * | clutter_get_actor_by_gid ()
void | clutter_set_default_frame_rate ()
guint | clutter_get_default_frame_rate ()
void | clutter_set_motion_events_enabled ()
gboolean | clutter_get_motion_events_enabled ()
void | clutter_clear_glyph_cache ()
void | clutter_set_font_flags ()
ClutterFontFlags | clutter_get_font_flags ()
PangoFontMap * | clutter_get_font_map ()
ClutterTextDirection | clutter_get_default_text_direction ()
gboolean | clutter_get_accessibility_enabled ()
void | clutter_disable_accessibility ()
void | clutter_threads_set_lock_functions ()
void | clutter_threads_init ()
void | clutter_threads_enter ()
void | clutter_threads_leave ()
guint | clutter_threads_add_idle ()
guint | clutter_threads_add_idle_full ()
guint | clutter_threads_add_timeout ()
guint | clutter_threads_add_timeout_full ()
guint | clutter_threads_add_frame_source ()
guint | clutter_threads_add_frame_source_full ()
guint | clutter_threads_add_repaint_func ()
guint | clutter_threads_add_repaint_func_full ()
void | clutter_threads_remove_repaint_func ()
ClutterActor * | clutter_get_keyboard_grab ()
ClutterActor * | clutter_get_pointer_grab ()
void | clutter_grab_keyboard ()
void | clutter_grab_pointer ()
void | clutter_ungrab_keyboard ()
void | clutter_ungrab_pointer ()
void | clutter_grab_pointer_for_device ()
void | clutter_ungrab_pointer_for_device ()
void | clutter_do_event ()

## Types and Values

enum | ClutterInitError
enum | ClutterFontFlags
enum | ClutterTextDirection
enum | ClutterRepaintFlags

## Description

Functions to retrieve various global Clutter resources and other utility functions for mainloops, events and threads

#### The Clutter Threading Model

Clutter is *thread-aware*: all operations performed by Clutter are assumed to be under the Big Clutter Lock, which is created when the threading is initialized through `clutter_init()`, and entered when calling user-related code during event handling and actor drawing.

The only safe and portable way to use the Clutter API in a multi-threaded environment is to only access the Clutter API from a thread that did called `clutter_init()` and `clutter_main()`.

The common pattern for using threads with Clutter is to use worker threads to perform blocking operations and then install idle or timeout sources with the result when the thread finishes, and update the UI from those callbacks.

For a working example of how to use a worker thread to update the UI, see threads.c

## Functions

### CLUTTER_PRIORITY_REDRAW

    #define CLUTTER_PRIORITY_REDRAW         (G_PRIORITY_HIGH_IDLE + 50)

Priority of the redraws. This is chosen to be lower than the GTK+ redraw and resize priorities, because in application with both GTK+ and Clutter it's more likely that the Clutter part will be continually animating (and thus able to starve GTK+) than vice-versa.

Since 0.8

### clutter_init ()

    ClutterInitError
    clutter_init (int *argc,
                  char ***argv);

Initialises everything needed to operate with Clutter and parses some standard command line options; `argc` and `argv` are adjusted accordingly so your own code will never see those standard arguments.

It is safe to call this function multiple times.

This function will not abort in case of errors during initialization; `clutter_init()` will print out the error message on stderr, and will return an error code. It is up to the application code to handle this case. If you need to display the error message yourself, you can use `clutter_init_with_args()`, which takes a GError pointer.

If this function fails, and returns an error code, any subsequent Clutter API will have undefined behaviour - including segmentation faults and assertion failures. Make sure to handle the returned ClutterInitError enumeration value.

#### Parameters

argc | The number of arguments in `argv` . | [inout]
argv | A pointer to an array of arguments. | [array length=argc][inout][allow-none]

#### Returns

a ClutterInitError value

### clutter_init_with_args ()

    ClutterInitError
    clutter_init_with_args (int *argc,
                            char ***argv,
                            const char *parameter_string,
                            GOptionEntry *entries,
                            const char *translation_domain,
                            GError **error);

This function does the same work as `clutter_init()`. Additionally, it allows you to add your own command line options, and it automatically generates nicely formatted <option>--help</option> output. Note that your program will be terminated after writing out the help output. Also note that, in case of error, the error message will be placed inside `error` instead of being printed on the display.

Just like `clutter_init()`, if this function returns an error code then any subsequent call to any other Clutter API will result in undefined behaviour - including segmentation faults.

#### Parameters

argc | a pointer to the number of command line arguments. | [inout]
argv | a pointer to the array of command line arguments. | [array length=argc][inout][allow-none]
parameter_string | a string which is displayed in the first line of <option>--help</option> output, after <literal><replaceable>programname</replaceable> [OPTION...]</literal>. | [allow-none]
entries | a `NULL` terminated array of GOptionEntry<!-- -->s describing the options of your program. | [array][allow-none]
translation_domain | a translation domain to use for translating the <option>--help</option> output for the options in `entries` with `gettext()`, or `NULL`. | [allow-none]
error | a return location for a GError. | [allow-none]

#### Returns

`CLUTTER_INIT_SUCCESS` if Clutter has been successfully initialised, or other values or ClutterInitError in case of error.

Since 0.2

### clutter_get_option_group ()

    GOptionGroup *
    clutter_get_option_group (void);

Returns a GOptionGroup for the command line arguments recognized by Clutter. You should add this group to your GOptionContext with `g_option_context_add_group()`, if you are using `g_option_context_parse()` to parse your commandline arguments.

Calling `g_option_context_parse()` with Clutter's GOptionGroup will result in Clutter's initialization. That is, the following code:

    1
    2
    g_option_context_set_main_group (context, clutter_get_option_group ());
    res = g_option_context_parse (context, &argc, &argc, NULL);

is functionally equivalent to:

    1
    clutter_init (&argc, &argv);

After `g_option_context_parse()` on a GOptionContext containing the Clutter GOptionGroup has returned `TRUE`, Clutter is guaranteed to be initialized.

#### Returns

a GOptionGroup for the commandline arguments recognized by Clutter.

[transfer full]

Since 0.2

### clutter_get_option_group_without_init ()

    GOptionGroup *
    clutter_get_option_group_without_init (void);

Returns a GOptionGroup for the command line arguments recognized by Clutter. You should add this group to your GOptionContext with `g_option_context_add_group()`, if you are using `g_option_context_parse()` to parse your commandline arguments.

Unlike `clutter_get_option_group()`, calling `g_option_context_parse()` with the GOptionGroup returned by this function requires a subsequent explicit call to `clutter_init()`; use this function when needing to set foreign display connection with `clutter_x11_set_display()`, or with ``gtk_clutter_init()``.

#### Returns

a GOptionGroup for the commandline arguments recognized by Clutter.

[transfer full]

Since 0.8.2

### clutter_main ()

    void
    clutter_main (void);

Starts the Clutter mainloop.

### clutter_main_quit ()

    void
    clutter_main_quit (void);

Terminates the Clutter mainloop.

### clutter_main_level ()

    gint
    clutter_main_level (void);

Retrieves the depth of the Clutter mainloop.

#### Returns

The level of the mainloop.

### clutter_get_debug_enabled ()

    gboolean
    clutter_get_debug_enabled (void);

`clutter_get_debug_enabled` has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything.

Check if Clutter has debugging enabled.

#### Returns

`FALSE`

### clutter_get_show_fps ()

    gboolean
    clutter_get_show_fps (void);

`clutter_get_show_fps` 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 variable or the configuration file to determine whether Clutter should print out the FPS counter on the console.

Returns whether Clutter should print out the frames per second on the console. You can enable this setting either using the <literal>CLUTTER_SHOW_FPS</literal> environment variable or passing the <literal>--clutter-show-fps</literal> command line argument. *

#### Returns

`TRUE` if Clutter should show the FPS.

Since 0.4

### clutter_get_timestamp ()

    gulong
    clutter_get_timestamp (void);

`clutter_get_timestamp` has been deprecated since version 1.10 and should not be used in newly-written code.

Use GTimer or `g_get_monotonic_time()` for a proper timing source

Returns the approximate number of microseconds passed since Clutter was intialised.

This function shdould not be used by application code.

The output of this function depends on whether Clutter was configured to enable its debugging code paths, so it's less useful than intended.

Since Clutter 1.10, this function is an alias to `g_get_monotonic_time()` if Clutter was configured to enable the debugging code paths.

#### Returns

Number of microseconds since `clutter_init()` was called, or zero if Clutter was not configured with debugging code paths.

### clutter_get_actor_by_gid ()

    ClutterActor *
    clutter_get_actor_by_gid (guint32 id_);

`clutter_get_actor_by_gid` has been deprecated since version 1.8 and should not be used in newly-written code.

The id is not used any longer.

Retrieves the ClutterActor with `id_` .

#### Parameters

id_ | a ClutterActor unique id. |

#### Returns

the actor with the passed id or `NULL`. The returned actor does not have its reference count increased.

[transfer none]

Since 0.6

### clutter_set_default_frame_rate ()

    void
    clutter_set_default_frame_rate (guint frames_per_sec);

`clutter_set_default_frame_rate` has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything any more.

Sets the default frame rate. This frame rate will be used to limit the number of frames drawn if Clutter is not able to synchronize with the vertical refresh rate of the display. When synchronization is possible, this value is ignored.

#### Parameters

frames_per_sec | the new default frame rate |

Since 0.6

### clutter_get_default_frame_rate ()

    guint
    clutter_get_default_frame_rate (void);

Retrieves the default frame rate. See `clutter_set_default_frame_rate()`.

#### Returns

the default frame rate

Since 0.6

### clutter_set_motion_events_enabled ()

    void
    clutter_set_motion_events_enabled (gboolean enable);

`clutter_set_motion_events_enabled` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_stage_set_motion_events_enabled()` instead.

Sets whether per-actor motion events should be enabled or not on all ClutterStage<!-- -->s managed by Clutter.

If `enable` is `FALSE` the following events will not work:

- ClutterActor::motion-event, except on the ClutterStage

- ClutterActor::enter-event

- ClutterActor::leave-event

#### Parameters

enable | `TRUE` to enable per-actor motion events |

Since 0.6

### clutter_get_motion_events_enabled ()

    gboolean
    clutter_get_motion_events_enabled (void);

`clutter_get_motion_events_enabled` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_stage_get_motion_events_enabled()` instead.

Gets whether the per-actor motion events are enabled.

#### Returns

`TRUE` if the motion events are enabled

Since 0.6

### clutter_clear_glyph_cache ()

    void
    clutter_clear_glyph_cache (void);

`clutter_clear_glyph_cache` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_get_font_map()` and `cogl_pango_font_map_clear_glyph_cache()` instead.

Clears the internal cache of glyphs used by the Pango renderer. This will free up some memory and GL texture resources. The cache will be automatically refilled as more text is drawn.

Since 0.8

### clutter_set_font_flags ()

    void
    clutter_set_font_flags (ClutterFontFlags flags);

`clutter_set_font_flags` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_backend_set_font_options()` and the cairo_font_option_t API.

Sets the font quality options for subsequent text rendering operations.

Using mipmapped textures will improve the quality for scaled down text but will use more texture memory.

Enabling hinting improves text quality for static text but may introduce some artifacts if the text is animated.

#### Parameters

flags | The new flags |

Since 1.0

### clutter_get_font_flags ()

    ClutterFontFlags
    clutter_get_font_flags (void);

`clutter_get_font_flags` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_backend_get_font_options()` and the cairo_font_options_t API.

Gets the current font flags for rendering text. See `clutter_set_font_flags()`.

#### Returns

The font flags

Since 1.0

### clutter_get_font_map ()

    PangoFontMap *
    clutter_get_font_map (void);

Retrieves the PangoFontMap instance used by Clutter. You can use the global font map object with the COGL Pango API.

#### Returns

the PangoFontMap instance. The returned value is owned by Clutter and it should never be unreferenced.

[transfer none]

Since 1.0

### clutter_get_default_text_direction ()

    ClutterTextDirection
    clutter_get_default_text_direction (void);

Retrieves the default direction for the text. The text direction is determined by the locale and/or by the <varname>CLUTTER_TEXT_DIRECTION</varname> environment variable.

The default text direction can be overridden on a per-actor basis by using `clutter_actor_set_text_direction()`.

#### Returns

the default text direction

Since 1.2

### clutter_get_accessibility_enabled ()

    gboolean
    clutter_get_accessibility_enabled (void);

Returns whether Clutter has accessibility support enabled. As least, a value of TRUE means that there are a proper AtkUtil implementation available

#### Returns

`TRUE` if Clutter has accessibility support enabled

Since 1.4

### clutter_disable_accessibility ()

    void
    clutter_disable_accessibility (void);

Disable loading the accessibility support. It has the same effect as setting the environment variable CLUTTER_DISABLE_ACCESSIBILITY. For the same reason, this method should be called before `clutter_init()`.

Since 1.14

### clutter_threads_set_lock_functions ()

    void
    clutter_threads_set_lock_functions (GCallback enter_fn,
                                        GCallback leave_fn);

Allows the application to replace the standard method that Clutter uses to protect its data structures. Normally, Clutter creates a single GMutex that is locked by `clutter_threads_enter()`, and released by `clutter_threads_leave()`; using this function an application provides, instead, a function `enter_fn` that is called by `clutter_threads_enter()` and a function `leave_fn` that is called by `clutter_threads_leave()`.

The functions must provide at least same locking functionality as the default implementation, but can also do extra application specific processing.

As an example, consider an application that has its own recursive lock that when held, holds the Clutter lock as well. When Clutter unlocks the Clutter lock when entering a recursive main loop, the application must temporarily release its lock as well.

Most threaded Clutter apps won't need to use this method.

This method must be called before `clutter_init()`, and cannot be called multiple times.

#### Parameters

enter_fn | function called when aquiring the Clutter main lock |
leave_fn | function called when releasing the Clutter main lock |

Since 0.4

### clutter_threads_init ()

    void
    clutter_threads_init (void);

`clutter_threads_init` has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything. Threading support is initialized when Clutter is initialized.

Initialises the Clutter threading mechanism, so that Clutter API can be called by multiple threads, using `clutter_threads_enter()` and `clutter_threads_leave()` to mark the critical sections.

You must call `g_thread_init()` before this function.

This function must be called before `clutter_init()`.

It is safe to call this function multiple times.

Since 0.4

### clutter_threads_enter ()

    void
    clutter_threads_enter (void);

`clutter_threads_enter` has been deprecated since version 1.12 and should not be used in newly-written code.

This function should not be used by application code; marking critical sections is not portable on various platforms. Instead of acquiring the Clutter lock, schedule UI updates from the main loop using `clutter_threads_add_idle()` or `clutter_threads_add_timeout()`.

Locks the Clutter thread lock.

Since 0.4

### clutter_threads_leave ()

    void
    clutter_threads_leave (void);

`clutter_threads_leave` has been deprecated since version 1.12 and should not be used in newly-written code.

This function should not be used by application code; marking critical sections is not portable on various platforms. Instead of acquiring the Clutter lock, schedule UI updates from the main loop using `clutter_threads_add_idle()` or `clutter_threads_add_timeout()`.

Unlocks the Clutter thread lock.

Since 0.4

### clutter_threads_add_idle ()

    guint
    clutter_threads_add_idle (GSourceFunc func,
                              gpointer data);

Simple wrapper around `clutter_threads_add_idle_full()` using the default priority.

#### Parameters

func | function to call |
data | data to pass to the function |

#### Returns

the ID (greater than 0) of the event source.

Since 0.4

### clutter_threads_add_idle_full ()

    guint
    clutter_threads_add_idle_full (gint priority,
                                   GSourceFunc func,
                                   gpointer data,
                                   GDestroyNotify notify);

Adds a function to be called whenever there are no higher priority events pending. If the function returns `FALSE` it is automatically removed from the list of event sources and will not be called again.

This function can be considered a thread-safe variant of `g_idle_add_full()`: it will call `function` while holding the Clutter lock. It is logically equivalent to the following implementation:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    static gboolean
    idle_safe_callback (gpointer data)
    {
       SafeClosure *closure = data;
       gboolean res = FALSE;

       // mark the critical section //

       clutter_threads_enter();

       // the callback does not need to acquire the Clutter
        / lock itself, as it is held by the this proxy handler
        //
       res = closure->callback (closure->data);

       clutter_threads_leave();

       return res;
    }
    static gulong
    add_safe_idle (GSourceFunc callback,
                   gpointer    data)
    {
      SafeClosure *closure = g_new0 (SafeClosure, 1);

      closure->callback = callback;
      closure->data = data;

      return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE,
                              idle_safe_callback,
                              closure,
                              g_free)
    }

This function should be used by threaded applications to make sure that `func` is emitted under the Clutter threads lock and invoked from the same thread that started the Clutter main loop. For instance, it can be used to update the UI using the results from a worker thread:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    static gboolean
    update_ui (gpointer data)
    {
      SomeClosure *closure = data;

      // it is safe to call Clutter API from this function because
       / it is invoked from the same thread that started the main
       / loop and under the Clutter thread lock
       //
      clutter_label_set_text (CLUTTER_LABEL (closure->label),
                              closure->text);

      g_object_unref (closure->label);
      g_free (closure);

      return FALSE;
    }

      // within another thread //
      closure = g_new0 (SomeClosure, 1);
      // always take a reference on GObject instances //
      closure->label = g_object_ref (my_application->label);
      closure->text = g_strdup (processed_text_to_update_the_label);

      clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE,
                                     update_ui,
                                     closure,
                                     NULL);

Rename to: clutter_threads_add_idle

#### Parameters

priority | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT_IDLE and G_PRIORITY_HIGH_IDLE |
func | function to call |
data | data to pass to the function |
notify | functio to call when the idle source is removed |

#### Returns

the ID (greater than 0) of the event source.

Since 0.4

### clutter_threads_add_timeout ()

    guint
    clutter_threads_add_timeout (guint interval,
                                 GSourceFunc func,
                                 gpointer data);

Simple wrapper around `clutter_threads_add_timeout_full()`.

#### Parameters

interval | the time between calls to the function, in milliseconds |
func | function to call |
data | data to pass to the function |

#### Returns

the ID (greater than 0) of the event source.

Since 0.4

### clutter_threads_add_timeout_full ()

    guint
    clutter_threads_add_timeout_full (gint priority,
                                      guint interval,
                                      GSourceFunc func,
                                      gpointer data,
                                      GDestroyNotify notify);

Sets a function to be called at regular intervals holding the Clutter threads lock, with the given priority. The function is called repeatedly until it returns `FALSE`, at which point the timeout is automatically removed and the function will not be called again. The `notify` function is called when the timeout is removed.

The first call to the function will be at the end of the first `interval` .

It is important to note that, due to how the Clutter main loop is implemented, the timing will not be accurate and it will not try to "keep up" with the interval.

See also `clutter_threads_add_idle_full()`.

Rename to: clutter_threads_add_timeout

#### Parameters

priority | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. |
interval | the time between calls to the function, in milliseconds |
func | function to call |
data | data to pass to the function |
notify | function to call when the timeout source is removed |

#### Returns

the ID (greater than 0) of the event source.

Since 0.4

### clutter_threads_add_frame_source ()

    guint
    clutter_threads_add_frame_source (guint fps,
                                      GSourceFunc func,
                                      gpointer data);

`clutter_threads_add_frame_source` has been deprecated since version 1.6 and should not be used in newly-written code.

Simple wrapper around `clutter_threads_add_frame_source_full()`.

#### Parameters

fps | the number of times per second to call the function |
func | function to call |
data | data to pass to the function |

#### Returns

the ID (greater than 0) of the event source.

Since 0.8

### clutter_threads_add_frame_source_full ()

    guint
    clutter_threads_add_frame_source_full (gint priority,
                                           guint fps,
                                           GSourceFunc func,
                                           gpointer data,
                                           GDestroyNotify notify);

`clutter_threads_add_frame_source_full` has been deprecated since version 1.6 and should not be used in newly-written code.

Sets a function to be called at regular intervals holding the Clutter threads lock, with the given priority. The function is called repeatedly until it returns `FALSE`, at which point the timeout is automatically removed and the function will not be called again. The `notify` function is called when the timeout is removed.

This function is similar to `clutter_threads_add_timeout_full()` except that it will try to compensate for delays. For example, if `func` takes half the interval time to execute then the function will be called again half the interval time after it finished. In contrast `clutter_threads_add_timeout_full()` would not fire until a full interval after the function completes so the delay between calls would be `interval` * 1.5. This function does not however try to invoke the function multiple times to catch up missing frames if `func` takes more than `interval` ms to execute.

See also `clutter_threads_add_idle_full()`.

Rename to: clutter_threads_add_frame_source

#### Parameters

priority | the priority of the frame source. Typically this will be in the range between `G_PRIORITY_DEFAULT` and `G_PRIORITY_HIGH`. |
fps | the number of times per second to call the function |
func | function to call |
data | data to pass to the function |
notify | function to call when the timeout source is removed |

#### Returns

the ID (greater than 0) of the event source.

Since 0.8

### clutter_threads_add_repaint_func ()

    guint
    clutter_threads_add_repaint_func (GSourceFunc func,
                                      gpointer data,
                                      GDestroyNotify notify);

Adds a function to be called whenever Clutter is processing a new frame.

If the function returns `FALSE` it is automatically removed from the list of repaint functions and will not be called again.

This function is guaranteed to be called from within the same thread that called `clutter_main()`, and while the Clutter lock is being held; the function will be called within the main loop, so it is imperative that it does not block, otherwise the frame time budget may be lost.

A repaint function is useful to ensure that an update of the scenegraph is performed before the scenegraph is repainted; for instance, uploading a frame from a video into a ClutterTexture. By default, a repaint function added using this function will be invoked prior to the frame being processed.

Adding a repaint function does not automatically ensure that a new frame will be queued.

When the repaint function is removed (either because it returned `FALSE` or because `clutter_threads_remove_repaint_func()` has been called) the `notify` function will be called, if any is set.

See also: `clutter_threads_add_repaint_func_full()`

#### Parameters

func | the function to be called within the paint cycle |
data | data to be passed to the function, or `NULL` |
notify | function to be called when removing the repaint function, or `NULL` |

#### Returns

the ID (greater than 0) of the repaint function. You can use the returned integer to remove the repaint function by calling `clutter_threads_remove_repaint_func()`.

Since 1.0

### clutter_threads_add_repaint_func_full ()

    guint
    clutter_threads_add_repaint_func_full (ClutterRepaintFlags flags,
                                           GSourceFunc func,
                                           gpointer data,
                                           GDestroyNotify notify);

Adds a function to be called whenever Clutter is processing a new frame.

If the function returns `FALSE` it is automatically removed from the list of repaint functions and will not be called again.

This function is guaranteed to be called from within the same thread that called `clutter_main()`, and while the Clutter lock is being held; the function will be called within the main loop, so it is imperative that it does not block, otherwise the frame time budget may be lost.

A repaint function is useful to ensure that an update of the scenegraph is performed before the scenegraph is repainted; for instance, uploading a frame from a video into a ClutterTexture. The `flags` passed to this function will determine the section of the frame processing that will result in `func` being called.

Adding a repaint function does not automatically ensure that a new frame will be queued.

When the repaint function is removed (either because it returned `FALSE` or because `clutter_threads_remove_repaint_func()` has been called) the `notify` function will be called, if any is set.

#### Parameters

flags | flags for the repaint function |
func | the function to be called within the paint cycle |
data | data to be passed to the function, or `NULL` |
notify | function to be called when removing the repaint function, or `NULL` |

#### Returns

the ID (greater than 0) of the repaint function. You can use the returned integer to remove the repaint function by calling `clutter_threads_remove_repaint_func()`.

Since 1.10

### clutter_threads_remove_repaint_func ()

    void
    clutter_threads_remove_repaint_func (guint handle_id);

Removes the repaint function with `handle_id` as its id

#### Parameters

handle_id | an unsigned integer greater than zero |

Since 1.0

### clutter_get_keyboard_grab ()

    ClutterActor *
    clutter_get_keyboard_grab (void);

Queries the current keyboard grab of clutter.

#### Returns

the actor currently holding the keyboard grab, or NULL if there is no grab.

[transfer none]

Since 0.6

### clutter_get_pointer_grab ()

    ClutterActor *
    clutter_get_pointer_grab (void);

Queries the current pointer grab of clutter.

#### Returns

the actor currently holding the pointer grab, or NULL if there is no grab.

[transfer none]

Since 0.6

### clutter_grab_keyboard ()

    void
    clutter_grab_keyboard (ClutterActor *actor);

Grabs keyboard events, after the grab is done keyboard events (“key-press-event” and “key-release-event”) are delivered to this actor directly. The source set in the event will be the actor that would have received the event if the keyboard grab was not in effect.

Like pointer grabs, keyboard grabs should only be used as a last resource.

See also `clutter_stage_set_key_focus()` and `clutter_actor_grab_key_focus()` to perform a "soft" key grab and assign key focus to a specific actor.

#### Parameters

actor | a ClutterActor |

Since 0.6

### clutter_grab_pointer ()

    void
    clutter_grab_pointer (ClutterActor *actor);

Grabs pointer events, after the grab is done all pointer related events (press, motion, release, enter, leave and scroll) are delivered to this actor directly without passing through both capture and bubble phases of the event delivery chain. The source set in the event will be the actor that would have received the event if the pointer grab was not in effect.

Grabs completely override the entire event delivery chain done by Clutter. Pointer grabs should only be used as a last resource; using the “captured-event” signal should always be the preferred way to intercept event delivery to reactive actors.

This function should rarely be used.

If a grab is required, you are strongly encouraged to use a specific input device by calling `clutter_input_device_grab()`.

#### Parameters

actor | a ClutterActor |

Since 0.6

### clutter_ungrab_keyboard ()

    void
    clutter_ungrab_keyboard (void);

Removes an existing grab of the keyboard.

Since 0.6

### clutter_ungrab_pointer ()

    void
    clutter_ungrab_pointer (void);

Removes an existing grab of the pointer.

Since 0.6

### clutter_grab_pointer_for_device ()

    void
    clutter_grab_pointer_for_device (ClutterActor *actor,
                                     gint id_);

`clutter_grab_pointer_for_device` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_input_device_grab()` instead.

Grabs all the pointer events coming from the device `id` for `actor` .

If `id` is -1 then this function is equivalent to `clutter_grab_pointer()`.

#### Parameters

actor | a ClutterActor |
id_ | a device id, or -1 |

Since 0.8

### clutter_ungrab_pointer_for_device ()

    void
    clutter_ungrab_pointer_for_device (gint id_);

`clutter_ungrab_pointer_for_device` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_input_device_ungrab()` instead.

Removes an existing grab of the pointer events for device `id_` .

#### Parameters

id_ | a device id |

Since 0.8

### clutter_do_event ()

    void
    clutter_do_event (ClutterEvent *event);

Processes an event.

The `event` must be a valid ClutterEvent and have a ClutterStage associated to it.

This function is only useful when embedding Clutter inside another toolkit, and it should never be called by applications.

#### Parameters

event | a ClutterEvent. |

Since 0.4

## Types and Values

### enum ClutterInitError

Error conditions returned by `clutter_init()` and `clutter_init_with_args()`.

#### Members

CLUTTER_INIT_SUCCESS | Initialisation successful |
CLUTTER_INIT_ERROR_UNKNOWN | Unknown error |
CLUTTER_INIT_ERROR_THREADS | Thread initialisation failed |
CLUTTER_INIT_ERROR_BACKEND | Backend initialisation failed |
CLUTTER_INIT_ERROR_INTERNAL | Internal error |

Since 0.2

### enum ClutterFontFlags

Runtime flags to change the font quality. To be used with `clutter_set_font_flags()`.

#### Members

CLUTTER_FONT_MIPMAPPING | Set to use mipmaps for the glyph cache textures. |
CLUTTER_FONT_HINTING | Set to enable hinting on the glyphs. |

Since 1.0

### enum ClutterTextDirection

The text direction to be used by ClutterActor<!-- -->s

#### Members

CLUTTER_TEXT_DIRECTION_DEFAULT | Use the default setting, as returned by `clutter_get_default_text_direction()` |
CLUTTER_TEXT_DIRECTION_LTR | Use left-to-right text direction |
CLUTTER_TEXT_DIRECTION_RTL | Use right-to-left text direction |

Since 1.2

### enum ClutterRepaintFlags

Flags to pass to `clutter_threads_add_repaint_func_full()`.

#### Members

CLUTTER_REPAINT_FLAGS_PRE_PAINT | Run the repaint function prior to painting the stages |
CLUTTER_REPAINT_FLAGS_POST_PAINT | Run the repaint function after painting the stages |
CLUTTER_REPAINT_FLAGS_QUEUE_REDRAW_ON_ADD | Ensure that a new frame is queued after adding the repaint function |

Since 1.10