@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gdk/surface.d.ts

@@ -12,34 +12,267 @@ import { Monitor } from "./monitor.js";
 import * as GObject from "../gobject/index.js";
 import * as cairo from "../cairo/index.js";
 export declare class Surface extends GObject.GObject {
+    /**
+     * Create a new popup surface.
+     *
+     * The surface will be attached to `parent` and can be positioned
+     * relative to it using [method@Gdk.Popup.present].
+     * @param parent - the parent surface to attach the surface to
+     * @param autohide - whether to hide the surface on outside clicks
+     */
     constructor(parent: Surface, autohide: boolean);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new toplevel surface.
+     * @param display - the display to create the surface on
+     */
     static newToplevel(display: Display): Surface;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * 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 [method@Gdk.Display.beep].
+     */
     beep(): void;
+    /**
+     * Creates a new `GdkCairoContext` for rendering on @surface.
+     */
     createCairoContext(): CairoContext;
+    /**
+     * 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 [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize].
+     */
     createGlContext(): GLContext;
+    /**
+     * 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.
+     * @param content - the content for the new surface
+     * @param width - width of the new surface
+     * @param height - height of the new surface
+     */
     createSimilarSurface(content: cairo.Content, width: number, height: number): cairo.Surface;
+    /**
+     * Sets an error and returns %NULL.
+     */
     createVulkanContext(): VulkanContext;
+    /**
+     * 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.
+     */
     destroy(): void;
+    /**
+     * Retrieves a `GdkCursor` pointer for the cursor currently set on the
+     * `GdkSurface`.
+     *
+     * If the return value is %NULL then there is no custom cursor set on
+     * the surface, and it is using the cursor for its parent surface.
+     *
+     * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+     */
     getCursor(): Cursor | null;
+    /**
+     * Retrieves a `GdkCursor` pointer for the `device` currently set on the
+     * specified `GdkSurface`.
+     *
+     * If the return value is %NULL then there is no custom cursor set on the
+     * specified surface, and it is using the cursor for its parent surface.
+     *
+     * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+     * @param device - a pointer `GdkDevice`
+     */
     getDeviceCursor(device: Device): Cursor | null;
+    /**
+     * 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
+     * @param x - return location for the X coordinate of @device
+     * @param y - return location for the Y coordinate of @device
+     * @param mask - return location for the modifier mask
+     */
     getDevicePosition(device: Device, x?: Ref<number> | null, y?: Ref<number> | null, mask?: Ref<ModifierType> | null): boolean;
+    /**
+     * Gets the `GdkDisplay` associated with a `GdkSurface`.
+     */
     getDisplay(): Display;
+    /**
+     * 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.
+     */
     getFrameClock(): FrameClock;
+    /**
+     * Returns the height of the given @surface.
+     *
+     * Surface size is reported in ”application pixels”, not
+     * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
+     */
     getHeight(): number;
+    /**
+     * Checks whether the surface has been mapped.
+     *
+     * A surface is mapped with [method@Gdk.Toplevel.present]
+     * or [method@Gdk.Popup.present].
+     */
     getMapped(): boolean;
+    /**
+     * 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 [method@Gdk.Surface.get_scale_factor], which returns the
+     * next larger integer.
+     *
+     * The scale may change during the lifetime of the surface.
+     */
     getScale(): number;
+    /**
+     * 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.
+     */
     getScaleFactor(): number;
+    /**
+     * Returns the width of the given @surface.
+     *
+     * Surface size is reported in ”application pixels”, not
+     * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
+     */
     getWidth(): number;
+    /**
+     * 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().
+     */
     hide(): void;
+    /**
+     * Check to see if a surface is destroyed.
+     */
     isDestroyed(): boolean;
+    /**
+     * Forces a [signal@Gdk.Surface::render] signal emission for `surface` to be scheduled.
+     *
+     * This function is useful for implementations that track invalid
+     * regions on their own.
+     */
     queueRender(): void;
+    /**
+     * Request a layout phase from the surface's frame clock.
+     *
+     * See [method@Gdk.FrameClock.request_phase].
+     */
     requestLayout(): void;
+    /**
+     * Sets the default mouse pointer for a `GdkSurface`.
+     *
+     * Passing %NULL 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 [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture]
+     * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.
+     * @param cursor - a `GdkCursor`
+     */
     setCursor(cursor?: Cursor | null): void;
+    /**
+     * Sets a specific `GdkCursor` for a given device when it gets inside @surface.
+     *
+     * Passing %NULL for the `cursor` argument means that `surface` will use the
+     * cursor of its parent surface. Most surfaces should use this default.
+     *
+     * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@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`
+     */
     setDeviceCursor(device: Device, cursor: Cursor): void;
+    /**
+     * 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 [method@Gdk.Display.supports_input_shapes] to find out if
+     * a particular backend supports input regions.
+     * @param region - region of surface to be reactive,
+     */
     setInputRegion(region?: cairo.Region | null): void;
+    /**
+     * 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.
+     * @param region - a region, or %NULL to make the entire
+     */
     setOpaqueRegion(region?: cairo.Region | null): void;
+    /**
+     * 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
+     * @param x - coordinates to translate
+     * @param y - coordinates to translate
+     */
     translateCoordinates(to: Surface, x: Ref<number>, y: Ref<number>): boolean;
     connect(signal: "enter-monitor", handler: (self: Surface, monitor: Monitor) => void, after?: boolean): number;
     connect(signal: "event", handler: (self: Surface, event: Event) => boolean, after?: boolean): number;

package/dist/generated/gdk/surface.js

@@ -7,6 +7,17 @@ import { Event } from "./event.js";
 import { Monitor } from "./monitor.js";
 import * as GObject from "../gobject/index.js";
 import * as cairo from "../cairo/index.js";
+/**
+ * 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 [iface@Gdk.Toplevel] or
+ * [iface@Gdk.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.
+ */
 const SIGNAL_META = {
     "enter-monitor": {
         params: [
@@ -44,6 +55,10 @@ export class Surface extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new toplevel surface.
+     * @param display - the display to create the surface on
+     */
     static newToplevel(display) {
         const ptr = call("libgtk-4.so.1", "gdk_surface_new_toplevel", [
             {
@@ -66,6 +81,12 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * 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 [method@Gdk.Display.beep].
+     */
     beep() {
         call("libgtk-4.so.1", "gdk_surface_beep", [
             {
@@ -74,6 +95,9 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a new `GdkCairoContext` for rendering on @surface.
+     */
     createCairoContext() {
         const ptr = call("libgtk-4.so.1", "gdk_surface_create_cairo_context", [
             {
@@ -83,6 +107,14 @@ export class Surface extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return { ptr };
     }
+    /**
+     * 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 [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize].
+     */
     createGlContext() {
         const error = { value: null };
         const ptr = call("libgtk-4.so.1", "gdk_surface_create_gl_context", [
@@ -107,6 +139,26 @@ export class Surface extends GObject.GObject {
         }
         return { ptr };
     }
+    /**
+     * 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.
+     * @param content - the content for the new surface
+     * @param width - width of the new surface
+     * @param height - height of the new surface
+     */
     createSimilarSurface(content, width, height) {
         const ptr = call("libgtk-4.so.1", "gdk_surface_create_similar_surface", [
             {
@@ -133,6 +185,9 @@ export class Surface extends GObject.GObject {
         });
         return getObject(ptr, cairo.Surface);
     }
+    /**
+     * Sets an error and returns %NULL.
+     */
     createVulkanContext() {
         const error = { value: null };
         const ptr = call("libgtk-4.so.1", "gdk_surface_create_vulkan_context", [
@@ -157,6 +212,17 @@ export class Surface extends GObject.GObject {
         }
         return { ptr };
     }
+    /**
+     * 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.
+     */
     destroy() {
         call("libgtk-4.so.1", "gdk_surface_destroy", [
             {
@@ -165,6 +231,15 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves a `GdkCursor` pointer for the cursor currently set on the
+     * `GdkSurface`.
+     *
+     * If the return value is %NULL then there is no custom cursor set on
+     * the surface, and it is using the cursor for its parent surface.
+     *
+     * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+     */
     getCursor() {
         const ptr = call("libgtk-4.so.1", "gdk_surface_get_cursor", [
             {
@@ -176,6 +251,16 @@ export class Surface extends GObject.GObject {
             return null;
         return getObject(ptr, Cursor);
     }
+    /**
+     * Retrieves a `GdkCursor` pointer for the `device` currently set on the
+     * specified `GdkSurface`.
+     *
+     * If the return value is %NULL then there is no custom cursor set on the
+     * specified surface, and it is using the cursor for its parent surface.
+     *
+     * Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
+     * @param device - a pointer `GdkDevice`
+     */
     getDeviceCursor(device) {
         const ptr = call("libgtk-4.so.1", "gdk_surface_get_device_cursor", [
             {
@@ -191,6 +276,16 @@ export class Surface extends GObject.GObject {
             return null;
         return getObject(ptr, Cursor);
     }
+    /**
+     * 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
+     * @param x - return location for the X coordinate of @device
+     * @param y - return location for the Y coordinate of @device
+     * @param mask - return location for the modifier mask
+     */
     getDevicePosition(device, x, y, mask) {
         return call("libgtk-4.so.1", "gdk_surface_get_device_position", [
             {
@@ -221,6 +316,9 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the `GdkDisplay` associated with a `GdkSurface`.
+     */
     getDisplay() {
         const ptr = call("libgtk-4.so.1", "gdk_surface_get_display", [
             {
@@ -230,6 +328,12 @@ export class Surface extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Display);
     }
+    /**
+     * 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.
+     */
     getFrameClock() {
         const ptr = call("libgtk-4.so.1", "gdk_surface_get_frame_clock", [
             {
@@ -239,6 +343,12 @@ export class Surface extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, FrameClock);
     }
+    /**
+     * Returns the height of the given @surface.
+     *
+     * Surface size is reported in ”application pixels”, not
+     * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
+     */
     getHeight() {
         return call("libgtk-4.so.1", "gdk_surface_get_height", [
             {
@@ -247,6 +357,12 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Checks whether the surface has been mapped.
+     *
+     * A surface is mapped with [method@Gdk.Toplevel.present]
+     * or [method@Gdk.Popup.present].
+     */
     getMapped() {
         return call("libgtk-4.so.1", "gdk_surface_get_mapped", [
             {
@@ -255,6 +371,19 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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 [method@Gdk.Surface.get_scale_factor], which returns the
+     * next larger integer.
+     *
+     * The scale may change during the lifetime of the surface.
+     */
     getScale() {
         return call("libgtk-4.so.1", "gdk_surface_get_scale", [
             {
@@ -263,6 +392,19 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "float", size: 64 });
     }
+    /**
+     * 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.
+     */
     getScaleFactor() {
         return call("libgtk-4.so.1", "gdk_surface_get_scale_factor", [
             {
@@ -271,6 +413,12 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the width of the given @surface.
+     *
+     * Surface size is reported in ”application pixels”, not
+     * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]).
+     */
     getWidth() {
         return call("libgtk-4.so.1", "gdk_surface_get_width", [
             {
@@ -279,6 +427,14 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * 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().
+     */
     hide() {
         call("libgtk-4.so.1", "gdk_surface_hide", [
             {
@@ -287,6 +443,9 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Check to see if a surface is destroyed.
+     */
     isDestroyed() {
         return call("libgtk-4.so.1", "gdk_surface_is_destroyed", [
             {
@@ -295,6 +454,12 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Forces a [signal@Gdk.Surface::render] signal emission for `surface` to be scheduled.
+     *
+     * This function is useful for implementations that track invalid
+     * regions on their own.
+     */
     queueRender() {
         call("libgtk-4.so.1", "gdk_surface_queue_render", [
             {
@@ -303,6 +468,11 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Request a layout phase from the surface's frame clock.
+     *
+     * See [method@Gdk.FrameClock.request_phase].
+     */
     requestLayout() {
         call("libgtk-4.so.1", "gdk_surface_request_layout", [
             {
@@ -311,6 +481,17 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the default mouse pointer for a `GdkSurface`.
+     *
+     * Passing %NULL 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 [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture]
+     * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.
+     * @param cursor - a `GdkCursor`
+     */
     setCursor(cursor) {
         call("libgtk-4.so.1", "gdk_surface_set_cursor", [
             {
@@ -324,6 +505,17 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets a specific `GdkCursor` for a given device when it gets inside @surface.
+     *
+     * Passing %NULL for the `cursor` argument means that `surface` will use the
+     * cursor of its parent surface. Most surfaces should use this default.
+     *
+     * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@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`
+     */
     setDeviceCursor(device, cursor) {
         call("libgtk-4.so.1", "gdk_surface_set_device_cursor", [
             {
@@ -340,6 +532,23 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 [method@Gdk.Display.supports_input_shapes] to find out if
+     * a particular backend supports input regions.
+     * @param region - region of surface to be reactive,
+     */
     setInputRegion(region) {
         call("libgtk-4.so.1", "gdk_surface_set_input_region", [
             {
@@ -358,6 +567,24 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param region - a region, or %NULL to make the entire
+     */
     setOpaqueRegion(region) {
         call("libgtk-4.so.1", "gdk_surface_set_opaque_region", [
             {
@@ -376,6 +603,15 @@ export class Surface extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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
+     * @param x - coordinates to translate
+     * @param y - coordinates to translate
+     */
     translateCoordinates(to, x, y) {
         return call("libgtk-4.so.1", "gdk_surface_translate_coordinates", [
             {