gtkmm: Gdk::Surface Class Reference

gtkmm 4.23.2

Public Member Functions | Static Public Member Functions | Related Symbols | List of all members
Gdk::Surface Class Reference

Onscreen display areas in the target window system. More...

`#include <gdkmm/surface.h>`

Inheritance diagram for Gdk::Surface:
[legend]

## Public Member Functions
| Surface (Surface && src) noexcept
Surface & | operator= (Surface && src) noexcept
| ~Surface () noexcept override
GdkSurface * | gobj ()
| Provides access to the underlying C GObject.
const GdkSurface * | gobj () const
| Provides access to the underlying C GObject.
GdkSurface * | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr< Display > | get_display ()
| Gets the Gdk::Display associated with a Gdk::Surface.
Glib::RefPtr< const Display > | get_display () const
| Gets the Gdk::Display associated with a Gdk::Surface.
void | hide ()
| Hide the surface.
void | set_input_region (const ::Cairo::RefPtr< ::Cairo::Region > & region)
| Apply the region to the surface for the purpose of event handling.
bool | get_mapped () const
| Checks whether the surface has been mapped.
void | set_cursor (const Glib::RefPtr< Cursor > & cursor)
| Sets the default mouse pointer for a Gdk::Surface.
void | set_cursor ()
| Use the parent surface's cursor.
void | set_device_cursor (const Glib::RefPtr< Device > & device, const Glib::RefPtr< Cursor > & cursor)
| Sets a specific Gdk::Cursor for a given device when it gets inside surface.
Glib::RefPtr< Cursor > | get_device_cursor (const Glib::RefPtr< Device > & device)
| Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface.
Glib::RefPtr< const Cursor > | get_device_cursor (const Glib::RefPtr< const Device > & device) const
| Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface.
Glib::RefPtr< Cursor > | get_cursor ()
| Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface.
Glib::RefPtr< const Cursor > | get_cursor () const
| Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface.
int | get_width () const
| Returns the width of the given surface.
int | get_height () const
| Returns the height of the given surface.
bool | translate_coordinates (const Glib::RefPtr< const Surface > & to, double & x, double & y) const
| Translates coordinates between two surfaces.
int | get_scale_factor () const
| Returns the internal scale factor that maps from surface coordinates to the actual device pixels.
double | get_scale () const
| Returns the internal scale that maps from surface coordinates to the actual device pixels.
bool | get_device_position (const Glib::RefPtr< const Device > & device, double & x, double & y, ModifierType & mask) const
| Obtains the current device position and modifier state.
::Cairo::RefPtr< ::Cairo::Surface > | create_similar_surface (::Cairo::Content content, int width, int height)
| Create a new Cairo surface that is as compatible as possible with the given surface.
void | beep ()
| Emits a short beep associated to surface.
Glib::RefPtr< Drag > | drag_begin_from_point (const Glib::RefPtr< Device > & device, const Glib::RefPtr< ContentProvider > & content, DragAction actions, double dx, double dy)
| Starts a drag and creates a new drag context for it.
void | queue_render ()
| Forces a signal_render() signal emission for surface to be scheduled.
void | request_layout ()
| Request a layout phase from the surface's frame clock.
Glib::RefPtr< FrameClock > | get_frame_clock ()
| Gets the frame clock for the surface.
Glib::RefPtr< const FrameClock > | get_frame_clock () const
| Gets the frame clock for the surface.
void | set_opaque_region (const ::Cairo::RefPtr< const ::Cairo::Region > & region)
| Marks a region of the Gdk::Surface as opaque.
Glib::RefPtr< Gdk::GLContext > | create_gl_context ()
| Creates a new GLContext matching the framebuffer format to the visual of the Surface.
Glib::RefPtr< Gdk::CairoContext > | create_cairo_context ()
| Creates a new Gdk::CairoContext for rendering on surface.
Glib::SignalProxy< void(int, int)> | signal_layout ()
Glib::SignalProxy< bool(const ::Cairo::RefPtr< const ::Cairo::Region > &)> | signal_render ()
Glib::SignalProxy< bool(const Glib::RefPtr< const Event > &)> | signal_event ()
Glib::SignalProxy< void(const Glib::RefPtr< Monitor > &)> | signal_enter_monitor ()
Glib::SignalProxy< void(const Glib::RefPtr< Monitor > &)> | signal_leave_monitor ()
Glib::PropertyProxy< Glib::RefPtr< Cursor > > | property_cursor ()
| The mouse pointer for the Gdk::Surface.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > | property_cursor () const
| The mouse pointer for the Gdk::Surface.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > | property_display () const
| The Gdk::Display connection of the surface.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< FrameClock > > | property_frame_clock () const
| The Gdk::FrameClock of the surface.
Glib::PropertyProxy_ReadOnly< bool > | property_mapped () const
| Whether the surface is mapped.
Glib::PropertyProxy_ReadOnly< int > | property_width () const
| The width of the surface in pixels.
Glib::PropertyProxy_ReadOnly< int > | property_height () const
| The height of the surface, in pixels.
Glib::PropertyProxy_ReadOnly< int > | property_scale_factor () const
| The scale factor of the surface.
Glib::PropertyProxy_ReadOnly< double > | property_scale () const
| The scale of the surface.
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data_with_c_callback (const Quark &key, void *data, GDestroyNotify notify)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src) noexcept
| ~trackable ()
void | add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src) noexcept
void | remove_destroy_notify_callback (notifiable *data) const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system.
static Glib::RefPtr< Surface > | create_toplevel (const Glib::RefPtr< Display > & display)
| Creates a new toplevel surface.
static Glib::RefPtr< Surface > | create_popup (const Glib::RefPtr< Surface > & parent, bool autohide)
| Create a new popup surface.

## Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gdk::Surface > | wrap (GdkSurface * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify
Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify | func_destroy_notify
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Detailed Description

Onscreen display areas in the target window system.

A Gdk::Surface is a (usually) rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as Gtk::Window or Gtk::Dialog in GTK.

The surfaces you see in practice are either Gdk::Toplevel or Gdk::Popup, and those interfaces provide much of the required API to interact with these surfaces. Other, more specialized surface types exist, but you will rarely interact with them directly.

See also
  Gdk::Toplevel, Gdk::Popup

## Constructor & Destructor Documentation

## ◆ Surface()

Gdk::Surface::Surface | ( | Surface && | src | ) |
| noexcept

## ◆ ~Surface()

Gdk::Surface::~Surface | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ beep()

void Gdk::Surface::beep | ( |  | ) |

Emits a short beep associated to surface.

If the display of surface does not support per-surface beeps, emits a short beep on the display just as Gdk::Display::beep().

## ◆ create_cairo_context()

Glib::RefPtr< Gdk::CairoContext > Gdk::Surface::create_cairo_context | ( |  | ) |

Creates a new Gdk::CairoContext for rendering on surface.

Deprecated: 4.18: Drawing content with Cairo should be done via Cairo rendernodes, not by using the Cairo renderer.

Deprecated
  4.18: Drawing content with Cairo should be done via Cairo rendernodes, not by using the Cairo renderer.

Returns
  The newly created Gdk::CairoContext.

## ◆ create_gl_context()

Glib::RefPtr< Gdk::GLContext > Gdk::Surface::create_gl_context | ( |  | ) |

Creates a new GLContext matching the framebuffer format to the visual of the Surface.

The context is disconnected from any particular surface.

If the creation of the GLContext failed an error will be thrown.

Before using the returned GLContext, you will need to call GLContext::make_current() or GLContext::realize().

Since gtkmm 3.18

Returns
  GLContext The newly created context.

Exceptions

  GLError | On missing GL implementation or extension required for context creation.

## ◆ create_popup()

Glib::RefPtr< Surface > Gdk::Surface::create_popup | ( | const Glib::RefPtr< Surface > & | parent,
|  | bool | autohide )
| static

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using Gdk::Popup::present().

The created surface is usually a subclass of Gdk::Surface that implements the Gdk::Popup interface. To use popup API, do something like

auto surface = Gdk::Surface::create_popup(parent, autohide);
auto popup = std::dynamic_pointer_cast<Gdk::PopupSurfaceImpl>(surface);
if (popup)
popup->do_something();
std::dynamic_pointer_cast
__shared_ptr< _Tp, _Lp > dynamic_pointer_cast(const __shared_ptr< _Tp1, _Lp > &__r) noexcept
Gdk::Surface::create_popup
static Glib::RefPtr< Surface > create_popup(const Glib::RefPtr< Surface > &parent, bool autohide)
Create a new popup surface.

Parameters

  parent | The parent surface to attach the surface to.
  autohide | Whether to hide the surface on outside clicks.

Returns
  A new Gdk::Surface.

## ◆ create_similar_surface()

::Cairo::RefPtr< ::Cairo::Surface > Gdk::Surface::create_similar_surface | ( | ::Cairo::Content | content,
|  | int | width,
|  | int | height )

Create a new Cairo surface that is as compatible as possible with the given surface.

For example the new surface will have the same fallback resolution and font options as surface. Generally, the new surface will also use the same backend as surface, unless that is not possible for some reason. The type of the returned surface may be examined with cairo_surface_get_type().

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

This function always returns a valid pointer, but it will return a pointer to a “nil” surface if other is already in an error state or any other error occurs.

Deprecated: 4.12: Create a suitable cairo image surface yourself

Deprecated
  Create a suitable cairo image surface yourself.

Parameters

  content | The content for the new surface.
  width | Width of the new surface.
  height | Height of the new surface.

Returns
  A pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it.

## ◆ create_toplevel()

Glib::RefPtr< Surface > Gdk::Surface::create_toplevel | ( | const Glib::RefPtr< Display > & | display | ) |
| static

Creates a new toplevel surface.

The created surface is usually a subclass of Gdk::Surface that implements the Gdk::Toplevel interface. To use toplevel API, do something like

auto surface = Gdk::Surface::create_toplevel(display);
auto toplevel = std::dynamic_pointer_cast<Gdk::ToplevelSurfaceImpl>(surface);
if (toplevel)
toplevel->do_something();
Gdk::Surface::create_toplevel
static Glib::RefPtr< Surface > create_toplevel(const Glib::RefPtr< Display > &display)
Creates a new toplevel surface.

Parameters

  display | The display to create the surface on.

Returns
  The new Gdk::Surface.

## ◆ drag_begin_from_point()

Glib::RefPtr< Drag > Gdk::Surface::drag_begin_from_point | ( | const Glib::RefPtr< Device > & | device,
|  | const Glib::RefPtr< ContentProvider > & | content,
|  | DragAction | actions,
|  | double | dx,
|  | double | dy )

Starts a drag and creates a new drag context for it.

This function is called by the drag source. After this call, you probably want to set up the drag icon using the surface returned by get_drag_surface().

This function returns a reference to the Gdk::Drag object, but GTK keeps its own reference as well, as long as the DND operation is going on.

Note
  if actions include Gdk::DragAction::MOVE, you need to listen for the Gdk::Drag::signal_dnd_finished() signal and delete the data at the source if get_selected_action() returns Gdk::DragAction::MOVE.

Parameters

  device | The device that controls this drag.
  content | The offered content.
  actions | The actions supported by this drag.
  dx | The x offset to device's position where the drag nominally started.
  dy | The y offset to device's position where the drag nominally started.

Returns
  A newly created Gdk::Drag.

## ◆ get_cursor() [1/2]

Glib::RefPtr< Cursor > Gdk::Surface::get_cursor | ( |  | ) |

Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface.

If the return value is nullptr then there is no custom cursor set on the surface, and it is using the cursor for its parent surface.

Use set_cursor() to unset the cursor of the surface.

Returns
  A Gdk::Cursor.

## ◆ get_cursor() [2/2]

Glib::RefPtr< const Cursor > Gdk::Surface::get_cursor | ( |  | ) | const

Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface.

If the return value is nullptr then there is no custom cursor set on the surface, and it is using the cursor for its parent surface.

Use set_cursor() to unset the cursor of the surface.

Returns
  A Gdk::Cursor.

## ◆ get_device_cursor() [1/2]

Glib::RefPtr< const Cursor > Gdk::Surface::get_device_cursor | ( | const Glib::RefPtr< const Device > & | device | ) | const

Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface.

If the return value is nullptr then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.

Use set_cursor() to unset the cursor of the surface.

Parameters

  device | A pointer Gdk::Device.

Returns
  A Gdk::Cursor.

## ◆ get_device_cursor() [2/2]

Glib::RefPtr< Cursor > Gdk::Surface::get_device_cursor | ( | const Glib::RefPtr< Device > & | device | ) |

Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface.

If the return value is nullptr then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.

Use set_cursor() to unset the cursor of the surface.

Parameters

  device | A pointer Gdk::Device.

Returns
  A Gdk::Cursor.

## ◆ get_device_position()

bool Gdk::Surface::get_device_position | ( | const Glib::RefPtr< const Device > & | device,
|  | double & | x,
|  | double & | y,
|  | ModifierType & | mask ) const

Obtains the current device position and modifier state.

The position is given in coordinates relative to the upper left corner of surface.

Return: true if the device is over the surface

Parameters

  device | Pointer Gdk::Device to query to.
  x | Return location for the X coordinate of device.
  y | Return location for the Y coordinate of device.
  mask | Return location for the modifier mask.

## ◆ get_display() [1/2]

Glib::RefPtr< Display > Gdk::Surface::get_display | ( |  | ) |

Gets the Gdk::Display associated with a Gdk::Surface.

Returns
  The Gdk::Display associated with surface.

## ◆ get_display() [2/2]

Glib::RefPtr< const Display > Gdk::Surface::get_display | ( |  | ) | const

Gets the Gdk::Display associated with a Gdk::Surface.

Returns
  The Gdk::Display associated with surface.

## ◆ get_frame_clock() [1/2]

Glib::RefPtr< FrameClock > Gdk::Surface::get_frame_clock | ( |  | ) |

Gets the frame clock for the surface.

The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface.

Since gtkmm 3.24

Returns
  The frame clock.

## ◆ get_frame_clock() [2/2]

Glib::RefPtr< const FrameClock > Gdk::Surface::get_frame_clock | ( |  | ) | const

Gets the frame clock for the surface.

The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface.

Since gtkmm 3.24

Returns
  The frame clock.

## ◆ get_height()

int Gdk::Surface::get_height | ( |  | ) | const

Returns the height of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see get_scale_factor()).

Returns
  The height of surface.

## ◆ get_mapped()

bool Gdk::Surface::get_mapped | ( |  | ) | const

Checks whether the surface has been mapped.

A surface is mapped with Gdk::Toplevel::present() or Gdk::Popup::present().

Returns
  true if the surface is mapped.

## ◆ get_scale()

double Gdk::Surface::get_scale | ( |  | ) | const

Returns the internal scale that maps from surface coordinates to the actual device pixels.

When the scale is bigger than 1, the windowing system prefers to get buffers with a resolution that is bigger than the surface size (e.g. to show the surface on a high-resolution display, or in a magnifier).

Compare with get_scale_factor(), which returns the next larger integer.

The scale may change during the lifetime of the surface.

Since gtkmm 4.12

Returns
  The scale.

## ◆ get_scale_factor()

int Gdk::Surface::get_scale_factor | ( |  | ) | const

Returns the internal scale factor that maps from surface coordinates to the actual device pixels.

On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2). A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data.

The scale factor may change during the lifetime of the surface.

Returns
  The scale factor.

## ◆ get_type()

GType Gdk::Surface::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ get_width()

int Gdk::Surface::get_width | ( |  | ) | const

Returns the width of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see get_scale_factor()).

Returns
  The width of surface.

## ◆ gobj() [1/2]

GdkSurface * Gdk::Surface::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GdkSurface * Gdk::Surface::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GdkSurface * Gdk::Surface::gobj_copy | ( |  | ) |

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

## ◆ hide()

void Gdk::Surface::hide | ( |  | ) |

Hide the surface.

For toplevel surfaces, withdraws them, so they will no longer be known to the window manager; for all surfaces, unmaps them, so they won’t be displayed. Normally done automatically as part of gtk_widget_hide().

## ◆ operator=()

Surface & Gdk::Surface::operator= | ( | Surface && | src | ) |
| noexcept

## ◆ property_cursor() [1/2]

Glib::PropertyProxy< Glib::RefPtr< Cursor > > Gdk::Surface::property_cursor | ( |  | ) |

The mouse pointer for the Gdk::Surface.

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

## ◆ property_cursor() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > Gdk::Surface::property_cursor | ( |  | ) | const

The mouse pointer for the Gdk::Surface.

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

## ◆ property_display()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > Gdk::Surface::property_display | ( |  | ) | const

The Gdk::Display connection of the surface.

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

## ◆ property_frame_clock()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< FrameClock > > Gdk::Surface::property_frame_clock | ( |  | ) | const

The Gdk::FrameClock of the surface.

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

## ◆ property_height()

Glib::PropertyProxy_ReadOnly< int > Gdk::Surface::property_height | ( |  | ) | const

The height of the surface, in pixels.

Default value: 0

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

## ◆ property_mapped()

Glib::PropertyProxy_ReadOnly< bool > Gdk::Surface::property_mapped | ( |  | ) | const

Whether the surface is mapped.

Default value: false

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

## ◆ property_scale()

Glib::PropertyProxy_ReadOnly< double > Gdk::Surface::property_scale | ( |  | ) | const

The scale of the surface.

Since gtkmm 4.12

Default value: 1.000000

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

## ◆ property_scale_factor()

Glib::PropertyProxy_ReadOnly< int > Gdk::Surface::property_scale_factor | ( |  | ) | const

The scale factor of the surface.

The scale factor is the next larger integer, compared to property_scale().

Default value: 1

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

## ◆ property_width()

Glib::PropertyProxy_ReadOnly< int > Gdk::Surface::property_width | ( |  | ) | const

The width of the surface in pixels.

Default value: 0

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

## ◆ queue_render()

void Gdk::Surface::queue_render | ( |  | ) |

Forces a signal_render() signal emission for surface to be scheduled.

This function is useful for implementations that track invalid regions on their own.

## ◆ request_layout()

void Gdk::Surface::request_layout | ( |  | ) |

Request a layout phase from the surface's frame clock.

See Gdk::FrameClock::request_phase().

## ◆ set_cursor() [1/2]

void Gdk::Surface::set_cursor | ( |  | ) |

Use the parent surface's cursor.

For top-level windows this means that it will use the default cursor for the ROOT window.

## ◆ set_cursor() [2/2]

void Gdk::Surface::set_cursor | ( | const Glib::RefPtr< Cursor > & | cursor | ) |

Sets the default mouse pointer for a Gdk::Surface.

Passing nullptr for the cursor argument means that surface will use the cursor of its parent surface. Most surfaces should use this default. Note that cursor must be for the same display as surface.

Use Gdk::Cursor::new_from_name() or Gdk::Cursor::new_from_texture() to create the cursor. To make the cursor invisible, use Gdk::Cursor::Type::BLANK_CURSOR.

Parameters

  cursor | A Gdk::Cursor.

## ◆ set_device_cursor()

void Gdk::Surface::set_device_cursor | ( | const Glib::RefPtr< Device > & | device,
|  | const Glib::RefPtr< Cursor > & | cursor )

Sets a specific Gdk::Cursor for a given device when it gets inside surface.

Passing nullptr for the cursor argument means that surface will use the cursor of its parent surface. Most surfaces should use this default.

Use Gdk::Cursor::new_from_name() or Gdk::Cursor::new_from_texture() to create the cursor. To make the cursor invisible, use Gdk::Cursor::Type::BLANK_CURSOR.

Parameters

  device | A pointer Gdk::Device.
  cursor | A Gdk::Cursor.

## ◆ set_input_region()

void Gdk::Surface::set_input_region | ( | const ::Cairo::RefPtr< ::Cairo::Region > & | region | ) |

Apply the region to the surface for the purpose of event handling.

Mouse events which happen while the pointer position corresponds to an unset bit in the mask will be passed on the surface below surface.

An input region is typically used with RGBA surfaces. The alpha channel of the surface defines which pixels are invisible and allows for nicely antialiased borders, and the input region controls where the surface is “clickable”.

Use Gdk::Display::supports_input_shapes() to find out if a particular backend supports input regions.

Parameters

  region | Region of surface to be reactive, or nullptr to make the entire surface reactive.

## ◆ set_opaque_region()

void Gdk::Surface::set_opaque_region | ( | const ::Cairo::RefPtr< const ::Cairo::Region > & | region | ) |

Marks a region of the Gdk::Surface as opaque.

For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not.

This function only works for toplevel surfaces.

GTK will update this property automatically if the surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your GtkWidgetClass.css_changed handler.

Deprecated: 4.16: GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.

Deprecated
  4.16: GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.

Parameters

  region | A region, or nullptr to make the entire surface opaque.

## ◆ signal_enter_monitor()

Glib::SignalProxy< void(const Glib::RefPtr< Monitor > &)> Gdk::Surface::signal_enter_monitor | ( |  | ) |

Slot Prototype:
  void on_my_enter_monitor(const Glib::RefPtr<Monitor>& monitor)

Flags: Run First

Emitted when surface starts being present on the monitor.

Parameters

  monitor | The monitor.

## ◆ signal_event()

Glib::SignalProxy< bool(const Glib::RefPtr< const Event > &)> Gdk::Surface::signal_event | ( |  | ) |

Slot Prototype:
  bool on_my_event(const Glib::RefPtr<const Event>& event)

Flags: Run Last

Emitted when GDK receives an input event for surface.

Parameters

  event | An input event.

Returns
  true to indicate that the event has been handled.

## ◆ signal_layout()

Glib::SignalProxy< void(int, int)> Gdk::Surface::signal_layout | ( |  | ) |

Slot Prototype:
  void on_my_layout(int width, int height)

Flags: Run First

Emitted when the size of surface is changed, or when relayout should be performed.

Surface size is reported in ”application pixels”, not ”device pixels” (see Gdk::Surface::get_scale_factor()).

Parameters

  width | The current width.
  height | The current height.

## ◆ signal_leave_monitor()

Glib::SignalProxy< void(const Glib::RefPtr< Monitor > &)> Gdk::Surface::signal_leave_monitor | ( |  | ) |

Slot Prototype:
  void on_my_leave_monitor(const Glib::RefPtr<Monitor>& monitor)

Flags: Run First

Emitted when surface stops being present on the monitor.

Parameters

  monitor | The monitor.

## ◆ signal_render()

Glib::SignalProxy< bool(const ::Cairo::RefPtr< const ::Cairo::Region > &)> Gdk::Surface::signal_render | ( |  | ) |

Slot Prototype:
  bool on_my_render(const Cairo::RefPtr<const ::Cairo::Region>& expose_region)

Flags: Run Last

Emitted when part of the surface needs to be redrawn.

Parameters

  expose_region | The region that needs to be redrawn.

Returns
  true to indicate that the signal has been handled.

## ◆ translate_coordinates()

bool Gdk::Surface::translate_coordinates | ( | const Glib::RefPtr< const Surface > & | to,
|  | double & | x,
|  | double & | y ) const

Translates coordinates between two surfaces.

Note that this only works if this surface and to are popups or transient-for to the same toplevel (directly or indirectly).

Since gtkmm 4.18

Parameters

  | to | The target surface.
  [in,out] | x | Coordinate to translate.
  [in,out] | y | Coordinate to translate.

Returns
  true if the coordinates were successfully translated.

## Friends And Related Symbol Documentation

## ◆ wrap()

Glib::RefPtr< Gdk::Surface > wrap | ( | GdkSurface * | 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.