Functions

actor_box_alloc ()

base_init ()

cairo_clear (cr)

cairo_set_source_color (cr, color)

check_version (major, minor, micro)

check_windowing_backend (backend_type)

clear_glyph_cache ()

color_from_hls (hue, luminance, saturation)

color_from_pixel (pixel)

color_from_string (str)

color_get_static (color)

container_class_find_child_property (klass, property_name)

container_class_list_child_properties (klass)

disable_accessibility ()

do_event (event)

event_add_filter (stage, func, *user_data)

event_get ()

event_peek ()

event_remove_filter (id)

events_pending ()

feature_available (feature)

feature_get_all ()

frame_source_add (priority, fps, func, *data)

get_accessibility_enabled ()

get_actor_by_gid (id_)

get_current_event ()

get_current_event_time ()

get_debug_enabled ()

get_default_backend ()

get_default_frame_rate ()

get_default_text_direction ()

get_font_flags ()

get_font_map ()

get_input_device_for_id (id_)

get_keyboard_grab ()

get_motion_events_enabled ()

get_pointer_grab ()

get_script_id (gobject)

get_show_fps ()

get_timestamp ()

grab_keyboard (actor)

grab_pointer (actor)

grab_pointer_for_device (actor, id_)

image_error_quark ()

init (argv)

init_error_quark ()

init_with_args (argv, parameter_string, entries, translation_domain)

keysym_to_unicode (keyval)

main ()

main_level ()

main_quit ()

matrix_alloc ()

point_zero ()

rect_zero ()

redraw (stage)

script_error_quark ()

set_default_frame_rate (frames_per_sec)

set_font_flags (flags)

set_motion_events_enabled (enable)

set_windowing_backend (backend_type)

shader_error_quark ()

test_add_data_full (test_path, test_func, *test_data)

test_check_actor_at_point (stage, point, actor)

test_check_color_at_point (stage, point, color)

test_get_stage ()

test_init (argc, argv)

test_run ()

texture_error_quark ()

threads_add_frame_source (priority, fps, func, *data)

threads_add_idle (priority, func, *data)

threads_add_repaint_func (func, *data)

threads_add_repaint_func_full (flags, func, *data)

threads_add_timeout (priority, interval, func, *data)

threads_enter ()

threads_init ()

threads_leave ()

threads_remove_repaint_func (handle_id)

ungrab_keyboard ()

ungrab_pointer ()

ungrab_pointer_for_device (id_)

unicode_to_keysym (wc)

units_from_cm (cm)

units_from_em (em)

units_from_em_for_font (font_name, em)

units_from_mm (mm)

units_from_pixels (px)

units_from_pt (pt)

units_from_string (str)

util_next_p2 (a)

value_dup_paint_node (value)

value_get_color (value)

value_get_paint_node (value)

value_get_shader_float (value)

value_get_shader_int (value)

value_get_shader_matrix (value)

value_get_units (value)

value_set_color (value, color)

value_set_paint_node (value, node)

value_set_shader_float (value, floats)

value_set_shader_int (value, ints)

value_set_shader_matrix (value, matrix)

value_set_units (value, units)

value_take_paint_node (value, node)

Details

Clutter.actor_box_alloc()
Returns:

the newly allocated Clutter.ActorBox. Use Clutter.ActorBox.free() to free its resources

Return type:

Clutter.ActorBox

Allocates a new Clutter.ActorBox.

New in version 1.12.

Clutter.base_init()
Clutter.cairo_clear(cr)
Parameters:

cr (cairo.Context) – a Cairo context

Utility function to clear a Cairo context.

New in version 1.12.

Clutter.cairo_set_source_color(cr, color)
Parameters:

Utility function for setting the source color of cr using a Clutter.Color. This function is the equivalent of:

cairo_set_source_rgba (cr,
color->red / 255.0,
color->green / 255.0,
color->blue / 255.0,
color->alpha / 255.0);

New in version 1.0.

Clutter.check_version(major, minor, micro)
Parameters:

  • major (int) – major version, like 1 in 1.2.3

  • minor (int) – minor version, like 2 in 1.2.3

  • micro (int) – micro version, like 3 in 1.2.3

Returns:

True if the version of the Clutter library is greater than (major, minor, micro), and False otherwise

Return type:

bool

Run-time version check, to check the version the Clutter library that an application is currently linked against

This is the run-time equivalent of the compile-time %CLUTTER_CHECK_VERSION pre-processor macro

New in version 1.2.

Clutter.check_windowing_backend(backend_type)
Parameters:

backend_type (str) – the name of the backend to check

Returns:

True if the current Clutter windowing system backend is the one checked, and False otherwise

Return type:

bool

Checks the run-time name of the Clutter windowing system backend, using the symbolic macros like %CLUTTER_WINDOWING_WIN32 or Clutter.WINDOWING_X11.

This function should be used in conjuction with the compile-time macros inside applications and libraries that are using the platform-specific windowing system API, to ensure that they are running on the correct windowing system; for instance:

#ifdef CLUTTER_WINDOWING_X11
  if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11))
    {
      // it is safe to use the clutter_x11_* API
    }
  else
#endif
#ifdef CLUTTER_WINDOWING_WIN32
  if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32))
    {
      // it is safe to use the clutter_win32_* API
    }
  else
#endif
    g_error ("Unknown Clutter backend.");

New in version 1.10.

Clutter.clear_glyph_cache()

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.

New in version 0.8.

Deprecated since version 1.10: Use Clutter.get_font_map() and CoglPango.font_map_clear_glyph_cache() instead.

Clutter.color_from_hls(hue, luminance, saturation)
Parameters:

  • hue (float) – hue value, in the 0 .. 360 range

  • luminance (float) – luminance value, in the 0 .. 1 range

  • saturation (float) – saturation value, in the 0 .. 1 range

Returns:

return location for a Clutter.Color

Return type:

color: Clutter.Color

Converts a color expressed in HLS (hue, luminance and saturation) values into a Clutter.Color.

Clutter.color_from_pixel(pixel)
Parameters:

pixel (int) – a 32 bit packed integer containing a color

Returns:

return location for a Clutter.Color

Return type:

color: Clutter.Color

Converts pixel from the packed representation of a four 8 bit channel color to a Clutter.Color.

Clutter.color_from_string(str)
Parameters:

str (str) – a string specifiying a color

Returns:

True if parsing succeeded, and False otherwise

color:

return location for a Clutter.Color

Return type:

(bool, color: Clutter.Color)

Parses a string definition of a color, filling the Clutter.Color.red, Clutter.Color.green, Clutter.Color.blue and Clutter.Color.alpha fields of color.

The color is not allocated.

The format of str can be either one of:

  • a standard name (as taken from the X11 rgb.txt file)

  • an hexadecimal value in the form: #rgb, #rrggbb, #rgba, or #rrggbbaa

  • a RGB color in the form: rgb(r, g, b)

  • a RGB color in the form: rgba(r, g, b, a)

  • a HSL color in the form: hsl(h, s, l) -a HSL color in the form: hsla(h, s, l, a)

where ‘r’, ‘g’, ‘b’ and ‘a’ are (respectively) the red, green, blue color intensities and the opacity. The ‘h’, ‘s’ and ‘l’ are (respectively) the hue, saturation and luminance values.

In the rgb() and rgba() formats, the ‘r’, ‘g’, and ‘b’ values are either integers between 0 and 255, or percentage values in the range between 0% and 100%; the percentages require the ‘%’ character. The ‘a’ value, if specified, can only be a floating point value between 0.0 and 1.0.

In the hls() and hlsa() formats, the ‘h’ value (hue) is an angle between 0 and 360.0 degrees; the ‘l’ and ‘s’ values (luminance and saturation) are percentage values in the range between 0% and 100%. The ‘a’ value, if specified, can only be a floating point value between 0.0 and 1.0.

Whitespace inside the definitions is ignored; no leading whitespace is allowed.

If the alpha component is not specified then it is assumed to be set to be fully opaque.

New in version 1.0.

Clutter.color_get_static(color)
Parameters:

color (Clutter.StaticColor) – the named global color

Returns:

a pointer to a static color; the returned pointer is owned by Clutter and it should never be modified or freed

Return type:

Clutter.Color

Retrieves a static color for the given color name

Static colors are created by Clutter and are guaranteed to always be available and valid

New in version 1.6.

Clutter.container_class_find_child_property(klass, property_name)
Parameters:
Returns:

The GObject.ParamSpec for the property or None if no such property exist.

Return type:

GObject.ParamSpec

Looks up the GObject.ParamSpec for a child property of klass.

New in version 0.8.

Clutter.container_class_list_child_properties(klass)
Parameters:

klass (GObject.ObjectClass) – a GObject.ObjectClass implementing the Clutter.Container interface.

Returns:

an array of GObject.ParamSpec s which should be freed after use.

Return type:

[GObject.ParamSpec]

Returns an array of GObject.ParamSpec for all child properties.

New in version 0.8.

Clutter.disable_accessibility()

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

New in version 1.14.

Clutter.do_event(event)
Parameters:

event (Clutter.Event) – a 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.

New in version 0.4.

Clutter.event_add_filter(stage, func, *user_data)
Parameters:
Returns:

an identifier for the event filter, to be used with Clutter.Event.remove_filter().

Return type:

int

Adds a function which will be called for all events that Clutter processes. The function will be called before any signals are emitted for the event and it will take precedence over any grabs.

New in version 1.18.

Clutter.event_get()
Returns:

A Clutter.Event or None if queue empty

Return type:

Clutter.Event

Pops an event off the event queue. Applications should not need to call this.

New in version 0.4.

Clutter.event_peek()
Returns:

A Clutter.Event or None if queue empty.

Return type:

Clutter.Event

Returns a pointer to the first event from the event queue but does not remove it.

New in version 0.4.

Clutter.event_remove_filter(id)
Parameters:

id (int) – The ID of the event filter, as returned from Clutter.Event.add_filter()

Removes an event filter that was previously added with Clutter.Event.add_filter().

New in version 1.18.

Clutter.events_pending()
Returns:

True if there are pending events, False otherwise.

Return type:

bool

Checks if events are pending in the event queue.

New in version 0.4.

Clutter.feature_available(feature)
Parameters:

feature (Clutter.FeatureFlags) – a Clutter.FeatureFlags

Returns:

True if a feature is available

Return type:

bool

Checks whether feature is available. feature can be a logical OR of Clutter.FeatureFlags.

New in version 0.2.

Clutter.feature_get_all()
Returns:

a logical OR of all the supported features.

Return type:

Clutter.FeatureFlags

Returns all the supported features.

New in version 0.2.

Clutter.frame_source_add(priority, fps, func, *data)
Parameters:
Returns:

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

Return type:

int

Sets a function to be called at regular intervals with the given priority. The function is called repeatedly until it returns False, at which point the timeout is automatically destroyed and the function will not be called again. The notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first interval.

This function is similar to GLib.timeout_add() 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 GLib.timeout_add() would not fire until a full interval after the function completes so the delay between calls would be 1.0 / fps * 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.

New in version 0.8.

Deprecated since version 1.6: There is no direct replacement for this API.

Clutter.get_accessibility_enabled()
Returns:

True if Clutter has accessibility support enabled

Return type:

bool

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

New in version 1.4.

Clutter.get_actor_by_gid(id_)
Parameters:

id (int) – a Clutter.Actor unique id.

Returns:

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

Return type:

Clutter.Actor

Retrieves the Clutter.Actor with id_.

New in version 0.6.

Deprecated since version 1.8: The id is deprecated, and this function always returns None. Use the proper scene graph API in Clutter.Actor to find a child of the stage.

Clutter.get_current_event()
Returns:

The current Clutter.Event, or None if none

Return type:

Clutter.Event

If an event is currently being processed, return that event. This function is intended to be used to access event state that might not be exposed by higher-level widgets. For example, to get the key modifier state from a Button ‘clicked’ event.

New in version 1.2.

Clutter.get_current_event_time()
Returns:

the event timestamp, or Clutter.CURRENT_TIME

Return type:

int

Retrieves the timestamp of the last event, if there is an event or if the event has a timestamp.

New in version 1.0.

Clutter.get_debug_enabled()
Returns:

False

Return type:

bool

Check if Clutter has debugging enabled.

Deprecated since version 1.10: This function does not do anything.

Clutter.get_default_backend()
Returns:

the default backend. You should not ref or unref the returned object. Applications should rarely need to use this.

Return type:

Clutter.Backend

Retrieves the default Clutter.Backend used by Clutter. The Clutter.Backend holds backend-specific configuration options.

New in version 0.4.

Clutter.get_default_frame_rate()
Returns:

the default frame rate

Return type:

int

Retrieves the default frame rate. See Clutter.set_default_frame_rate().

New in version 0.6.

Clutter.get_default_text_direction()
Returns:

the default text direction

Return type:

Clutter.TextDirection

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

New in version 1.2.

Clutter.get_font_flags()
Returns:

The font flags

Return type:

Clutter.FontFlags

Gets the current font flags for rendering text. See Clutter.set_font_flags().

New in version 1.0.

Deprecated since version 1.10: Use Clutter.Backend.get_font_options() and the cairo.FontOptions API.

Clutter.get_font_map()
Returns:

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

Return type:

Pango.FontMap

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

New in version 1.0.

Clutter.get_input_device_for_id(id_)
Parameters:

id (int) – the unique id for a device

Returns:

a Clutter.InputDevice, or None

Return type:

Clutter.InputDevice

Retrieves the Clutter.InputDevice from its id_. This is a convenience wrapper for Clutter.DeviceManager.get_device() and it is functionally equivalent to:

ClutterDeviceManager *manager;
ClutterInputDevice *device;

manager = clutter_device_manager_get_default ();
device = clutter_device_manager_get_device (manager, id);

New in version 0.8.

Deprecated since version 1.10: Use Clutter.DeviceManager.get_device() instead.

Clutter.get_keyboard_grab()
Returns:

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

Return type:

Clutter.Actor

Queries the current keyboard grab of clutter.

New in version 0.6.

Clutter.get_motion_events_enabled()
Returns:

True if the motion events are enabled

Return type:

bool

Gets whether the per-actor motion events are enabled.

New in version 0.6.

Deprecated since version 1.8: Use Clutter.Stage.get_motion_events_enabled() instead.

Clutter.get_pointer_grab()
Returns:

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

Return type:

Clutter.Actor

Queries the current pointer grab of clutter.

New in version 0.6.

Clutter.get_script_id(gobject)
Parameters:

gobject (GObject.Object) – a GObject.Object

Returns:

the script id, or None if object was not defined inside a UI definition file. The returned string is owned by the object and should never be modified or freed.

Return type:

str

Retrieves the Clutter script id, if any.

New in version 0.6.

Clutter.get_show_fps()
Returns:

True if Clutter should show the FPS.

Return type:

bool

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

New in version 0.4.

Deprecated since version 1.10: 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.

Clutter.get_timestamp()
Returns:

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

Return type:

int

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 GLib.get_monotonic_time() if Clutter was configured to enable the debugging code paths.

Deprecated since version 1.10: Use GLib.Timer or GLib.get_monotonic_time() for a proper timing source

Clutter.grab_keyboard(actor)
Parameters:

actor (Clutter.Actor) – a Clutter.Actor

Grabs keyboard events, after the grab is done keyboard events (Clutter.Actor ::key-press-event and Clutter.Actor ::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.

New in version 0.6.

Clutter.grab_pointer(actor)
Parameters:

actor (Clutter.Actor) – a 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 Clutter.Actor ::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.InputDevice.grab().

New in version 0.6.

Clutter.grab_pointer_for_device(actor, id_)
Parameters:

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

New in version 0.8.

Deprecated since version 1.10: Use Clutter.InputDevice.grab() instead.

Clutter.image_error_quark()
Return type:

int

Clutter.init(argv)
Parameters:

argv ([str] or None) – A pointer to an array of arguments.

Returns:

a Clutter.InitError value

argv:

A pointer to an array of arguments.

Return type:

(Clutter.InitError, argv: [str])

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 GLib.Error 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 Clutter.InitError enumeration value.

Clutter.init_error_quark()
Return type:

int

Clutter.init_with_args(argv, parameter_string, entries, translation_domain)
Parameters:

  • argv ([str] or None) – a pointer to the array of command line arguments

  • parameter_string (str or None) – a string which is displayed in the first line of –help output, after programname [OPTION...]

  • entries ([GLib.OptionEntry] or None) – a None terminated array of GLib.OptionEntry s describing the options of your program

  • translation_domain (str or None) – a translation domain to use for translating the –help output for the options in entries with gettext(), or None

Raises:

GLib.Error

Returns:

Clutter.InitError.SUCCESS if Clutter has been successfully initialised, or other values or Clutter.InitError in case of error.

argv:

a pointer to the array of command line arguments

Return type:

(Clutter.InitError, argv: [str])

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.

New in version 0.2.

Clutter.keysym_to_unicode(keyval)
Parameters:

keyval (int) – a key symbol

Returns:

a Unicode character, or 0 if there is no corresponding character.

Return type:

int

Converts keyval from a Clutter key symbol to the corresponding ISO10646 (Unicode) character.

Clutter.main()

Starts the Clutter mainloop.

Clutter.main_level()
Returns:

The level of the mainloop.

Return type:

int

Retrieves the depth of the Clutter mainloop.

Clutter.main_quit()

Terminates the Clutter mainloop.

Clutter.matrix_alloc()
Returns:

the newly allocated Clutter.Matrix

Return type:

Clutter.Matrix

Allocates enough memory to hold a Clutter.Matrix.

New in version 1.12.

Clutter.point_zero()
Returns:

a point centered in (0, 0); the returned Clutter.Point is owned by Clutter and it should not be modified or freed.

Return type:

Clutter.Point

A point centered at (0, 0).

The returned value can be used as a guard.

New in version 1.12.

Clutter.rect_zero()
Returns:

a rectangle with origin in (0, 0) and a size of 0. The returned Clutter.Rect is owned by Clutter and it should not be modified or freed.

Return type:

Clutter.Rect

A Clutter.Rect with Clutter.Rect.origin set at (0, 0) and a size of 0.

The returned value can be used as a guard.

New in version 1.12.

Clutter.redraw(stage)
Parameters:

stage (Clutter.Stage) –

Forces a redraw of the entire stage. Applications should never use this function, but queue a redraw using Clutter.Actor.queue_redraw().

This function should only be used by libraries integrating Clutter from within another toolkit.

Deprecated since version 1.10: Use Clutter.Stage.ensure_redraw() instead.

Clutter.script_error_quark()
Return type:

int

Clutter.set_default_frame_rate(frames_per_sec)
Parameters:

frames_per_sec (int) – the new default frame rate

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.

New in version 0.6.

Deprecated since version 1.10: This function does not do anything any more.

Clutter.set_font_flags(flags)
Parameters:

flags (Clutter.FontFlags) – The new flags

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.

New in version 1.0.

Deprecated since version 1.10: Use Clutter.Backend.set_font_options() and the #cairo_font_option_t API.

Clutter.set_motion_events_enabled(enable)
Parameters:

enable (bool) – True to enable per-actor motion events

Sets whether per-actor motion events should be enabled or not on all Clutter.Stage s managed by Clutter.

If enable is False the following events will not work:

New in version 0.6.

Deprecated since version 1.8: Use Clutter.Stage.set_motion_events_enabled() instead.

Clutter.set_windowing_backend(backend_type)
Parameters:

backend_type (str) – a comma separated list of windowing backends

Restricts Clutter to only use the specified backend or list of backends.

You can use one of the CLUTTER_WINDOWING_* symbols, e.g.

clutter_set_windowing_backend (CLUTTER_WINDOWING_X11);

Will force Clutter to use the X11 windowing and input backend, and terminate if the X11 backend could not be initialized successfully.

Since Clutter 1.26, you can also use a comma-separated list of windowing system backends to provide a fallback in case backends are not available or enabled, e.g.:

clutter_set_windowing_backend ("gdk,wayland,x11");

Will make Clutter test for the GDK, Wayland, and X11 backends in that order.

You can use the * special value to ask Clutter to use the internally defined list of backends. For instance:

clutter_set_windowing_backend ("x11,wayland,*");

Will make Clutter test the X11 and Wayland backends, and then fall back to the internal list of available backends.

This function must be called before the first API call to Clutter, including clutter_get_option_context()

New in version 1.16.

Clutter.shader_error_quark()
Return type:

int

Clutter.test_add_data_full(test_path, test_func, *test_data)
Parameters:

  • test_path (str) – unique path for identifying the test

  • test_func (GLib.TestDataFunc) – function containing the test

  • test_data (object or None) – data to pass to the test function

Adds a test unit to the Clutter test environment.

See also: GLib.test_add_data_func_full()

New in version 1.18.

Clutter.test_check_actor_at_point(stage, point, actor)
Parameters:
Returns:

True if the actor at the given coordinates matches

result:

actor at the coordinates

Return type:

(bool, result: Clutter.Actor or None)

Checks the given coordinates of the stage and compares the actor found there with the given actor.

New in version 1.18.

Clutter.test_check_color_at_point(stage, point, color)
Parameters:
Returns:

True if the colors match

result:

color at the given coordinates

Return type:

(bool, result: Clutter.Color)

Checks the color at the given coordinates on stage, and matches it with the red, green, and blue channels of color. The alpha component of color and result is ignored.

New in version 1.18.

Clutter.test_get_stage()
Returns:

the stage used for testing

Return type:

Clutter.Actor

Retrieves the Clutter.Stage used for testing.

New in version 1.18.

Clutter.test_init(argc, argv)
Parameters:

  • argc (int) –

  • argv (str) –

Clutter.test_run()
Returns:

the exit code for the test suite

Return type:

int

Runs the test suite using the units added by calling clutter_test_add().

The typical test suite is composed of a list of functions called by Clutter.test_run(), for instance:

static void unit_foo (void) { ... }

static void unit_bar (void) { ... }

static void unit_baz (void) { ... }

int
main (int argc, char *argv[])
{
  clutter_test_init (&argc, &argv);

  clutter_test_add ("/unit/foo", unit_foo);
  clutter_test_add ("/unit/bar", unit_bar);
  clutter_test_add ("/unit/baz", unit_baz);

  return clutter_test_run ();
}

New in version 1.18.

Clutter.texture_error_quark()
Return type:

int

Clutter.threads_add_frame_source(priority, fps, func, *data)
Parameters:
Returns:

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

Return type:

int

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

New in version 0.8.

Deprecated since version 1.6: There is no direct replacement for this API

Clutter.threads_add_idle(priority, func, *data)
Parameters:
Returns:

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

Return type:

int

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 GLib.idle_add(): it will call function while holding the Clutter lock. It is logically equivalent to the following implementation:

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:

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

New in version 0.4.

Clutter.threads_add_repaint_func(func, *data)
Parameters:

  • func (GLib.SourceFunc) – the function to be called within the paint cycle

  • data (object or None) – data to be passed to the function, or None

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

Return type:

int

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 Clutter.Texture. 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()

New in version 1.0.

Clutter.threads_add_repaint_func_full(flags, func, *data)
Parameters:
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().

Return type:

int

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 Clutter.Texture. 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.

New in version 1.10.

Clutter.threads_add_timeout(priority, interval, func, *data)
Parameters:
Returns:

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

Return type:

int

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

New in version 0.4.

Clutter.threads_enter()

Locks the Clutter thread lock.

New in version 0.4.

Deprecated since version 1.12: 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().

Clutter.threads_init()

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.

New in version 0.4.

Deprecated since version 1.10: This function does not do anything. Threading support is initialized when Clutter is initialized.

Clutter.threads_leave()

Unlocks the Clutter thread lock.

New in version 0.4.

Deprecated since version 1.12: 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().

Clutter.threads_remove_repaint_func(handle_id)
Parameters:

handle_id (int) – an unsigned integer greater than zero

Removes the repaint function with handle_id as its id

New in version 1.0.

Clutter.ungrab_keyboard()

Removes an existing grab of the keyboard.

New in version 0.6.

Clutter.ungrab_pointer()

Removes an existing grab of the pointer.

New in version 0.6.

Clutter.ungrab_pointer_for_device(id_)
Parameters:

id (int) – a device id

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

New in version 0.8.

Deprecated since version 1.10: Use Clutter.InputDevice.ungrab() instead.

Clutter.unicode_to_keysym(wc)
Parameters:

wc (int) – a ISO10646 encoded character

Returns:

the corresponding Clutter key symbol, if one exists. or, if there is no corresponding symbol, wc | 0x01000000

Return type:

int

Convert from a ISO10646 character to a key symbol.

New in version 1.10.

Clutter.units_from_cm(cm)
Parameters:

cm (float) – centimeters

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in centimeters inside units

New in version 1.2.

Clutter.units_from_em(em)
Parameters:

em (float) – em

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in em inside units, using the default font name as returned by Clutter.Backend.get_font_name()

New in version 1.0.

Clutter.units_from_em_for_font(font_name, em)
Parameters:

  • font_name (str or None) – the font name and size

  • em (float) – em

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in em inside units using font_name

New in version 1.0.

Clutter.units_from_mm(mm)
Parameters:

mm (float) – millimeters

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in millimiters inside units

New in version 1.0.

Clutter.units_from_pixels(px)
Parameters:

px (int) – pixels

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in pixels inside units

New in version 1.0.

Clutter.units_from_pt(pt)
Parameters:

pt (float) – typographic points

Returns:

a Clutter.Units

Return type:

units: Clutter.Units

Stores a value in typographic points inside units

New in version 1.0.

Clutter.units_from_string(str)
Parameters:

str (str) – the string to convert

Returns:

True if the string was successfully parsed, and False otherwise

units:

a Clutter.Units

Return type:

(bool, units: Clutter.Units)

Parses a value and updates units with it

A Clutter.Units expressed in string should match:

units: wsp* unit-value wsp* unit-name? wsp*
unit-value: number
unit-name: 'px' | 'pt' | 'mm' | 'em' | 'cm'
number: digit+
        | digit* sep digit+
sep: '.' | ','
digit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
wsp: (#0x20 | #0x9 | #0xA | #0xB | #0xC | #0xD)+

For instance, these are valid strings:

10 px
5.1 em
24 pt
12.6 mm
.3 cm

While these are not:

42 cats
omg!1!ponies

If no unit is specified, pixels are assumed.

New in version 1.0.

Clutter.util_next_p2(a)
Parameters:

a (int) – Value to get the next power

Returns:

The nearest power of two, greater or equal to a.

Return type:

int

Calculates the nearest power of two, greater than or equal to a.

Deprecated since version 1.2.

Clutter.value_dup_paint_node(value)
Parameters:

value (GObject.Value) – a GObject.Value initialized with %CLUTTER_TYPE_PAINT_NODE

Returns:

a pointer to the Clutter.PaintNode, with its reference count increased, or None

Return type:

Clutter.PaintNode

Retrieves a pointer to the Clutter.PaintNode contained inside the passed GObject.Value, and if not None it will increase the reference count.

New in version 1.10.

Clutter.value_get_color(value)
Parameters:

value (GObject.Value) – a GObject.Value initialized to #CLUTTER_TYPE_COLOR

Returns:

the color inside the passed GObject.Value

Return type:

Clutter.Color

Gets the Clutter.Color contained in value.

New in version 0.8.

Clutter.value_get_paint_node(value)
Parameters:

value (GObject.Value) – a GObject.Value initialized with %CLUTTER_TYPE_PAINT_NODE

Returns:

a pointer to a Clutter.PaintNode, or None

Return type:

Clutter.PaintNode

Retrieves a pointer to the Clutter.PaintNode contained inside the passed GObject.Value.

New in version 1.10.

Clutter.value_get_shader_float(value)
Parameters:

value (GObject.Value) – a GObject.Value

Returns:

the pointer to a list of floating point values. The returned value is owned by the GObject.Value and should never be modified or freed.

Return type:

[float]

Retrieves the list of floating point values stored inside the passed GObject.Value. value must have been initialized with %CLUTTER_TYPE_SHADER_FLOAT.

New in version 0.8.

Clutter.value_get_shader_int(value)
Parameters:

value (GObject.Value) – a GObject.Value

Returns:

the pointer to a list of integer values. The returned value is owned by the GObject.Value and should never be modified or freed.

Return type:

[int]

Retrieves the list of integer values stored inside the passed GObject.Value. value must have been initialized with %CLUTTER_TYPE_SHADER_INT.

New in version 0.8.

Clutter.value_get_shader_matrix(value)
Parameters:

value (GObject.Value) – a GObject.Value

Returns:

the pointer to a matrix of floating point values. The returned value is owned by the GObject.Value and should never be modified or freed.

Return type:

[float]

Retrieves a matrix of floating point values stored inside the passed GObject.Value. value must have been initialized with %CLUTTER_TYPE_SHADER_MATRIX.

New in version 0.8.

Clutter.value_get_units(value)
Parameters:

value (GObject.Value) – a GObject.Value initialized to %CLUTTER_TYPE_UNITS

Returns:

the units inside the passed GObject.Value

Return type:

Clutter.Units

Gets the Clutter.Units contained in value.

New in version 0.8.

Clutter.value_set_color(value, color)
Parameters:

Sets value to color.

New in version 0.8.

Clutter.value_set_paint_node(value, node)
Parameters:

Sets the contents of a GObject.Value initialized with %CLUTTER_TYPE_PAINT_NODE.

This function increased the reference count of node; if you do not wish to increase the reference count, use Clutter.value_take_paint_node() instead. The reference count will be released by GObject.Value.unset().

New in version 1.10.

Clutter.value_set_shader_float(value, floats)
Parameters:

Sets floats as the contents of value. The passed GObject.Value must have been initialized using %CLUTTER_TYPE_SHADER_FLOAT.

New in version 0.8.

Clutter.value_set_shader_int(value, ints)
Parameters:

Sets ints as the contents of value. The passed GObject.Value must have been initialized using %CLUTTER_TYPE_SHADER_INT.

New in version 0.8.

Clutter.value_set_shader_matrix(value, matrix)
Parameters:

Sets matrix as the contents of value. The passed GObject.Value must have been initialized using %CLUTTER_TYPE_SHADER_MATRIX.

New in version 0.8.

Clutter.value_set_units(value, units)
Parameters:

Sets value to units

New in version 0.8.

Clutter.value_take_paint_node(value, node)
Parameters:

Sets the contents of a GObject.Value initialized with %CLUTTER_TYPE_PAINT_NODE.

Unlike Clutter.value_set_paint_node(), this function will not take a reference on the passed node: instead, it will take ownership of the current reference count.

New in version 1.10.