gtkmm: Gdk::Surface Class Reference

gtkmm 4.2.0

Public Member Functions | Static Public Member Functions | Related Functions | 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. More...
const GdkSurface* | gobj () const
| Provides access to the underlying C GObject. More...
GdkSurface* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Glib::RefPtr< Display > | get_display ()
| Gets the `GdkDisplay` associated with a `GdkSurface`. More...
Glib::RefPtr< const Display > | get_display () const
| Gets the `GdkDisplay` associated with a `GdkSurface`. More...
void | hide ()
| Hide the surface. More...
void | set_input_region (const ::Cairo::RefPtr< ::Cairo::Region >& region)
| Apply the region to the surface for the purpose of event handling. More...
bool | get_mapped () const
| Checks whether the surface has been mapped. More...
void | set_cursor (const Glib::RefPtr< Cursor >& cursor)
| Sets the default mouse pointer for a `GdkSurface`. More...
void | set_cursor ()
| Use the parent surface's cursor. More...
void | set_device_cursor (const Glib::RefPtr< Device >& device, const Glib::RefPtr< Cursor >& cursor)
| Sets a specific `GdkCursor` for a given device when it gets inside surface. More...
Glib::RefPtr< Cursor > | get_device_cursor (const Glib::RefPtr< Device >& device)
| Retrieves a `GdkCursor` pointer for the device currently set on the specified `GdkSurface`. More...
Glib::RefPtr< const Cursor > | get_device_cursor (const Glib::RefPtr< const Device >& device) const
| Retrieves a `GdkCursor` pointer for the device currently set on the specified `GdkSurface`. More...
Glib::RefPtr< Cursor > | get_cursor ()
| Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`. More...
Glib::RefPtr< const Cursor > | get_cursor () const
| Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`. More...
int | get_width () const
| Returns the width of the given surface. More...
int | get_height () const
| Returns the height of the given surface. More...
int | get_scale_factor () const
| Returns the internal scale factor that maps from surface coordinates to the actual device pixels. More...
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. More...
::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. More...
void | beep ()
| Emits a short beep associated to surface. More...
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. More...
void | queue_render ()
| Forces a [signal Gdk.Surface::render] signal emission for surface to be scheduled. More...
void | request_layout ()
| Request a layout phase from the surface's frame clock. More...
Glib::RefPtr< FrameClock > | get_frame_clock ()
| Gets the frame clock for the surface. More...
Glib::RefPtr< const FrameClock > | get_frame_clock () const
| Gets the frame clock for the surface. More...
void | set_opaque_region (const ::Cairo::RefPtr< const ::Cairo::Region >& region)
| Marks a region of the `GdkSurface` as opaque. More...
Glib::RefPtr< Gdk::GLContext > | create_gl_context ()
| Creates a new GLContext matching the framebuffer format to the visual of the Surface. More...
Glib::RefPtr< Gdk::CairoContext > | create_cairo_context ()
| Creates a new `GdkCairoContext` for rendering on surface. More...
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 `GdkSurface`. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > | property_cursor () const
| The mouse pointer for the `GdkSurface`. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > | property_display () const
| The `GdkDisplay` connection of the surface. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< FrameClock > > | property_frame_clock () const
| The `GdkFrameClock` of the surface. More...
Glib::PropertyProxy_ReadOnly< bool > | property_mapped () const
| Whether the surface is mapped. More...
Glib::PropertyProxy_ReadOnly< int > | property_width () const
| The width of the surface in pixels. More...
Glib::PropertyProxy_ReadOnly< int > | property_height () const
| The height of the surface, in pixels. More...
Glib::PropertyProxy_ReadOnly< int > | property_scale_factor () const
| The scale factor of the surface. More...
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 (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

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

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

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
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 [method Gdk.Display.beep].

## ◆ create_cairo_context()

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

Creates a new `GdkCairoContext` for rendering on surface.

Returns
  The newly created `GdkCairoContext`.

## ◆ 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()

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

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

static 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 [method Gdk.Drag.get_drag_surface].

This function returns a reference to the [class 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 [signal Gdk.Drag::dnd-finished] signal and delete the data at the source if [method Gdk.Drag.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 [class Gdk.Drag] or `nullptr` on error.

## ◆ get_cursor() [1/2]

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

Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`.

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.

Returns
  A `GdkCursor`, or `nullptr`. The returned object is owned by the `GdkSurface` and should not be unreferenced directly. Use [method Gdk.Surface.set_cursor] to unset the cursor of the surface.

## ◆ get_cursor() [2/2]

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

Retrieves a `GdkCursor` pointer for the cursor currently set on the `GdkSurface`.

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.

Returns
  A `GdkCursor`, or `nullptr`. The returned object is owned by the `GdkSurface` and should not be unreferenced directly. Use [method Gdk.Surface.set_cursor] to unset the cursor of the surface.

## ◆ get_device_cursor() [1/2]

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

Retrieves a `GdkCursor` pointer for the device currently set on the specified `GdkSurface`.

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.

Parameters

  device | A pointer `GdkDevice`.

Returns
  A `GdkCursor`, or `nullptr`. The returned object is owned by the `GdkSurface` and should not be unreferenced directly. Use [method Gdk.Surface.set_cursor] to unset the cursor of the surface.

## ◆ get_device_cursor() [2/2]

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

Retrieves a `GdkCursor` pointer for the device currently set on the specified `GdkSurface`.

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.

Parameters

  device | A pointer `GdkDevice`.

Returns
  A `GdkCursor`, or `nullptr`. The returned object is owned by the `GdkSurface` and should not be unreferenced directly. Use [method Gdk.Surface.set_cursor] to unset the cursor of the surface.

## ◆ 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 `GdkDevice` to query to.
  x | Return locatio for the X coordinate of device, or `nullptr`.
  y | Return location for the Y coordinate of device, or `nullptr`.
  mask | Return location for the modifier mask, or `nullptr`.

## ◆ get_display() [1/2]

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

Gets the `GdkDisplay` associated with a `GdkSurface`.

Returns
  The `GdkDisplay` associated with surface.

## ◆ get_display() [2/2]

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

Gets the `GdkDisplay` associated with a `GdkSurface`.

Returns
  The `GdkDisplay` 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 [method Gdk.Surface.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 [method Gdk.Toplevel.present] or [method Gdk.Popup.present].

Returns
  `true` if the surface is mapped.

## ◆ 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 of a surface may change during runtime.

Returns
  The scale factor.

## ◆ get_type()

static 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 [method Gdk.Surface.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 [method 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 `GdkSurface`.

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 `GdkSurface`.

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 `GdkDisplay` 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 `GdkFrameClock` 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_factor()

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

The scale factor of the surface.

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 Gdk.Surface::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 [method 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 `GdkSurface`.

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 [ctor Gdk.Cursor.new_from_name] or [ctor Gdk.Cursor.new_from_texture] to create the cursor. To make the cursor invisible, use Gdk::Cursor::Type::BLANK_CURSOR.

Parameters

  cursor | A `GdkCursor`.

## ◆ set_device_cursor()

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

Sets a specific `GdkCursor` 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 [ctor Gdk.Cursor.new_from_name] or [ctor Gdk.Cursor.new_from_texture] to create the cursor. To make the cursor invisible, use Gdk::Cursor::Type::BLANK_CURSOR.

Parameters

  device | A pointer `GdkDevice`.
  cursor | A `GdkCursor`.

## ◆ 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 [method Gdk.Display.supports_input_shapes] to find out if a particular backend supports input regions.

Parameters

  region | Region of surface to be reactive.

## ◆ set_opaque_region()

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

Marks a region of the `GdkSurface` 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 Gtk::WidgetClass.css_changed() handler.

Parameters

  region | A region, or `nullptr`.

## ◆ 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.

## Friends And Related Function 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.