Clutter.Stage¶

Subclasses:: None

Methods¶

Inherited:: Clutter.Group (4), Clutter.Actor (238), GObject.Object (37), Clutter.Animatable (5), Clutter.Container (17), Clutter.Scriptable (4)
Structs:: GObject.ObjectClass (5)

class	`get_default` ()
class	`new` ()
	`ensure_current` ()
	`ensure_redraw` ()
	`ensure_viewport` ()
	`event` (event)
	`get_accept_focus` ()
	`get_actor_at_pos` (pick_mode, x, y)
	`get_color` ()
	`get_fog` ()
	`get_fullscreen` ()
	`get_key_focus` ()
	`get_minimum_size` ()
	`get_motion_events_enabled` ()
	`get_no_clear_hint` ()
	`get_perspective` ()
	`get_redraw_clip_bounds` ()
	`get_throttle_motion_events` ()
	`get_title` ()
	`get_use_alpha` ()
	`get_use_fog` ()
	`get_user_resizable` ()
	`hide_cursor` ()
	`is_default` ()
	`queue_redraw` ()
	`read_pixels` (x, y, width, height)
	`set_accept_focus` (accept_focus)
	`set_color` (color)
	`set_fog` (fog)
	`set_fullscreen` (fullscreen)
	`set_key_focus` (actor)
	`set_minimum_size` (width, height)
	`set_motion_events_enabled` (enabled)
	`set_no_clear_hint` (no_clear)
	`set_perspective` (perspective)
	`set_throttle_motion_events` (throttle)
	`set_title` (title)
	`set_use_alpha` (use_alpha)
	`set_use_fog` (fog)
	`set_user_resizable` (resizable)
	`show_cursor` ()

Virtual Methods¶

Inherited:: Clutter.Actor (35), GObject.Object (7), Clutter.Animatable (5), Clutter.Container (13), Clutter.Scriptable (4)

	`do_activate` ()
	`do_deactivate` ()
	`do_delete_event` (event)
	`do_fullscreen` ()
	`do_unfullscreen` ()

Properties¶

Inherited:: Clutter.Actor (82)

Name	Type	Flags	Short Description
`accept-focus`	`bool`	r/w	Whether the stage should accept focus on show
`color`	`Clutter.Color`	d/r/w	The color of the stage `deprecated`
`cursor-visible`	`bool`	r/w	Whether the mouse pointer is visible on the main stage
`fog`	`Clutter.Fog`	d/r/w	Settings for the depth cueing `deprecated`
`fullscreen-set`	`bool`	r	Whether the main stage is fullscreen
`key-focus`	`Clutter.Actor`	r/w	The currently key focused actor
`no-clear-hint`	`bool`	r/w	Whether the stage should clear its contents
`offscreen`	`bool`	d/r/w	Whether the main stage should be rendered offscreen `deprecated`
`perspective`	`Clutter.Perspective`	r/w	Perspective projection parameters
`title`	`str`	r/w	Stage Title
`use-alpha`	`bool`	r/w	Whether to honour the alpha component of the stage color
`use-fog`	`bool`	d/r/w	Whether to enable depth cueing `deprecated`
`user-resizable`	`bool`	r/w	Whether the stage is able to be resized via user interaction

Signals¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Short Description
`activate`	The `::activate` signal is emitted when the stage receives key focus from the underlying window system.
`after-paint`	The `::after-paint` signal is emitted after the stage is painted, but before the results are displayed on the screen.
`deactivate`	The `::deactivate` signal is emitted when the stage loses key focus from the underlying window system.
`delete-event`	The `::delete-event` signal is emitted when the user closes a `Clutter.Stage` window using the window controls.
`fullscreen`	The `::fullscreen` signal is emitted when the stage is made fullscreen.
`unfullscreen`	The `::unfullscreen` signal is emitted when the stage leaves a fullscreen state.

Fields¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Type	Access	Description
parent_instance	`Clutter.Group`	r

Class Details¶

class Clutter.Stage(**kwargs)¶

Bases:: Clutter.Group
Abstract:: No
Structure:: Clutter.StageClass

The Clutter.Stage structure contains only private data and should be accessed using the provided API

New in version 0.2.

classmethod get_default()¶

Returns:: the main Clutter.Stage. You should never destroy or unref the returned actor.
Return type:: Clutter.Stage

Retrieves a Clutter.Stage singleton.

This function is not as useful as it sounds, and will most likely by deprecated in the future. Application code should only create a Clutter.Stage instance using Clutter.Stage.new(), and manage the lifetime of the stage manually.

The default stage singleton has a platform-specific behaviour: on platforms without the Clutter.FeatureFlags.STAGE_MULTIPLE feature flag set, the first Clutter.Stage instance will also be set to be the default stage instance, and this function will always return a pointer to it.

On platforms with the Clutter.FeatureFlags.STAGE_MULTIPLE feature flag set, the default stage will be created by the first call to this function, and every following call will return the same pointer to it.

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

classmethod new()¶

Returns:: a new stage, or None if the default backend does not support multiple stages. Use Clutter.Actor.destroy() to programmatically close the returned stage.
Return type:: Clutter.Actor

Creates a new, non-default stage. A non-default stage is a new top-level actor which can be used as another container. It works exactly like the default stage, but while Clutter.Stage.get_default() will always return the same instance, you will have to keep a pointer to any Clutter.Stage returned by Clutter.Stage.new().

The ability to support multiple stages depends on the current backend. Use Clutter.feature_available() and Clutter.FeatureFlags.STAGE_MULTIPLE to check at runtime whether a backend supports multiple stages.

New in version 0.8.

ensure_current()¶: This function essentially makes sure the right GL context is current for the passed stage. It is not intended to be used by applications.

New in version 0.8.

ensure_redraw()¶

Ensures that self is redrawn

This function should not be called by applications: it is used when embedding a Clutter.Stage into a toolkit with another windowing system, like GTK+.

New in version 1.0.

ensure_viewport()¶

Ensures that the GL viewport is updated with the current stage window size.

This function will queue a redraw of self.

This function should not be called by applications; it is used when embedding a Clutter.Stage into a toolkit with another windowing system, like GTK+.

New in version 1.0.

event(event)¶

Parameters:: event (Clutter.Event) – a Clutter.Event
Returns:: the return value from the signal emission
Return type:: bool

This function is used to emit an event on the main stage.

You should rarely need to use this function, except for synthetised events.

New in version 0.4.

get_accept_focus()¶

Returns:: True if the Clutter.Stage should accept focus, and False otherwise
Return type:: bool

Retrieves the value set with Clutter.Stage.set_accept_focus().

New in version 1.6.

get_actor_at_pos(pick_mode, x, y)¶

Parameters:

pick_mode (Clutter.PickMode) – how the scene graph should be painted
x (int) – X coordinate to check
y (int) – Y coordinate to check

Returns:

the actor at the specified coordinates, if any

Return type:

Clutter.Actor

Checks the scene at the coordinates x and y and returns a pointer to the Clutter.Actor at those coordinates.

By using pick_mode it is possible to control which actors will be painted and thus available.

get_color()¶

Returns:: return location for a Clutter.Color
Return type:: color: Clutter.Color

Retrieves the stage color.

Deprecated since version 1.10: Use Clutter.Actor.get_background_color() instead.

get_fog()¶

Returns:: return location for a Clutter.Fog structure
Return type:: fog: Clutter.Fog

Retrieves the current depth cueing settings from the stage.

New in version 0.6.

Deprecated since version 1.10: This function will always return the default values of Clutter.Fog

get_fullscreen()¶

Returns:: True if the stage is full screen
Return type:: bool

Retrieves whether the stage is full screen or not

New in version 1.0.

get_key_focus()¶

Returns:: the actor with key focus, or the stage
Return type:: Clutter.Actor

Retrieves the actor that is currently under key focus.

New in version 0.6.

get_minimum_size()¶

Returns:

width:: return location for the minimum width, in pixels, or None
height:: return location for the minimum height, in pixels, or None

Return type:

(width: int, height: int)

Retrieves the minimum size for a stage window as set using Clutter.Stage.set_minimum_size().

The returned size may not correspond to the actual minimum size and it is specific to the Clutter.Stage implementation inside the Clutter backend

New in version 1.2.

get_motion_events_enabled()¶

Returns:: True if the per-actor motion event delivery is enabled and False otherwise
Return type:: bool

Retrieves the value set using Clutter.Stage.set_motion_events_enabled().

New in version 1.8.

get_no_clear_hint()¶

Returns:: True if the stage should not clear itself on every paint cycle, and False otherwise
Return type:: bool

Retrieves the hint set with Clutter.Stage.set_no_clear_hint()

New in version 1.4.

get_perspective()¶

Returns:: return location for a Clutter.Perspective
Return type:: perspective: Clutter.Perspective

Retrieves the stage perspective.

get_redraw_clip_bounds()¶

Returns:: Return location for the clip bounds
Return type:: clip: cairo.RectangleInt

Gets the bounds of the current redraw for self in stage pixel coordinates. E.g., if only a single actor has queued a redraw then Clutter may redraw the stage with a clip so that it doesn’t have to paint every pixel in the stage. This function would then return the bounds of that clip. An application can use this information to avoid some extra work if it knows that some regions of the stage aren’t going to be painted. This should only be called while the stage is being painted. If there is no current redraw clip then this function will set clip to the full extents of the stage.

New in version 1.8.

get_throttle_motion_events()¶

Returns:: True if the motion events are being throttled, and False otherwise
Return type:: bool

Retrieves the value set with Clutter.Stage.set_throttle_motion_events()

New in version 1.0.

get_title()¶

Returns:: pointer to the title string for the stage. The returned string is owned by the actor and should not be modified or freed.
Return type:: str

Gets the stage title.

New in version 0.4.

get_use_alpha()¶

Returns:: True if the stage should honour the opacity and the alpha channel of the stage color
Return type:: bool

Retrieves the value set using Clutter.Stage.set_use_alpha()

New in version 1.2.

get_use_fog()¶

Returns:: True if the depth cueing effect is enabled
Return type:: bool

Gets whether the depth cueing effect is enabled on self.

New in version 0.6.

Deprecated since version 1.10: This function will always return False

get_user_resizable()¶

Returns:: True if the stage is resizable by the user.
Return type:: bool

Retrieves the value set with Clutter.Stage.set_user_resizable().

New in version 0.4.

hide_cursor()¶: Makes the cursor invisible on the stage window

New in version 0.4.

is_default()¶

Returns:: True if the passed stage is the default one
Return type:: bool

Checks if self is the default stage, or an instance created using Clutter.Stage.new() but internally using the same implementation.

New in version 0.8.

Deprecated since version 1.10: Track the stage pointer inside your application code, or use Clutter.Actor.get_stage() to retrieve the stage for a given actor.

queue_redraw()¶

Queues a redraw for the passed stage.

Applications should call Clutter.Actor.queue_redraw() and not this function.

New in version 0.8.

Deprecated since version 1.10: Use Clutter.Actor.queue_redraw() instead.

read_pixels(x, y, width, height)¶

Parameters:

x (int) – x coordinate of the first pixel that is read from stage
y (int) – y coordinate of the first pixel that is read from stage
width (int) – Width dimention of pixels to be read, or -1 for the entire stage width
height (int) – Height dimention of pixels to be read, or -1 for the entire stage height

Returns:

a pointer to newly allocated memory with the buffer or None if the read failed. Use GLib.free() on the returned data to release the resources it has allocated.

Return type:

bytes

Makes a screenshot of the stage in RGBA 8bit data, returns a linear buffer with width * 4 as rowstride.

The alpha data contained in the returned buffer is driver-dependent, and not guaranteed to hold any sensible value.

set_accept_focus(accept_focus)¶

Parameters:: accept_focus (bool) – True to accept focus on show

Sets whether the self should accept the key focus when shown.

This function should be called before showing self using Clutter.Actor.show().

New in version 1.6.

set_color(color)¶

Parameters:: color (Clutter.Color) – A Clutter.Color

Sets the stage color.

Deprecated since version 1.10: Use Clutter.Actor.set_background_color() instead.

set_fog(fog)¶

Parameters:: fog (Clutter.Fog) – a Clutter.Fog structure

Sets the fog (also known as “depth cueing”) settings for the self.

A Clutter.Stage will only use a linear fog progression, which depends solely on the distance from the viewer. The Cogl.set_fog() function in COGL exposes more of the underlying implementation, and allows changing the for progression function. It can be directly used by disabling the Clutter.Stage :use-fog property and connecting a signal handler to the Clutter.Actor ::paint signal on the self, like:

clutter_stage_set_use_fog (stage, FALSE);
g_signal_connect (stage, "paint", G_CALLBACK (on_stage_paint), NULL);

The paint signal handler will call Cogl.set_fog() with the desired settings:

static void
on_stage_paint (ClutterActor *actor)
{
  ClutterColor stage_color = { 0, };
  CoglColor fog_color = { 0, };

  // set the fog color to the stage background color
  clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color);
  cogl_color_init_from_4ub (&fog_color,
                            stage_color.red,
                            stage_color.green,
                            stage_color.blue,
                            stage_color.alpha);

  // enable fog //
  cogl_set_fog (&fog_color,
                COGL_FOG_MODE_EXPONENTIAL, // mode
                0.5,                       // density
                5.0, 30.0);                // z_near and z_far
}

The fogging functions only work correctly when the visible actors use unmultiplied alpha colors. By default Cogl will premultiply textures and Cogl.set_source_color() will premultiply colors, so unless you explicitly load your textures requesting an unmultiplied internal format and use Cogl.Material.set_color() you can only use fogging with fully opaque actors. Support for premultiplied colors will improve in the future when we can depend on fragment shaders.

New in version 0.6.

Deprecated since version 1.10: Fog settings are ignored.

set_fullscreen(fullscreen)¶

Parameters:: fullscreen (bool) – True to to set the stage fullscreen

Asks to place the stage window in the fullscreen or unfullscreen states.

( Note that you shouldn’t assume the window is definitely full screen afterward, because other entities (e.g. the user or window manager) could unfullscreen it again, and not all window managers honor requests to fullscreen windows.

If you want to receive notification of the fullscreen state you should either use the Clutter.Stage ::fullscreen and Clutter.Stage ::unfullscreen signals, or use the notify signal for the Clutter.Stage :fullscreen-set property

New in version 1.0.

set_key_focus(actor)¶

Parameters:: actor (Clutter.Actor or None) – the actor to set key focus to, or None

Sets the key focus on actor. An actor with key focus will receive all the key events. If actor is None, the stage will receive focus.

New in version 0.6.

set_minimum_size(width, height)¶

Parameters:

width (int) – width, in pixels
height (int) – height, in pixels

Sets the minimum size for a stage window, if the default backend uses Clutter.Stage inside a window

This is a convenience function, and it is equivalent to setting the Clutter.Actor :min-width and Clutter.Actor :min-height on self

If the current size of self is smaller than the minimum size, the self will be resized to the new width and height

This function has no effect if self is fullscreen

New in version 1.2.

set_motion_events_enabled(enabled)¶

Parameters:: enabled (bool) – True to enable the motion events delivery, and False otherwise

Sets whether per-actor motion events (and relative crossing events) should be disabled or not.

The default is True.

If enable is False the following signals will not be emitted by the actors children of self:

The events will still be delivered to the Clutter.Stage.

The main side effect of this function is that disabling the motion events will disable picking to detect the Clutter.Actor underneath the pointer for each motion event. This is useful, for instance, when dragging a Clutter.Actor across the self: the actor underneath the pointer is not going to change, so it’s meaningless to perform a pick.

New in version 1.8.

set_no_clear_hint(no_clear)¶

Parameters:: no_clear (bool) – True if the self should not clear itself on every repaint cycle

Sets whether the self should clear itself at the beginning of each paint cycle or not.

Clearing the Clutter.Stage can be a costly operation, especially if the stage is always covered - for instance, in a full-screen video player or in a game with a background texture.

This setting is a hint; Clutter might discard this hint depending on its internal state.

If parts of the stage are visible and you disable clearing you might end up with visual artifacts while painting the contents of the stage.

New in version 1.4.

set_perspective(perspective)¶

Parameters:: perspective (Clutter.Perspective) – A Clutter.Perspective

Sets the stage perspective. Using this function is not recommended because it will disable Clutter’s attempts to generate an appropriate perspective based on the size of the stage.

set_throttle_motion_events(throttle)¶

Parameters:: throttle (bool) – True to throttle motion events

Sets whether motion events received between redraws should be throttled or not. If motion events are throttled, those events received by the windowing system between redraws will be compressed so that only the last event will be propagated to the self and its actors.

This function should only be used if you want to have all the motion events delivered to your application code.

New in version 1.0.

set_title(title)¶

Parameters:: title (str) – A utf8 string for the stage windows title.

Sets the stage title.

New in version 0.4.

set_use_alpha(use_alpha)¶

Parameters:: use_alpha (bool) – whether the stage should honour the opacity or the alpha channel of the stage color

Sets whether the self should honour the Clutter.Actor :opacity and the alpha channel of the Clutter.Stage :color

New in version 1.2.

set_use_fog(fog)¶

Parameters:: fog (bool) – True for enabling the depth cueing effect

Sets whether the depth cueing effect on the stage should be enabled or not.

Depth cueing is a 3D effect that makes actors farther away from the viewing point less opaque, by fading them with the stage color.

The parameters of the GL fog used can be changed using the Clutter.Stage.set_fog() function.

New in version 0.6.

Deprecated since version 1.10: Calling this function produces no visible effect

set_user_resizable(resizable)¶

Parameters:: resizable (bool) – whether the stage should be user resizable.

Sets if the stage is resizable by user interaction (e.g. via window manager controls)

New in version 0.4.

show_cursor()¶: Shows the cursor on the stage window

do_activate() virtual¶

do_deactivate() virtual¶

do_delete_event(event) virtual¶

Parameters:: event (Clutter.Event) –
Return type:: bool

do_fullscreen() virtual¶

do_unfullscreen() virtual¶

Signal Details¶

Clutter.Stage.signals.activate(stage)¶

Signal Name:: activate
Flags:: RUN_LAST
Parameters:: stage (Clutter.Stage) – The object which received the signal

The ::activate signal is emitted when the stage receives key focus from the underlying window system.

New in version 0.6.

Clutter.Stage.signals.after_paint(stage)¶

Signal Name:: after-paint
Flags:: RUN_LAST
Parameters:: stage (Clutter.Stage) – The object which received the signal

The ::after-paint signal is emitted after the stage is painted, but before the results are displayed on the screen.

New in version 1.20.

Clutter.Stage.signals.deactivate(stage)¶

Signal Name:: deactivate
Flags:: RUN_LAST
Parameters:: stage (Clutter.Stage) – The object which received the signal

The ::deactivate signal is emitted when the stage loses key focus from the underlying window system.

New in version 0.6.

Clutter.Stage.signals.delete_event(stage, event)¶

Signal Name:

delete-event

Flags:

RUN_LAST

Parameters:

stage (Clutter.Stage) – The object which received the signal
event (Clutter.Event) – a Clutter.Event of type Clutter.EventType.DELETE

Return type:

bool

The ::delete-event signal is emitted when the user closes a Clutter.Stage window using the window controls.

Clutter by default will call Clutter.main_quit() if stage is the default stage, and Clutter.Actor.destroy() for any other stage.

It is possible to override the default behaviour by connecting a new handler and returning True there.

This signal is emitted only on Clutter backends that embed Clutter.Stage in native windows. It is not emitted for backends that use a static frame buffer.

New in version 1.2.

Clutter.Stage.signals.fullscreen(stage)¶

Signal Name:: fullscreen
Flags:: RUN_FIRST
Parameters:: stage (Clutter.Stage) – The object which received the signal

The ::fullscreen signal is emitted when the stage is made fullscreen.

New in version 0.6.

Clutter.Stage.signals.unfullscreen(stage)¶

Signal Name:: unfullscreen
Flags:: RUN_LAST
Parameters:: stage (Clutter.Stage) – The object which received the signal

The ::unfullscreen signal is emitted when the stage leaves a fullscreen state.

New in version 0.6.

Property Details¶

Clutter.Stage.props.accept_focus¶

Name:: accept-focus
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

Whether the Clutter.Stage should accept key focus when shown.

New in version 1.6.

Clutter.Stage.props.color¶

Name:: color
Type:: Clutter.Color
Default Value:: <Color structure at 0x000000000000 (ClutterColor at 0x0000000)>
Flags:: DEPRECATED, READABLE, WRITABLE

The background color of the main stage.

Deprecated since version 1.10: Use the Clutter.Actor :background-color property of Clutter.Actor instead.

Clutter.Stage.props.cursor_visible¶

Name:: cursor-visible
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

Whether the mouse pointer should be visible

Clutter.Stage.props.fog¶

Name:: fog
Type:: Clutter.Fog
Default Value:: None
Flags:: DEPRECATED, READABLE, WRITABLE

The settings for the GL “fog”, used only if Clutter.Stage :use-fog is set to True

New in version 1.0.

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

Clutter.Stage.props.fullscreen_set¶

Name:: fullscreen-set
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the main stage is fullscreen

Clutter.Stage.props.key_focus¶

Name:: key-focus
Type:: Clutter.Actor
Default Value:: None
Flags:: READABLE, WRITABLE

The Clutter.Actor that will receive key events from the underlying windowing system.

If None, the Clutter.Stage will receive the events.

New in version 1.2.

Clutter.Stage.props.no_clear_hint¶

Name:: no-clear-hint
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Whether or not the Clutter.Stage should clear its contents before each paint cycle.

See Clutter.Stage.set_no_clear_hint() for further information.

New in version 1.4.

Clutter.Stage.props.offscreen¶

Name:: offscreen
Type:: bool
Default Value:: False
Flags:: DEPRECATED, READABLE, WRITABLE

Whether the stage should be rendered in an offscreen buffer.

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

Clutter.Stage.props.perspective¶

Name:: perspective
Type:: Clutter.Perspective
Default Value:: None
Flags:: READABLE, WRITABLE

The parameters used for the perspective projection from 3D coordinates to 2D

New in version 0.8.

Clutter.Stage.props.title¶

Name:: title
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The stage’s title - usually displayed in stage windows title decorations.

New in version 0.4.

Clutter.Stage.props.use_alpha¶

Name:: use-alpha
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Whether the Clutter.Stage should honour the alpha component of the Clutter.Stage :color property when painting. If Clutter is run under a compositing manager this will result in the stage being blended with the underlying window(s)

New in version 1.2.

Clutter.Stage.props.use_fog¶

Name:: use-fog
Type:: bool
Default Value:: False
Flags:: DEPRECATED, READABLE, WRITABLE

Whether the stage should use a linear GL “fog” in creating the depth-cueing effect, to enhance the perception of depth by fading actors farther from the viewpoint.

New in version 0.6.

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

Clutter.Stage.props.user_resizable¶

Name:: user-resizable
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Whether the stage is resizable via user interaction.

New in version 0.4.