Surface#
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 usingpresent
.- Parameters:
parent – the parent surface to attach the surface to
autohide – whether to hide the surface on outside clicks
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 asbeep
.
- create_cairo_context() CairoContext #
Creates a new
GdkCairoContext
for rendering onsurface
.
- create_gl_context() GLContext #
Creates a new
GdkGLContext
for theGdkSurface
.The context is disconnected from any particular surface or surface. If the creation of the
GdkGLContext
failed,error
will be set. Before using the returnedGdkGLContext
, you will need to callmake_current
orrealize
.
- 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 assurface
, 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 decrementssurface
’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 theGdkSurface
.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 thedevice
currently set on the specifiedGdkSurface
.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_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_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().
- queue_render() None #
Forces a
render
signal emission forsurface
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 thecursor
argument means thatsurface
will use the cursor of its parent surface. Most surfaces should use this default. Note thatcursor
must be for the same display assurface
.Use
new_from_name
ornew_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 insidesurface
.Passing
None
for thecursor
argument means thatsurface
will use the cursor of its parent surface. Most surfaces should use this default.Use
new_from_name
ornew_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
andfrom
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.frame_clock: FrameClock#
The type of the None singleton.
Signals#
- class Surface.signals
- enter_monitor(monitor: Monitor) None #
The type of the None singleton.
- Parameters:
monitor – the monitor
- layout(width: int, height: int) None #
The type of the None singleton.
- Parameters:
width – the current width
height – the current height