General

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

## Synopsis

    #define             CLUTTER_PRIORITY_REDRAW

    enum                ClutterInitError;
    ClutterInitError    clutter_init                        (int *argc,
                                                             char ***argv);
    ClutterInitError    clutter_init_with_args              (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);
    GOptionGroup *      clutter_get_option_group            (void);
    GOptionGroup *      clutter_get_option_group_without_init
                                                            (void);

    void                clutter_main                        (void);
    void                clutter_main_quit                   (void);
    gint                clutter_main_level                  (void);

    gboolean            clutter_get_debug_enabled           (void);
    gboolean            clutter_get_show_fps                (void);
    gulong              clutter_get_timestamp               (void);
    ClutterActor *      clutter_get_actor_by_gid            (guint32 id_);
    void                clutter_set_default_frame_rate      (guint frames_per_sec);
    guint               clutter_get_default_frame_rate      (void);
    void                clutter_set_motion_events_enabled   (gboolean enable);
    gboolean            clutter_get_motion_events_enabled   (void);
    void                clutter_clear_glyph_cache           (void);
    enum                ClutterFontFlags;
    void                clutter_set_font_flags              (ClutterFontFlags flags);
    ClutterFontFlags    clutter_get_font_flags              (void);
    PangoFontMap *      clutter_get_font_map                (void);
    enum                ClutterTextDirection;
    ClutterTextDirection clutter_get_default_text_direction (void);
    gboolean            clutter_get_accessibility_enabled   (void);
    void                clutter_disable_accessibility       (void);

    void                clutter_threads_set_lock_functions  (GCallback enter_fn,
                                                             GCallback leave_fn);
    void                clutter_threads_init                (void);
    void                clutter_threads_enter               (void);
    void                clutter_threads_leave               (void);
    guint               clutter_threads_add_idle            (GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_idle_full       (gint priority,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               clutter_threads_add_timeout         (guint interval,
                                                             GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_timeout_full    (gint priority,
                                                             guint interval,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               clutter_threads_add_frame_source    (guint fps,
                                                             GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_frame_source_full
                                                            (gint priority,
                                                             guint fps,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               clutter_threads_add_repaint_func    (GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    enum                ClutterRepaintFlags;
    guint               clutter_threads_add_repaint_func_full
                                                            (ClutterRepaintFlags flags,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                clutter_threads_remove_repaint_func (guint handle_id);

    ClutterActor *      clutter_get_keyboard_grab           (void);
    ClutterActor *      clutter_get_pointer_grab            (void);
    void                clutter_grab_keyboard               (ClutterActor *actor);
    void                clutter_grab_pointer                (ClutterActor *actor);
    void                clutter_ungrab_keyboard             (void);
    void                clutter_ungrab_pointer              (void);
    void                clutter_grab_pointer_for_device     (ClutterActor *actor,
                                                             gint id_);
    void                clutter_ungrab_pointer_for_device   (gint id_);

    void                clutter_do_event                    (ClutterEvent *event);

## Description

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

### 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()`.

Example 9. Thread Initialization

The code below shows how to correctly initialize Clutter in a multi-threaded environment. These operations are mandatory for applications that wish to use threads with Clutter.

    int
    main (int argc, char *argv[])
    {
      /* initialize Clutter */
      clutter_init (&argc, &argv);

      /* program code */

      /* acquire the main lock */
      clutter_threads_enter ();

      /* start the main loop */
      clutter_main ();

      /* release the main lock */
      clutter_threads_leave ();

      /* clean up */
      return 0;
    }

This threading model has the caveat that it is only safe to call Clutter's API when the lock has been acquired — which happens between pairs of `clutter_threads_enter()` and `clutter_threads_leave()` calls.

The only safe and portable way to use the Clutter API in a multi-threaded environment is to never access the API from a thread that did not call `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 finished.

Clutter provides thread-aware variants of `g_idle_add()` and `g_timeout_add()` that acquire the Clutter lock before invoking the provided callback: `clutter_threads_add_idle()` and `clutter_threads_add_timeout()`.

The example below shows how to use a worker thread to perform a blocking operation, and perform UI updates using the main loop.

Example 10. A worker thread example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    #include <stdio.h>
    #include <stdlib.h>
    #include <clutter/clutter.h>

    /* our thread-specific data */
    typedef struct
    {
      ClutterActor *stage;
      ClutterActor *label;
      ClutterActor *progress;
      ClutterActor *rect;

      ClutterTransition *flip;
      ClutterTransition *bounce;
    } TestThreadData;

    static TestThreadData *
    test_thread_data_new (void)
    {
      TestThreadData *data;

      data = g_new0 (TestThreadData, 1);

      return data;
    }

    static void
    test_thread_data_free (gpointer _data)
    {
      TestThreadData *data = _data;

      if (data == NULL)
        return;

      g_print ("Removing thread data [%p]\n", _data);

      g_clear_object (&data->progress);
      g_clear_object (&data->label);
      g_clear_object (&data->stage);
      g_clear_object (&data->rect);
      g_clear_object (&data->flip);
      g_clear_object (&data->bounce);

      g_free (data);
    }

    static gboolean
    test_thread_done_idle (gpointer user_data)
    {
      TestThreadData *data = user_data;

      g_print ("Last update [%p]\n", data);

      clutter_text_set_text (CLUTTER_TEXT (data->label), "Completed");

      clutter_actor_remove_transition (data->rect, "bounce");
      clutter_actor_remove_transition (data->rect, "flip");

      return G_SOURCE_REMOVE;
    }

    static void
    test_thread_data_done (gpointer _data)
    {
      if (_data == NULL)
        return;

      g_print ("Thread completed\n");

      /* since the TestThreadData structure references Clutter data structures
       * we need to free it from within the same thread that called clutter_main()
       * which means using an idle handler in the main loop.
       *
       * clutter_threads_add_idle() is guaranteed to run the callback passed to
       * to it under the Big Clutter Lock.
       */
      clutter_threads_add_idle_full (G_PRIORITY_DEFAULT,
                                     test_thread_done_idle,
                                     _data,
                                     test_thread_data_free);
    }

    /* thread local storage */
    static GPrivate test_thread_data = G_PRIVATE_INIT (test_thread_data_done);

    typedef struct {
      gint count;
      TestThreadData *thread_data;
    } TestUpdate;

    static gboolean
    update_label_idle (gpointer data)
    {
      TestUpdate *update = data;
      guint width;
      gchar *text;

      if (update->thread_data->label == NULL)
        return G_SOURCE_REMOVE;

      text = g_strdup_printf ("Count to %d", update->count);
      clutter_text_set_text (CLUTTER_TEXT (update->thread_data->label), text);

      clutter_actor_set_width (update->thread_data->label, -1);

      if (update->count == 0)
        width = 0;
      else if (update->count == 100)
        width = 350;
      else
        width = (guint) (update->count / 100.0 * 350.0);

      clutter_actor_save_easing_state (update->thread_data->progress);
      clutter_actor_set_width (update->thread_data->progress, width);
      clutter_actor_restore_easing_state (update->thread_data->progress);

      g_free (text);
      g_free (update);

      return G_SOURCE_REMOVE;
    }

    static void
    do_something_very_slow (void)
    {
      TestThreadData *data;
      gint i;

      data = g_private_get (&test_thread_data);

      for (i = 0; i <= 100; i++)
        {
          gint msecs;

          msecs = 1 + (int) (100.0 * rand () / ((RAND_MAX + 1.0) / 3));

          /* sleep for a while, to emulate some work being done */
          g_usleep (msecs * 1000);

          if ((i % 10) == 0)
            {
              TestUpdate *update;

              /* update the UI from within the main loop, making sure that the
               * Big Clutter Lock is held; only one thread at a time can call
               * Clutter API, and it's mandatory to do this from the same thread
               * that called clutter_init()/clutter_main().
               */
              update = g_new (TestUpdate, 1);
              update->count = i;
              update->thread_data = data;

              clutter_threads_add_idle_full (G_PRIORITY_HIGH,
                                             update_label_idle,
                                             update, NULL);
            }
        }
    }

    static gpointer
    test_thread_func (gpointer user_data)
    {
      TestThreadData *data = user_data;

      g_private_set (&test_thread_data, data);

      /* this function will block */
      do_something_very_slow ();

      return NULL;
    }

    static ClutterActor *count_label   = NULL;
    static ClutterActor *help_label    = NULL;
    static ClutterActor *progress_rect = NULL;
    static ClutterActor *rect          = NULL;
    static ClutterTransition *flip     = NULL;
    static ClutterTransition *bounce   = NULL;

    static gboolean
    on_key_press_event (ClutterStage *stage,
                        ClutterEvent *event,
                        gpointer      user_data)
    {
      TestThreadData *data;

      switch (clutter_event_get_key_symbol (event))
        {
        case CLUTTER_KEY_s:
          clutter_text_set_text (CLUTTER_TEXT (help_label), "Press 'q' to quit");

          /* start the animations */
          clutter_actor_add_transition (rect, "flip", flip);
          clutter_actor_add_transition (rect, "bounce", bounce);

          /* the data structure holding all our objects */
          data = test_thread_data_new ();
          data->stage = g_object_ref (stage);
          data->label = g_object_ref (count_label);
          data->progress = g_object_ref (progress_rect);
          data->rect = g_object_ref (rect);
          data->flip = g_object_ref (flip);
          data->bounce = g_object_ref (bounce);

          /* start the thread that updates the counter and the progress bar */
          g_thread_new ("counter", test_thread_func, data);

          return CLUTTER_EVENT_STOP;

        case CLUTTER_KEY_q:
          clutter_main_quit ();

          return CLUTTER_EVENT_STOP;

        default:
          break;
        }

      return CLUTTER_EVENT_PROPAGATE;
    }

    int
    main (int argc, char *argv[])
    {
      ClutterTransition *transition;
      ClutterActor *stage;
      ClutterPoint start = CLUTTER_POINT_INIT (75.f, 150.f);
      ClutterPoint end = CLUTTER_POINT_INIT (400.f, 150.f);

      if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
        return 1;

      stage = clutter_stage_new ();
      clutter_stage_set_title (CLUTTER_STAGE (stage), "Threading");
      clutter_actor_set_background_color (stage, CLUTTER_COLOR_Aluminium3);
      clutter_actor_set_size (stage, 600, 300);
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);

      count_label = clutter_text_new_with_text ("Mono 12", "Counter");
      clutter_actor_set_position (count_label, 350, 50);
      clutter_actor_add_child (stage, count_label);

      help_label = clutter_text_new_with_text ("Mono 12", "Press 's' to start");
      clutter_actor_set_position (help_label, 50, 50);
      clutter_actor_add_child (stage, help_label);

      /* a progress bar */
      progress_rect = clutter_actor_new ();
      clutter_actor_set_background_color (progress_rect, CLUTTER_COLOR_DarkChameleon);
      clutter_actor_set_position (progress_rect, 50, 225);
      clutter_actor_set_size (progress_rect, 350, 50);
      clutter_actor_add_child (stage, progress_rect);

      /* an actor we bounce around */
      rect = clutter_actor_new ();
      clutter_actor_set_background_color (rect, CLUTTER_COLOR_LightScarletRed);
      clutter_actor_set_position (rect, 75, 150);
      clutter_actor_set_size (rect, 50, 50);
      clutter_actor_set_pivot_point (rect, .5f, .5f);
      clutter_actor_set_opacity (rect, 224);
      clutter_actor_add_child (stage, rect);

      /* two transitions we use to bounce rect around */
      transition = clutter_property_transition_new ("rotation-angle-z");
      clutter_transition_set_from (transition, G_TYPE_DOUBLE, 0.0);
      clutter_transition_set_to (transition, G_TYPE_DOUBLE, 360.0);
      clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);
      clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
      clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
      flip = transition;

      transition = clutter_property_transition_new ("position");
      clutter_transition_set_from (transition, CLUTTER_TYPE_POINT, &start);
      clutter_transition_set_to (transition, CLUTTER_TYPE_POINT, &end);
      clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);
      clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
      clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
      bounce = transition;

      g_signal_connect (stage,
                        "button-press-event", G_CALLBACK (clutter_main_quit),
                        NULL);
      g_signal_connect (stage,
                        "key-press-event", G_CALLBACK (on_key_press_event),
                        NULL);

      clutter_actor_show (stage);

      clutter_main ();

      return EXIT_SUCCESS;
    }

## Details

### 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

### enum ClutterInitError

    typedef enum {
      CLUTTER_INIT_SUCCESS        =  1,
      CLUTTER_INIT_ERROR_UNKNOWN  =  0,
      CLUTTER_INIT_ERROR_THREADS  = -1,
      CLUTTER_INIT_ERROR_BACKEND  = -2,
      CLUTTER_INIT_ERROR_INTERNAL = -3
    } ClutterInitError;

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

`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

### 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.

### Note

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.

`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 `--help` 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.

`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 `--help` output, after ``programname` [OPTION...]`. [allow-none]
`entries` : | a `NULL` terminated array of GOptionEntrys describing the options of your program. [array][allow-none]
`translation_domain` : | a translation domain to use for translating the `--help` 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);

### Warning

`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);

### Warning

`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 `CLUTTER_SHOW_FPS` environment variable or passing the `--clutter-show-fps` command line argument. *

Returns : | `TRUE` if Clutter should show the FPS.

Since 0.4

### clutter_get_timestamp ()

    gulong              clutter_get_timestamp               (void);

### Warning

`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_);

### Warning

`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_`.

`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);

### Warning

`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.

`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);

### Warning

`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 ClutterStages managed by Clutter.

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

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

- ClutterActor::enter-event

- ClutterActor::leave-event

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

Since 0.6

### clutter_get_motion_events_enabled ()

    gboolean            clutter_get_motion_events_enabled   (void);

### Warning

`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);

### Warning

`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

### enum ClutterFontFlags

    typedef enum {
     /*< prefix=CLUTTER_FONT >*/
      CLUTTER_FONT_MIPMAPPING = (1 << 0),
      CLUTTER_FONT_HINTING    = (1 << 1)
    } ClutterFontFlags;

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

`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

### clutter_set_font_flags ()

    void                clutter_set_font_flags              (ClutterFontFlags flags);

### Warning

`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.

`flags` : | The new flags

Since 1.0

### clutter_get_font_flags ()

    ClutterFontFlags    clutter_get_font_flags              (void);

### Warning

`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

### enum ClutterTextDirection

    typedef enum {
      CLUTTER_TEXT_DIRECTION_DEFAULT,
      CLUTTER_TEXT_DIRECTION_LTR,
      CLUTTER_TEXT_DIRECTION_RTL
    } ClutterTextDirection;

The text direction to be used by ClutterActors

`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

### 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 `CLUTTER_TEXT_DIRECTION` 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.

`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);

### Warning

`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);

### Warning

`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);

### Warning

`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.

`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

`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()`.

`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

`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);

### Warning

`clutter_threads_add_frame_source` is deprecated and should not be used in newly-written code. 1.6

Simple wrapper around `clutter_threads_add_frame_source_full()`.

`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);

### Warning

`clutter_threads_add_frame_source_full` is deprecated and should not be used in newly-written code. 1.6

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

`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()`

`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

### enum ClutterRepaintFlags

    typedef enum {
      CLUTTER_REPAINT_FLAGS_PRE_PAINT = 1 << 0,
      CLUTTER_REPAINT_FLAGS_POST_PAINT = 1 << 1,
      CLUTTER_REPAINT_FLAGS_QUEUE_REDRAW_ON_ADD = 1 << 2
    } ClutterRepaintFlags;

Flags to pass to `clutter_threads_add_repaint_func_full()`.

`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

### 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.

`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

`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.

`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.

### Note

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()`.

`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_);

### Warning

`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()`.

`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_);

### Warning

`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_`.

`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.

`event` : | a ClutterEvent.

Since 0.4