Skip to content

Gdk.Surface

class — extends GObject.Object

Represents 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

new_popup

@classmethod
def new_popup(cls, 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 Popup.present.

Parameters:

  • parent — the parent surface to attach the surface to
  • autohide — whether to hide the surface on outside clicks

new_toplevel

@classmethod
def new_toplevel(cls, display: Display) -> Surface

Creates a new toplevel surface.

Parameters:

  • display — the display to create the surface on

Methods

beep

def beep(self) -> 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 Display.beep.

create_cairo_context

def create_cairo_context(self) -> CairoContext

:::warning Deprecated since 4.18 This API is deprecated. :::

Creates a new GdkCairoContext for rendering on surface.

create_gl_context

def create_gl_context(self) -> 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 GLContext.make_current or GLContext.realize.

create_similar_surface

def create_similar_surface(self, content: cairo.Content | int, width: int, height: int) -> cairo.Surface

:::warning Deprecated since 4.12 This API is deprecated. :::

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

create_vulkan_context

def create_vulkan_context(self) -> VulkanContext

:::warning Deprecated since 4.14 This API is deprecated. :::

Sets an error and returns None.

destroy

def destroy(self) -> 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

def get_cursor(self) -> 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 Surface.set_cursor to unset the cursor of the surface.

get_device_cursor

def get_device_cursor(self, 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 Surface.set_cursor to unset the cursor of the surface.

Parameters:

  • device — a pointer GdkDevice

get_device_position

def get_device_position(self, device: Device) -> tuple[bool, float, float, ModifierType | int]

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

def get_display(self) -> Display

Gets the GdkDisplay associated with a GdkSurface.

get_frame_clock

def get_frame_clock(self) -> 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

def get_height(self) -> int

Returns the height of the given surface.

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

get_mapped

def get_mapped(self) -> bool

Checks whether the surface has been mapped.

A surface is mapped with Toplevel.present or Popup.present.

get_scale

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

The scale may change during the lifetime of the surface.

get_scale_factor

def get_scale_factor(self) -> 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

def get_width(self) -> int

Returns the width of the given surface.

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

hide

def hide(self) -> 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

def is_destroyed(self) -> bool

Check to see if a surface is destroyed.

queue_render

def queue_render(self) -> None

Forces a Surface.render signal emission for surface to be scheduled.

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

request_layout

def request_layout(self) -> None

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

See FrameClock.request_phase.

set_cursor

def set_cursor(self, cursor: Cursor | 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 Cursor.new_from_name or Cursor.new_from_texture to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.

Parameters:

  • cursor — a GdkCursor

set_device_cursor

def set_device_cursor(self, 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 Cursor.new_from_name or Cursor.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

def set_input_region(self, region: cairo.Region | None = ...) -> 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 Display.supports_input_shapes to find out if a particular backend supports input regions.

Parameters:

  • region — region of surface to be reactive, or None to make the entire surface reactive

set_opaque_region

def set_opaque_region(self, region: cairo.Region | None = ...) -> None

:::warning Deprecated since 4.16 This API is deprecated. :::

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

def translate_coordinates(self, 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

cursor

cursor: Cursor  # read/write

The mouse pointer for the GdkSurface.

display

display: Display  # read/write

The GdkDisplay connection of the surface.

frame_clock

frame_clock: FrameClock  # read/write

The GdkFrameClock of the surface.

height

height: int  # read-only

The height of the surface, in pixels.

mapped

mapped: bool  # read-only

Whether the surface is mapped.

scale

scale: float  # read-only

The scale of the surface.

scale_factor

scale_factor: int  # read-only

The scale factor of the surface.

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

width

width: int  # read-only

The width of the surface in pixels.

Signals

enter-monitor

def on_enter_monitor(self, monitor: Monitor) -> None: ...

Emitted when surface starts being present on the monitor.

event

def on_event(self, event: Event) -> bool: ...

Emitted when GDK receives an input event for surface.

layout

def on_layout(self, 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 Surface.get_scale_factor).

leave-monitor

def on_leave_monitor(self, monitor: Monitor) -> None: ...

Emitted when surface stops being present on the monitor.

render

def on_render(self, region: cairo.Region) -> bool: ...

Emitted when part of the surface needs to be redrawn.