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.

Deprecated since version 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 None to make the entire surface opaque

translate_coordinates(to: Surface, x: float, y: float) → 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
x – coordinates to translate
y – coordinates to translate

Properties#

class Surface

props.cursor: Cursor#: The type of the None singleton.

props.display: Display#: The type of the None singleton.

props.frame_clock: FrameClock#: The type of the None singleton.

props.height: int#: The type of the None singleton.

props.mapped: bool#: The type of the None singleton.

props.scale: float#: The type of the None singleton.

Added in version 4.12.

props.scale_factor: int#: The type of the None singleton.

props.width: int#: The type of the None singleton.