Gdk.Surface¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new_popup` (parent, autohide)
class	`new_toplevel` (display)
	`beep` ()
	`create_cairo_context` ()
	`create_gl_context` ()
	`create_similar_surface` (content, width, height)
	`create_vulkan_context` ()
	`destroy` ()
	`get_cursor` ()
	`get_device_cursor` (device)
	`get_device_position` (device)
	`get_display` ()
	`get_frame_clock` ()
	`get_height` ()
	`get_mapped` ()
	`get_scale` ()
	`get_scale_factor` ()
	`get_width` ()
	`hide` ()
	`is_destroyed` ()
	`queue_render` ()
	`request_layout` ()
	`set_cursor` (cursor)
	`set_device_cursor` (device, cursor)
	`set_input_region` (region)
	`set_opaque_region` (region)
	`translate_coordinates` (to, x, y)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`cursor`	`Gdk.Cursor`	r/w
`display`	`Gdk.Display`	r/w/co
`frame-clock`	`Gdk.FrameClock`	r/w/co
`height`	`int`	r
`mapped`	`bool`	r
`scale`	`float`	r
`scale-factor`	`int`	r
`width`	`int`	r

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`enter-monitor`	Emitted when surface starts being present on the monitor.
`event`	Emitted when GDK receives an input event for surface.
`layout`	Emitted when the size of surface is changed, or when relayout should be performed.
`leave-monitor`	Emitted when surface stops being present on the monitor.
`render`	Emitted when part of the surface needs to be redrawn.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gdk.Surface(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: Gdk.SurfaceClass

A GdkSurface is a rectangular region on the screen.

It’s a low-level object, used to implement high-level objects such as GtkWindow.

The surfaces you see in practice are either [iface`Gdk`.Toplevel] or [iface`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.

classmethod new_popup(parent, autohide)[source]¶

Parameters:

parent (Gdk.Surface) – the parent surface to attach the surface to
autohide (bool) – whether to hide the surface on outside clicks

Returns:

a new GdkSurface

Return type:

Gdk.Surface

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using [method`Gdk`.Popup.present].

classmethod new_toplevel(display)[source]¶

Parameters:: display (Gdk.Display) – the display to create the surface on
Returns:: the new GdkSurface
Return type:: Gdk.Surface

Creates a new toplevel surface.

beep()[source]¶

Emits a short beep associated to self.

If the display of self does not support per-surface beeps, emits a short beep on the display just as [method`Gdk`.Display.beep].

create_cairo_context()[source]¶

Returns:: the newly created GdkCairoContext
Return type:: Gdk.CairoContext

Creates a new GdkCairoContext for rendering on self.

create_gl_context()[source]¶

Raises:: GLib.Error
Returns:: the newly created GdkGLContext
Return type:: Gdk.GLContext

Creates a new GdkGLContext for the GdkSurface.

The context is disconnected from any particular surface or surface. If the creation of the GdkGLContext failed, error will be set. Before using the returned GdkGLContext, you will need to call [method`Gdk`.GLContext.make_current] or [method`Gdk`.GLContext.realize].

create_similar_surface(content, width, height)[source]¶

Parameters:

content (cairo.Content) – the content for the new surface
width (int) – width of the new surface
height (int) – 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.

Return type:

cairo.Surface

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

For example the new surface will have the same fallback resolution and font options as self. Generally, the new surface will also use the same backend as self, 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 since version 4.12: Create a suitable cairo image surface yourself

create_vulkan_context()[source]¶

Raises:: GLib.Error
Returns:: None
Return type:: Gdk.VulkanContext

Sets an error and returns None.

Deprecated since version 4.14: GTK does not expose any Vulkan internals. This function is a leftover that was accidentally exposed.

destroy()[source]¶

Destroys the window system resources associated with self and decrements self's reference count.

The window system resources for all children of self are also destroyed, but the children’s reference counts are not decremented.

Note that a surface will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens.

get_cursor()[source]¶

Returns:: a GdkCursor
Return type:: Gdk.Cursor or None

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

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

Use [method`Gdk`.Surface.set_cursor] to unset the cursor of the surface.

get_device_cursor(device)[source]¶

Parameters:: device (Gdk.Device) – a pointer GdkDevice
Returns:: a GdkCursor
Return type:: Gdk.Cursor or None

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

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

Use [method`Gdk`.Surface.set_cursor] to unset the cursor of the surface.

get_device_position(device)[source]¶

Parameters:

device (Gdk.Device) – pointer GdkDevice to query to

Returns:

True if the device is over the surface

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

Return type:

(bool, x: float, y: float, mask: Gdk.ModifierType)

Obtains the current device position and modifier state.

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

get_display()[source]¶

Returns:: the GdkDisplay associated with self
Return type:: Gdk.Display

Gets the GdkDisplay associated with a GdkSurface.

get_frame_clock()[source]¶

Returns:: the frame clock
Return type:: Gdk.FrameClock

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.

get_height()[source]¶

Returns:: The height of self
Return type:: int

Returns the height of the given self.

Surface size is reported in ”application pixels”, not ”device pixels” (see [method`Gdk`.Surface.get_scale_factor]).

get_mapped()[source]¶

Returns:: True if the surface is mapped
Return type:: bool

Checks whether the surface has been mapped.

A surface is mapped with [method`Gdk`.Toplevel.present] or [method`Gdk`.Popup.present].

get_scale()[source]¶

Returns:: the scale
Return type:: float

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 [method`Gdk`.Surface.get_scale_factor], which returns the next larger integer.

The scale may change during the lifetime of the surface.

New in version 4.12.

get_scale_factor()[source]¶

Returns:: the scale factor
Return type:: int

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.

get_width()[source]¶

Returns:: The width of self
Return type:: int

Returns the width of the given self.

Surface size is reported in ”application pixels”, not ”device pixels” (see [method`Gdk`.Surface.get_scale_factor]).

hide()[source]¶

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

is_destroyed()[source]¶

Returns:: True if the surface is destroyed
Return type:: bool

Check to see if a surface is destroyed.

queue_render()[source]¶

Forces a [signal`Gdk`.Surface::render] signal emission for self to be scheduled.

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

request_layout()[source]¶

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

See [method`Gdk`.FrameClock.request_phase].

set_cursor(cursor)[source]¶

Parameters:: cursor (Gdk.Cursor or None) – a GdkCursor

Sets the default mouse pointer for a GdkSurface.

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

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

set_device_cursor(device, cursor)[source]¶

Parameters:

device (Gdk.Device) – a pointer GdkDevice
cursor (Gdk.Cursor) – a GdkCursor

Sets a specific GdkCursor for a given device when it gets inside self.

Passing None for the cursor argument means that self 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_BLANK_CURSOR.

set_input_region(region)[source]¶

Parameters:: region (cairo.Region) – region of surface to be reactive

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

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.

set_opaque_region(region)[source]¶

Parameters:: region (cairo.Region or None) – a region, or None to make the entire surface opaque

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 self 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 since version 4.16: GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.

translate_coordinates(to, x, y)[source]¶

Parameters:

to (Gdk.Surface) – the target surface
x (float) – coordinates to translate
y (float) – coordinates to translate

Returns:

True if the coordinates were successfully translated

x:: coordinates to translate
y:: coordinates to translate

Return type:

(bool, x: float, y: float)

Translates coordinates between two surfaces.

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

Signal Details¶

Gdk.Surface.signals.enter_monitor(surface, monitor)¶

Signal Name:

enter-monitor

Flags:

RUN_FIRST

Parameters:

surface (Gdk.Surface) – The object which received the signal
monitor (Gdk.Monitor) – the monitor

Emitted when surface starts being present on the monitor.

Gdk.Surface.signals.event(surface, event)¶

Signal Name:

event

Flags:

RUN_LAST

Parameters:

surface (Gdk.Surface) – The object which received the signal
event (Gdk.Event) – an input event

Returns:

True to indicate that the event has been handled

Return type:

bool

Emitted when GDK receives an input event for surface.

Gdk.Surface.signals.layout(surface, width, height)¶

Signal Name:

layout

Flags:

RUN_FIRST

Parameters:

surface (Gdk.Surface) – The object which received the signal
width (int) – the current width
height (int) – the current height

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

Gdk.Surface.signals.leave_monitor(surface, monitor)¶

Signal Name:

leave-monitor

Flags:

RUN_FIRST

Parameters:

surface (Gdk.Surface) – The object which received the signal
monitor (Gdk.Monitor) – the monitor

Emitted when surface stops being present on the monitor.

Gdk.Surface.signals.render(surface, region)¶

Signal Name:

render

Flags:

RUN_LAST

Parameters:

surface (Gdk.Surface) – The object which received the signal
region (cairo.Region) – the region that needs to be redrawn

Returns:

True to indicate that the signal has been handled

Return type:

bool

Emitted when part of the surface needs to be redrawn.

Property Details¶

Gdk.Surface.props.cursor¶

Name:: cursor
Type:: Gdk.Cursor
Default Value:: None
Flags:: READABLE, WRITABLE

The mouse pointer for the GdkSurface.

Gdk.Surface.props.display¶

Name:: display
Type:: Gdk.Display
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The GdkDisplay connection of the surface.

Gdk.Surface.props.frame_clock¶

Name:: frame-clock
Type:: Gdk.FrameClock
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The GdkFrameClock of the surface.

Gdk.Surface.props.height¶

Name:: height
Type:: int
Default Value:: 0
Flags:: READABLE

The height of the surface, in pixels.

Gdk.Surface.props.mapped¶

Name:: mapped
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the surface is mapped.

Gdk.Surface.props.scale¶

Name:: scale
Type:: float
Default Value:: 1.0
Flags:: READABLE

The scale of the surface.

New in version 4.12.

Gdk.Surface.props.scale_factor¶

Name:: scale-factor
Type:: int
Default Value:: 1
Flags:: READABLE

The scale factor of the surface.

The scale factor is the next larger integer, compared to [property`Gdk`.Surface:scale].

Gdk.Surface.props.width¶

Name:: width
Type:: int
Default Value:: 0
Flags:: READABLE

The width of the surface in pixels.