:right-sidebar: True Surface =================================================================== .. currentmodule:: gi.repository.Gdk .. class:: Surface(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: Surface(**properties) new_popup(parent:Gdk.Surface, autohide:bool) -> Gdk.Surface new_toplevel(display:Gdk.Display) -> Gdk.Surface Constructors ------------ .. rst-class:: interim-class .. class:: Surface :no-index: .. classmethod:: new_popup(parent: ~gi.repository.Gdk.Surface, autohide: bool) -> ~gi.repository.Gdk.Surface Create a new popup surface. The surface will be attached to ``parent`` and can be positioned relative to it using :obj:`~gi.repository.Gdk.Popup.present`. :param parent: the parent surface to attach the surface to :param autohide: whether to hide the surface on outside clicks .. classmethod:: new_toplevel(display: ~gi.repository.Gdk.Display) -> ~gi.repository.Gdk.Surface Creates a new toplevel surface. :param display: the display to create the surface on Methods ------- .. rst-class:: interim-class .. class:: Surface :no-index: .. method:: 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 :obj:`~gi.repository.Gdk.Display.beep`. .. method:: create_cairo_context() -> ~gi.repository.Gdk.CairoContext Creates a new ``GdkCairoContext`` for rendering on ``surface``. .. method:: create_gl_context() -> ~gi.repository.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 :obj:`~gi.repository.Gdk.GLContext.make_current` or :obj:`~gi.repository.Gdk.GLContext.realize`. .. method:: create_similar_surface(content: ~gi.repository.cairo.Content, width: int, height: int) -> ~gi.repository.cairo.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:: 4.12 Create a suitable cairo image surface yourself :param content: the content for the new surface :param width: width of the new surface :param height: height of the new surface .. method:: create_vulkan_context() -> ~gi.repository.Gdk.VulkanContext Sets an error and returns :const:`None`. .. deprecated:: 4.14 GTK does not expose any Vulkan internals. This function is a leftover that was accidentally exposed. .. method:: 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. .. method:: get_cursor() -> ~gi.repository.Gdk.Cursor | None Retrieves a ``GdkCursor`` pointer for the cursor currently set on the ``GdkSurface``. If the return value is :const:`None` then there is no custom cursor set on the surface, and it is using the cursor for its parent surface. Use :obj:`~gi.repository.Gdk.Surface.set_cursor` to unset the cursor of the surface. .. method:: get_device_cursor(device: ~gi.repository.Gdk.Device) -> ~gi.repository.Gdk.Cursor | None Retrieves a ``GdkCursor`` pointer for the ``device`` currently set on the specified ``GdkSurface``. If the return value is :const:`None` then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface. Use :obj:`~gi.repository.Gdk.Surface.set_cursor` to unset the cursor of the surface. :param device: a pointer ``GdkDevice`` .. method:: get_device_position(device: ~gi.repository.Gdk.Device) -> tuple[bool, float, float, ~gi.repository.Gdk.ModifierType] Obtains the current device position and modifier state. The position is given in coordinates relative to the upper left corner of ``surface``. :param device: pointer ``GdkDevice`` to query to .. method:: get_display() -> ~gi.repository.Gdk.Display Gets the ``GdkDisplay`` associated with a ``GdkSurface``. .. method:: get_frame_clock() -> ~gi.repository.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. .. method:: get_height() -> int Returns the height of the given ``surface``. Surface size is reported in ”application pixels”, not ”device pixels” (see :obj:`~gi.repository.Gdk.Surface.get_scale_factor`). .. method:: get_mapped() -> bool Checks whether the surface has been mapped. A surface is mapped with :obj:`~gi.repository.Gdk.Toplevel.present` or :obj:`~gi.repository.Gdk.Popup.present`. .. method:: 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 :obj:`~gi.repository.Gdk.Surface.get_scale_factor`, which returns the next larger integer. The scale may change during the lifetime of the surface. .. versionadded:: 4.12 .. method:: 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. .. method:: get_width() -> int Returns the width of the given ``surface``. Surface size is reported in ”application pixels”, not ”device pixels” (see :obj:`~gi.repository.Gdk.Surface.get_scale_factor`). .. method:: 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() <../gtk4/method.Widget.hide.html>`_. .. method:: is_destroyed() -> bool Check to see if a surface is destroyed. .. method:: queue_render() -> None Forces a :obj:`~gi.repository.Gdk.Surface.signals.render` signal emission for ``surface`` to be scheduled. This function is useful for implementations that track invalid regions on their own. .. method:: request_layout() -> None Request a layout phase from the surface's frame clock. See :obj:`~gi.repository.Gdk.FrameClock.request_phase`. .. method:: set_cursor(cursor: ~gi.repository.Gdk.Cursor | None = None) -> None Sets the default mouse pointer for a ``GdkSurface``. Passing :const:`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 :obj:`~gi.repository.Gdk.Cursor.new_from_name` or :obj:`~gi.repository.Gdk.Cursor.new_from_texture` to create the cursor. To make the cursor invisible, use ``%GDK_BLANK_CURSOR``. :param cursor: a ``GdkCursor`` .. method:: set_device_cursor(device: ~gi.repository.Gdk.Device, cursor: ~gi.repository.Gdk.Cursor) -> None Sets a specific ``GdkCursor`` for a given device when it gets inside ``surface``. Passing :const:`None` for the ``cursor`` argument means that ``surface`` will use the cursor of its parent surface. Most surfaces should use this default. Use :obj:`~gi.repository.Gdk.Cursor.new_from_name` or :obj:`~gi.repository.Gdk.Cursor.new_from_texture` to create the cursor. To make the cursor invisible, use ``%GDK_BLANK_CURSOR``. :param device: a pointer ``GdkDevice`` :param cursor: a ``GdkCursor`` .. method:: set_input_region(region: ~gi.repository.cairo.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 :obj:`~gi.repository.Gdk.Display.supports_input_shapes` to find out if a particular backend supports input regions. :param region: region of surface to be reactive .. method:: set_opaque_region(region: ~gi.repository.cairo.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 <../gtk4/vfunc.Widget.css_changed.html>`_ handler. :param region: a region, or :const:`None` to make the entire surface opaque .. method:: translate_coordinates(to: ~gi.repository.Gdk.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). :param to: the target surface Properties ---------- .. rst-class:: interim-class .. class:: Surface :no-index: .. attribute:: props.cursor :type: ~gi.repository.Gdk.Cursor The mouse pointer for the ``GdkSurface``. .. attribute:: props.display :type: ~gi.repository.Gdk.Display The ``GdkDisplay`` connection of the surface. .. attribute:: props.frame_clock :type: ~gi.repository.Gdk.FrameClock The ``GdkFrameClock`` of the surface. .. attribute:: props.height :type: int The height of the surface, in pixels. .. attribute:: props.mapped :type: bool Whether the surface is mapped. .. attribute:: props.scale :type: float The scale of the surface. .. versionadded:: 4.12 .. attribute:: props.scale_factor :type: int The scale factor of the surface. The scale factor is the next larger integer, compared to :obj:`~gi.repository.Gdk.Surface.props.scale`. .. attribute:: props.width :type: int The width of the surface in pixels. Signals ------- .. rst-class:: interim-class .. class:: Surface.signals :no-index: .. method:: enter_monitor(monitor: ~gi.repository.Gdk.Monitor) -> None Emitted when ``surface`` starts being present on the monitor. :param monitor: the monitor .. method:: event(event: ~gi.repository.Gdk.Event) -> bool Emitted when GDK receives an input event for ``surface``. :param event: an input event .. method:: 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 :func:`~gi.repository.Gdk.Surface.get_scale_factor`). :param width: the current width :param height: the current height .. method:: leave_monitor(monitor: ~gi.repository.Gdk.Monitor) -> None Emitted when ``surface`` stops being present on the monitor. :param monitor: the monitor .. method:: render(region: ~gi.repository.cairo.Region) -> bool Emitted when part of the surface needs to be redrawn. :param region: the region that needs to be redrawn