gtkmm  4.8.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:
Inheritance graph
[legend]

Public Member Functions

 Surface (Surface && src) noexcept
 
Surfaceoperator= (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< Displayget_display ()
 Gets the Gdk::Display associated with a Gdk::Surface. More...
 
Glib::RefPtr< const Displayget_display () const
 Gets the Gdk::Display associated with a Gdk::Surface. 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 Gdk::Surface. 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 Gdk::Cursor for a given device when it gets inside surface. More...
 
Glib::RefPtr< Cursorget_device_cursor (const Glib::RefPtr< Device > & device)
 Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface. More...
 
Glib::RefPtr< const Cursorget_device_cursor (const Glib::RefPtr< const Device > & device) const
 Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface. More...
 
Glib::RefPtr< Cursorget_cursor ()
 Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface. More...
 
Glib::RefPtr< const Cursorget_cursor () const
 Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface. 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< Dragdrag_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_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< FrameClockget_frame_clock ()
 Gets the frame clock for the surface. More...
 
Glib::RefPtr< const FrameClockget_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 Gdk::Surface as opaque. More...
 
Glib::RefPtr< Gdk::GLContextcreate_gl_context ()
 Creates a new GLContext matching the framebuffer format to the visual of the Surface. More...
 
Glib::RefPtr< Gdk::CairoContextcreate_cairo_context ()
 Creates a new Gdk::CairoContext 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 Gdk::Surface. More...
 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > property_cursor () const
 The mouse pointer for the Gdk::Surface. More...
 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > property_display () const
 The Gdk::Display connection of the surface. More...
 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< FrameClock > > property_frame_clock () const
 The Gdk::FrameClock 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...
 

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< Surfacecreate_toplevel (const Glib::RefPtr< Display > & display)
 Creates a new toplevel surface. More...
 
static Glib::RefPtr< Surfacecreate_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::Surfacewrap (GdkSurface * object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

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.

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
GLErrorOn 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();
static Glib::RefPtr< Surface > create_popup(const Glib::RefPtr< Surface > &parent, bool autohide)
Create a new popup surface.
Parameters
parentThe parent surface to attach the surface to.
autohideWhether 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
contentThe content for the new surface.
widthWidth of the new surface.
heightHeight 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();
static Glib::RefPtr< Surface > create_toplevel(const Glib::RefPtr< Display > &display)
Creates a new toplevel surface.
Parameters
displayThe 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
deviceThe device that controls this drag.
contentThe offered content.
actionsThe actions supported by this drag.
dxThe x offset to device's position where the drag nominally started.
dyThe 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
deviceA 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
deviceA 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
devicePointer Gdk::Device to query to.
xReturn location for the X coordinate of device.
yReturn location for the Y coordinate of device.
maskReturn 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_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 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_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_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
cursorA 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
deviceA pointer Gdk::Device.
cursorA 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
regionRegion 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 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 Gtk::Widget::css_changed_vfunc() handler.

Parameters
regionA 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
monitorThe 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
eventAn 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
widthThe current width.
heightThe 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
monitorThe 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_regionThe 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
objectThe C instance.
take_copyFalse 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.