Surface

class Surface(**properties: Any)

Superclasses: Object

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 Toplevel or 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.

Constructors

class Surface

classmethod new_popup(parent: Surface, autohide: bool) → Surface

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using present.

Parameters:

• parent – the parent surface to attach the surface to

• autohide – whether to hide the surface on outside clicks

classmethod new_toplevel(display: Display) → Surface

Creates a new toplevel surface.

Parameters:

display – the display to create the surface on

Methods

class Surface

beep() → None

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

create_cairo_context() → CairoContext

Creates a new GdkCairoContext for rendering on surface.

create_gl_context() → 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 make_current or realize.

create_similar_surface(content: Content, width: int, height: int) → Surface

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 since version 4.12: 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

create_vulkan_context() → 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() → None

Destroys the window system resources associated with surface and decrements surface’s reference count.

The window system resources for all children of surface 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() → Cursor | 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 set_cursor to unset the cursor of the surface.

get_device_cursor(device: Device) → Cursor | 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 set_cursor to unset the cursor of the surface.

Parameters:

device – a pointer GdkDevice

get_device_position(device: Device) → tuple[bool, float, float, ModifierType]

Obtains the current device position and modifier state.

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

Parameters:

device – pointer GdkDevice to query to

get_display() → Display

Gets the GdkDisplay associated with a GdkSurface.

get_frame_clock() → 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() → int

Returns the height of the given surface.

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

get_mapped() → bool

Checks whether the surface has been mapped.

A surface is mapped with present or present.

get_scale() → 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 get_scale_factor, which returns the next larger integer.

The scale may change during the lifetime of the surface.

Added in version 4.12.

get_scale_factor() → 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() → int

Returns the width of the given surface.

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

hide() → None

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

Check to see if a surface is destroyed.

queue_render() → None

Forces a render signal emission for surface to be scheduled.

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

request_layout() → None

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

See request_phase.

set_cursor(cursor: Cursor | None = None) → None

Sets the default mouse pointer for a GdkSurface.

Passing None 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 new_from_name or new_from_texture to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.

Parameters:

cursor – a GdkCursor

set_device_cursor(device: Device, cursor: Cursor) → None

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

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

Use new_from_name or new_from_texture to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.

Parameters:

• device – a pointer GdkDevice

• cursor – a GdkCursor

set_input_region(region: Region) → None

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 supports_input_shapes to find out if a particular backend supports input regions.

Parameters:

region – region of surface to be reactive

set_opaque_region(region: Region | None = None) → None

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 GtkWidgetClass.css_changed handler.

Parameters:

region – a region, or None to make the entire surface opaque

translate_coordinates(to: Surface) → tuple[bool, float, float]

Translates coordinates between two surfaces.

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

Parameters:

to – the target surface

Properties

class Surface

props.cursor: Cursor

The mouse pointer for the GdkSurface.

props.display: Display

The GdkDisplay connection of the surface.

props.frame_clock: FrameClock

The GdkFrameClock of the surface.

props.height: int

The height of the surface, in pixels.

props.mapped: bool

Whether the surface is mapped.

props.scale: float

The scale of the surface.

Added in version 4.12.

props.scale_factor: int

The scale factor of the surface.

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

props.width: int

The width of the surface in pixels.

Signals

class Surface.signals

enter_monitor(monitor: Monitor) → None

Emitted when surface starts being present on the monitor.

Parameters:

monitor – the monitor

event(event: Event) → bool

Emitted when GDK receives an input event for surface.

Parameters:

event – an input event

layout(width: int, height: int) → None

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

Parameters:

• width – the current width

• height – the current height

leave_monitor(monitor: Monitor) → None

Emitted when surface stops being present on the monitor.

Parameters:

monitor – the monitor

render(region: Region) → bool

Emitted when part of the surface needs to be redrawn.

Parameters:

region – the region that needs to be redrawn