# Clutter::Stage Class Reference

This is a top level 'window' on which child actors are placed and manipulated. More...

Inherits Clutter::Group.

Collaboration diagram for Clutter::Stage:
[legend]

List of all members.

## Public Member Functions

virtual | ~Stage ()
ClutterStage* | gobj ()
| Provides access to the underlying C GObject.
const ClutterStage* | gobj () const
| Provides access to the underlying C GObject.
ClutterStage* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | set_color (const Color& color)
| Sets the stage color.
Color | get_color () const
| Retrieves the stage color.
void | set_perspective (const Perspective& prespective)
| Sets the stage perspective.
void | get_perspective (Perspective& prespective)
| Retrieves the stage perspective.
void | set_fullscreen (bool fullscreen=true)
| Asks to place the stage window in the fullscreen or unfullscreen states.
bool | get_fullscreen () const
| Retrieves whether the stage is full screen or not.
void | show_cursor ()
| Shows the cursor on the stage window.
void | hide_cursor ()
| Makes the cursor invisible on the stage window.
Glib::ustring | get_title () const
| Gets the stage title.
void | set_title (const Glib::ustring& title)
| Sets the stage title.
void | set_user_resizable (bool value)
| Sets if the stage is resizable by user interaction (e.g. via window manager controls).
bool | get_user_resizable () const
| Retrieves the value set with set_user_resizable().
Glib::RefPtr< Actor > | get_actor_at_pos (PickMode pick_mode, int x, int y)
| Checks the scene at the coordinates x and y and returns a pointer to the Clutter::Actor at those coordinates.
Glib::RefPtr< const Actor > | get_actor_at_pos (PickMode pick_mode, int x, int y) const
| Checks the scene at the coordinates x and y and returns a pointer to the Clutter::Actor at those coordinates.
Glib::RefPtr< Actor > | get_key_focus ()
| Retrieves the actor that is currently under key focus.
Glib::RefPtr< const Actor > | get_key_focus () const
| Retrieves the actor that is currently under key focus.
void | set_key_focus (const Glib::RefPtr< Actor >& actor)
| Sets the key focus on actor.
void | set_key_focus ()
guchar* | read_pixels (int x, int y, int width, int height) const
| Makes a screenshot of the stage in RGBA 8bit data, returns a linear buffer with width * 4 as rowstride.
bool | get_use_fog () const
| Gets whether the depth cueing effect is enabled on stage.
void | set_use_fog (bool fog=true)
| Sets whether the depth cueing effect on the stage should be enabled or not.
void | set_fog (const Fog& fog)
| Sets the fog (also known as "depth cueing") settings for the stage.
void | get_fog (Fog& fog) const
| Retrieves the current depth cueing settings from the stage.
void | stage_event (Event* event)
| This function is used to emit an event on the main stage.
bool | is_default () const
| Checks if stage is the default stage, or an instance created using new() but internally using the same implementation.
void | ensure_current ()
| This function essentially makes sure the right GL context is current for the passed stage.
void | ensure_viewport ()
| Ensures that the GL viewport is updated with the current stage window size.
void | ensure_redraw ()
| Ensures that stage is redrawn.
void | set_throttle_motion_events (bool throttle=true)
| Sets whether motion events received between redraws should be throttled or not.
bool | get_throttle_motion_events () const
| Retrieves the value set with set_throttle_motion_events().
void | set_use_alpha (bool use_alpha=true)
| Sets whether the stage should honour the Clutter::Actor:opacity and the alpha channel of the Clutter::Stage:color.
bool | get_use_alpha () const
| Retrieves the value set using set_use_alpha().
void | set_minimum_size (guint width, guint height)
| Sets the minimum size for a stage window, if the default backend uses Clutter::Stage inside a window.
void | get_minimum_size (guint& width, guint& height)
| Retrieves the minimum size for a stage window as set using set_minimum_size().
Glib::SignalProxy0< void > | signal_fullscreen ()
Glib::SignalProxy0< void > | signal_unfullscreen ()
Glib::SignalProxy0< void > | signal_activate ()
Glib::SignalProxy0< void > | signal_deactivate ()
Glib::SignalProxy1< bool, ClutterEvent* > | signal_delete_event ()
Glib::PropertyProxy< Color > | property_color ()
| The color of the stage.
Glib::PropertyProxy_ReadOnly < Color > | property_color () const
| The color of the stage.
Glib::PropertyProxy< bool > | property_cursor_visible ()
| Whether the mouse pointer is visible on the main stage.
Glib::PropertyProxy_ReadOnly < bool > | property_cursor_visible () const
| Whether the mouse pointer is visible on the main stage.
Glib::PropertyProxy< bool > | property_offscreen ()
| Whether the main stage should be rendered offscreen.
Glib::PropertyProxy_ReadOnly < bool > | property_offscreen () const
| Whether the main stage should be rendered offscreen.
Glib::PropertyProxy < Glib::ustring > | property_title ()
| Stage Title.
Glib::PropertyProxy_ReadOnly < Glib::ustring > | property_title () const
| Stage Title.
Glib::PropertyProxy< bool > | property_use_fog ()
| Whether to enable depth cueing.
Glib::PropertyProxy_ReadOnly < bool > | property_use_fog () const
| Whether to enable depth cueing.
Glib::PropertyProxy< bool > | property_user_resizable ()
| Whether the stage is able to be resized via user interaction.
Glib::PropertyProxy_ReadOnly < bool > | property_user_resizable () const
| Whether the stage is able to be resized via user interaction.

## Static Public Member Functions

static Glib::RefPtr< Stage > | get_default ()
| Returns the main stage.

## Protected Member Functions

| Stage ()
virtual void | on_fullscreen ()
virtual void | on_unfullscreen ()
virtual void | on_activate ()
virtual void | on_deactivate ()
virtual bool | on_delete_event (ClutterEvent* event)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Clutter::Stage > | wrap (ClutterStage* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

This is a top level 'window' on which child actors are placed and manipulated.

Clutter creates a default stage upon initialization, which can be retrieved using Stage::get_default(). Clutter always provides the default stage, unless the backend is unable to create one. The stage returned by Stage::get_default() is guaranteed to always be the same.

Backends might provide support for multiple stages. The support for this feature can be checked at run-time using the clutter_feature_available() function and the CLUTTER_FEATURE_STAGE_MULTIPLE flag. If the backend used supports multiple stages, new Clutter::Stage instances can be created.

Clutter::Stage is a proxy actor, wrapping the backend-specific implementation of the windowing system. It is possible to subclass ClutterStage, as long as every overridden virtual function calls the implementation in the base class.

## Constructor & Destructor Documentation

virtual Clutter::Stage::~Stage | ( |  | ) | `[virtual]`

Clutter::Stage::Stage | ( |  | ) | `[protected]`

## Member Function Documentation

void Clutter::Stage::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.

Since cluttermm 0.8:

void Clutter::Stage::ensure_redraw | ( |  | ) |

Ensures that stage 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+.

Since cluttermm 1.0:

void Clutter::Stage::ensure_viewport | ( |  | ) |

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

This function will queue a redraw of stage.

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

Since cluttermm 1.0:

Glib::RefPtr<const Actor> Clutter::Stage::get_actor_at_pos | ( | PickMode | pick_mode,
|  | int | x,
|  | int | y |
| ) |  |  | const

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.

Parameters:

  | pick_mode | How the scene graph should be painted.
  | x | X coordinate to check.
  | y | Y coordinate to check.

Returns:
  The actor at the specified coordinates, if any.

Glib::RefPtr<Actor> Clutter::Stage::get_actor_at_pos | ( | PickMode | pick_mode,
|  | int | x,
|  | int | y |
| ) |  |  |

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.

Parameters:

  | pick_mode | How the scene graph should be painted.
  | x | X coordinate to check.
  | y | Y coordinate to check.

Returns:
  The actor at the specified coordinates, if any.

Color Clutter::Stage::get_color | ( |  | ) | const

Retrieves the stage color.

Parameters:

  | color | Return location for a Clutter::Color.

static Glib::RefPtr<Stage> Clutter::Stage::get_default | ( |  | ) | `[static]`

Returns the main stage.

The default Clutter::Stage is a singleton, so the stage will be created the first time this function is called (typically, inside clutter_init()); all the subsequent calls to get_default() will return the same instance.

Clutter guarantess the existence of the default stage.

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

void Clutter::Stage::get_fog | ( | Fog& | fog | ) | const

Retrieves the current depth cueing settings from the stage.

Since cluttermm 0.6:

Parameters:

  | fog | Return location for a Clutter::Fog structure.

bool Clutter::Stage::get_fullscreen | ( |  | ) | const

Retrieves whether the stage is full screen or not.

Since cluttermm 1.0:

Returns:
  `true` if the stage is full screen.

Glib::RefPtr<const Actor> Clutter::Stage::get_key_focus | ( |  | ) | const

Retrieves the actor that is currently under key focus.

Since cluttermm 0.6:

Returns:
  The actor with key focus, or the stage.

Glib::RefPtr<Actor> Clutter::Stage::get_key_focus | ( |  | ) |

Retrieves the actor that is currently under key focus.

Since cluttermm 0.6:

Returns:
  The actor with key focus, or the stage.

void Clutter::Stage::get_minimum_size | ( | guint & | width,
|  | guint & | height |
| ) |  |  |

Retrieves the minimum size for a stage window as set using 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

Since cluttermm 1.2:

Parameters:

  | width | Return location for the minimum width, in pixels, or `0`.
  | height | Return location for the minimum height, in pixels, or `0`.

void Clutter::Stage::get_perspective | ( | Perspective& | prespective | ) |

Retrieves the stage perspective.

Parameters:

  | perspective | Return location for a Clutter::Perspective.

bool Clutter::Stage::get_throttle_motion_events | ( |  | ) | const

Retrieves the value set with set_throttle_motion_events().

Since cluttermm 1.0:

Returns:
  `true` if the motion events are being throttled, and `false` otherwise.

Glib::ustring Clutter::Stage::get_title | ( |  | ) | const

Gets the stage title.

Since cluttermm 0.4:

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

bool Clutter::Stage::get_use_alpha | ( |  | ) | const

Retrieves the value set using set_use_alpha().

Since cluttermm 1.2:

Returns:
  `true` if the stage should honour the opacity and the alpha channel of the stage color.

bool Clutter::Stage::get_use_fog | ( |  | ) | const

Gets whether the depth cueing effect is enabled on stage.

Since cluttermm 0.6:

Returns:
  `true` if the the depth cueing effect is enabled.

bool Clutter::Stage::get_user_resizable | ( |  | ) | const

Retrieves the value set with set_user_resizable().

Since cluttermm 0.4:

Returns:
  `true` if the stage is resizable by the user.

const ClutterStage* Clutter::Stage::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Clutter::Group.

ClutterStage* Clutter::Stage::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Clutter::Group.

ClutterStage* Clutter::Stage::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Clutter::Group.

void Clutter::Stage::hide_cursor | ( |  | ) |

Makes the cursor invisible on the stage window.

Since cluttermm 0.4:

bool Clutter::Stage::is_default | ( |  | ) | const

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

Since cluttermm 0.8:

Returns:
  `true` if the passed stage is the default one.

virtual void Clutter::Stage::on_activate | ( |  | ) | `[protected, virtual]`

virtual void Clutter::Stage::on_deactivate | ( |  | ) | `[protected, virtual]`

virtual bool Clutter::Stage::on_delete_event | ( | ClutterEvent * | event | ) | `[protected, virtual]`

virtual void Clutter::Stage::on_fullscreen | ( |  | ) | `[protected, virtual]`

virtual void Clutter::Stage::on_unfullscreen | ( |  | ) | `[protected, virtual]`

Glib::PropertyProxy_ReadOnly<Color> Clutter::Stage::property_color | ( |  | ) | const

The color of the stage.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<Color> Clutter::Stage::property_color | ( |  | ) |

The color of the stage.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Stage::property_cursor_visible | ( |  | ) | const

Whether the mouse pointer is visible on the main stage.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Stage::property_cursor_visible | ( |  | ) |

Whether the mouse pointer is visible on the main stage.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Stage::property_offscreen | ( |  | ) | const

Whether the main stage should be rendered offscreen.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Stage::property_offscreen | ( |  | ) |

Whether the main stage should be rendered offscreen.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<Glib::ustring> Clutter::Stage::property_title | ( |  | ) | const

Stage Title.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<Glib::ustring> Clutter::Stage::property_title | ( |  | ) |

Stage Title.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Stage::property_use_fog | ( |  | ) | const

Whether to enable depth cueing.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Stage::property_use_fog | ( |  | ) |

Whether to enable depth cueing.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Stage::property_user_resizable | ( |  | ) | const

Whether the stage is able to be resized via user interaction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Stage::property_user_resizable | ( |  | ) |

Whether the stage is able to be resized via user interaction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

guchar* Clutter::Stage::read_pixels | ( | int | x,
|  | int | y,
|  | int | width,
|  | int | height |
| ) |  |  | const

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.

Parameters:

  | x | X coordinate of the first pixel that is read from stage.
  | y | Y coordinate of the first pixel that is read from stage.
  | width | Width dimention of pixels to be read, or -1 for the entire stage width.
  | height | 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 `0` if the read failed. Use Glib::free() on the returned data to release the resources it has allocated.

void Clutter::Stage::set_color | ( | const Color& | color | ) |

Sets the stage color.

Parameters:

  | color | A Clutter::Color.

void Clutter::Stage::set_fog | ( | const Fog& | fog | ) |

Sets the fog (also known as "depth cueing") settings for the stage.

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 stage, like:

|[ clutter_stage_set_use_fog (stage, `false`); g_signal_connect (stage, "paint", G_CALLBACK (on_stage_paint), `0`); ]|

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_set_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 * / } ]|

Note:
  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.

We can look to improve this in the future when we can depend on fragment shaders.

Since cluttermm 0.6:

Parameters:

  | fog | A Clutter::Fog structure.

void Clutter::Stage::set_fullscreen | ( | bool | fullscreen = `true` | ) |

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

Since cluttermm 1.0:

Parameters:

  | fullscreen | `true` to to set the stage fullscreen.

void Clutter::Stage::set_key_focus | ( |  | ) |

void Clutter::Stage::set_key_focus | ( | const Glib::RefPtr< Actor >& | actor | ) |

Sets the key focus on actor.

An actor with key focus will receive all the key events. If actor is `0`, the stage will receive focus.

Since cluttermm 0.6:

Parameters:

  | actor | The actor to set key focus to, or `0`.

void Clutter::Stage::set_minimum_size | ( | guint | width,
|  | guint | height |
| ) |  |  |

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 stage

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

This function has no effect if stage is fullscreen

Since cluttermm 1.2:

Parameters:

  | width | Width, in pixels.
  | height | Height, in pixels.

void Clutter::Stage::set_perspective | ( | const Perspective& | prespective | ) |

Sets the stage perspective.

Parameters:

  | perspective | A Clutter::Perspective.

void Clutter::Stage::set_throttle_motion_events | ( | bool | throttle = `true` | ) |

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 stage and its actors.

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

Since cluttermm 1.0:

Parameters:

  | throttle | `true` to throttle motion events.

void Clutter::Stage::set_title | ( | const Glib::ustring & | title | ) |

Sets the stage title.

Since cluttermm 0.4:

Parameters:

  | title | A utf8 string for the stage windows title.

void Clutter::Stage::set_use_alpha | ( | bool | use_alpha = `true` | ) |

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

Since cluttermm 1.2:

Parameters:

  | use_alpha | Whether the stage should honour the opacity or the alpha channel of the stage color.

void Clutter::Stage::set_use_fog | ( | bool | fog = `true` | ) |

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

Since cluttermm 0.6:

Parameters:

  | fog | `true` for enabling the depth cueing effect.

void Clutter::Stage::set_user_resizable | ( | bool | value | ) |

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

Since cluttermm 0.4:

Parameters:

  | resizable | Whether the stage should be user resizable.

void Clutter::Stage::show_cursor | ( |  | ) |

Shows the cursor on the stage window.

Glib::SignalProxy0< void > Clutter::Stage::signal_activate | ( |  | ) |

Prototype:
  `void on_my_activate()`

Glib::SignalProxy0< void > Clutter::Stage::signal_deactivate | ( |  | ) |

Prototype:
  `void on_my_deactivate()`

Glib::SignalProxy1< bool,ClutterEvent * > Clutter::Stage::signal_delete_event | ( |  | ) |

Prototype:
  `bool on_my_delete_event(ClutterEvent * event)`

Glib::SignalProxy0< void > Clutter::Stage::signal_fullscreen | ( |  | ) |

Prototype:
  `void on_my_fullscreen()`

Glib::SignalProxy0< void > Clutter::Stage::signal_unfullscreen | ( |  | ) |

Prototype:
  `void on_my_unfullscreen()`

void Clutter::Stage::stage_event | ( | Event* | event | ) |

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

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

Since cluttermm 0.4:

Parameters:

  | event | A Clutter::Event.

Returns:
  The return value from the signal emission.

## Friends And Related Function Documentation

Glib::RefPtr< Clutter::Stage > wrap | ( | ClutterStage * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- cluttermm/stage.h