Next: , Previous: ClutterListModel, Up: Top

44 General

Various 'global' clutter functions.

44.1 Overview

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

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

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.

44.3 Usage

— Function: clutter-main

Starts the Clutter mainloop.

— Function: clutter-main-quit

Terminates the Clutter mainloop.

— Function: clutter-main-level ⇒  (ret int)

Retrieves the depth of the Clutter mainloop.

ret
The level of the mainloop.
— Function: clutter-get-default-frame-rate ⇒  (ret unsigned-int)

Retrieves the default frame rate. See clutter-set-default-frame-rate.

ret
the default frame rate

Since 0.6

— Function: clutter-get-font-map ⇒  (ret <pango-font-map>)

Retrieves the <pango-font-map> instance used by Clutter. You can use the global font map object with the COGL Pango API.

ret
the <pango-font-map> instance. The returned value is owned by Clutter and it should never be unreferenced.

Since 1.0

— Function: clutter-get-default-text-direction ⇒  (ret <clutter-text-direction>)

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.

ret
the default text direction

Since 1.2

— Function: clutter-get-accessibility-enabled ⇒  (ret bool)

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

ret
‘#t’ if Clutter has accessibility support enabled

Since 1.4

— Function: clutter-get-keyboard-grab ⇒  (ret <clutter-actor>)

Queries the current keyboard grab of clutter.

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

Since 0.6

— Function: clutter-get-pointer-grab ⇒  (ret <clutter-actor>)

Queries the current pointer grab of clutter.

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

Since 0.6

— Function: clutter-grab-keyboard (actor <clutter-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 <clutter-actor>

Since 0.6

— Function: clutter-grab-pointer (actor <clutter-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.

actor
a <clutter-actor>

Since 0.6

— Function: clutter-ungrab-keyboard

Removes an existing grab of the keyboard.

Since 0.6

— Function: clutter-ungrab-pointer

Removes an existing grab of the pointer.

Since 0.6

— Function: clutter-do-event (event <clutter-event>)

Processes an event.

The event must be a valid <clutter-event> and have a <clutter-stage> associated to it.

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

event
a <clutter-event>.

Since 0.4