@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gdk/display.js

@@ -7,6 +7,22 @@ import { Monitor } from "./monitor.js";
 import { Seat } from "./seat.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A representation of a workstation.
+ *
+ * Their purpose are two-fold:
+ *
+ * - To manage and provide information about input devices (pointers, keyboards, etc)
+ * - To manage and provide information about output devices (monitors, projectors, etc)
+ *
+ * Most of the input device handling has been factored out into separate
+ * [class@Gdk.Seat] objects. Every display has a one or more seats, which
+ * can be accessed with [method@Gdk.Display.get_default_seat] and
+ * [method@Gdk.Display.list_seats].
+ *
+ * Output devices are represented by [class@Gdk.Monitor] objects, which can
+ * be accessed with [method@Gdk.Display.get_monitor_at_surface] and similar APIs.
+ */
 const SIGNAL_META = {
     closed: {
         params: [{ type: { type: "boolean" } }],
@@ -41,6 +57,13 @@ export class Display extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Gets the default `GdkDisplay`.
+     *
+     * This is a convenience function for:
+     *
+     * gdk_display_manager_get_default_display (gdk_display_manager_get ())
+     */
     static getDefault() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_default", [], {
             type: "gobject",
@@ -48,6 +71,12 @@ export class Display extends GObject.GObject {
         });
         return getObject(ptr, Display);
     }
+    /**
+     * Opens a display.
+     *
+     * If opening the display fails, `NULL` is returned.
+     * @param displayName - the name of the display to open
+     */
     static open(displayName) {
         const ptr = call("libgtk-4.so.1", "gdk_display_open", [
             {
@@ -58,6 +87,9 @@ export class Display extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Display);
     }
+    /**
+     * Emits a short beep on @display
+     */
     beep() {
         call("libgtk-4.so.1", "gdk_display_beep", [
             {
@@ -66,6 +98,11 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Closes the connection to the windowing system for the given display.
+     *
+     * This cleans up associated resources.
+     */
     close() {
         call("libgtk-4.so.1", "gdk_display_close", [
             {
@@ -74,6 +111,17 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a new `GdkGLContext` for the `GdkDisplay`.
+     *
+     * The context is disconnected from any particular surface or surface
+     * and cannot be used to draw to any surface. It can only be used to
+     * draw to non-surface framebuffers like textures.
+     *
+     * 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_display_create_gl_context", [
@@ -98,6 +146,10 @@ export class Display extends GObject.GObject {
         }
         return { ptr };
     }
+    /**
+     * Returns %TRUE if there is an ongoing grab on `device` for @display.
+     * @param device - a `GdkDevice`
+     */
     deviceIsGrabbed(device) {
         return call("libgtk-4.so.1", "gdk_display_device_is_grabbed", [
             {
@@ -110,6 +162,18 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Flushes any requests queued for the windowing system.
+     *
+     * This happens automatically when the main loop blocks waiting for new events,
+     * but if your application is drawing without returning control to the main loop,
+     * you may need to call this function explicitly. A common case where this function
+     * needs to be called is when an application is executing drawing commands
+     * from a thread other than the thread where the main loop is running.
+     *
+     * This is most useful for X11. On windowing systems where requests are
+     * handled synchronously, this function will do nothing.
+     */
     flush() {
         call("libgtk-4.so.1", "gdk_display_flush", [
             {
@@ -118,6 +182,10 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns a `GdkAppLaunchContext` suitable for launching
+     * applications on the given display.
+     */
     getAppLaunchContext() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_app_launch_context", [
             {
@@ -127,6 +195,9 @@ export class Display extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, AppLaunchContext);
     }
+    /**
+     * Gets the clipboard used for copy/paste operations.
+     */
     getClipboard() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_clipboard", [
             {
@@ -136,6 +207,12 @@ export class Display extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Clipboard);
     }
+    /**
+     * Returns the default `GdkSeat` for this display.
+     *
+     * Note that a display may not have a seat. In this case,
+     * this function will return %NULL.
+     */
     getDefaultSeat() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_default_seat", [
             {
@@ -147,6 +224,19 @@ export class Display extends GObject.GObject {
             return null;
         return getObject(ptr, Seat);
     }
+    /**
+     * Returns the dma-buf formats that are supported on this display.
+     *
+     * GTK may use OpenGL or Vulkan to support some formats.
+     * Calling this function will then initialize them if they aren't yet.
+     *
+     * The formats returned by this function can be used for negotiating
+     * buffer formats with producers such as v4l, pipewire or GStreamer.
+     *
+     * To learn more about dma-bufs, see [class@Gdk.DmabufTextureBuilder].
+     *
+     * This function is threadsafe. It can be called from any thread.
+     */
     getDmabufFormats() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_dmabuf_formats", [
             {
@@ -161,6 +251,10 @@ export class Display extends GObject.GObject {
         });
         return getObject(ptr, DmabufFormats);
     }
+    /**
+     * Gets the monitor in which the largest area of `surface` resides.
+     * @param surface - a `GdkSurface`
+     */
     getMonitorAtSurface(surface) {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_monitor_at_surface", [
             {
@@ -176,6 +270,15 @@ export class Display extends GObject.GObject {
             return null;
         return getObject(ptr, Monitor);
     }
+    /**
+     * Gets the list of monitors associated with this display.
+     *
+     * Subsequent calls to this function will always return the
+     * same list for the same display.
+     *
+     * You can listen to the GListModel::items-changed signal on
+     * this list to monitor changes to the monitor of this display.
+     */
     getMonitors() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_monitors", [
             {
@@ -185,6 +288,9 @@ export class Display extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Gio.ListModel);
     }
+    /**
+     * Gets the name of the display.
+     */
     getName() {
         return call("libgtk-4.so.1", "gdk_display_get_name", [
             {
@@ -193,6 +299,12 @@ export class Display extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the clipboard used for the primary selection.
+     *
+     * On backends where the primary clipboard is not supported natively,
+     * GDK emulates this clipboard locally.
+     */
     getPrimaryClipboard() {
         const ptr = call("libgtk-4.so.1", "gdk_display_get_primary_clipboard", [
             {
@@ -202,6 +314,12 @@ export class Display extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Clipboard);
     }
+    /**
+     * Retrieves a desktop-wide setting such as double-click time
+     * for the @display.
+     * @param name - the name of the setting
+     * @param value - location to store the value of the setting
+     */
     getSetting(name, value) {
         return call("libgtk-4.so.1", "gdk_display_get_setting", [
             {
@@ -223,6 +341,10 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the startup notification ID for a Wayland display, or %NULL
+     * if no ID has been defined.
+     */
     getStartupNotificationId() {
         return call("libgtk-4.so.1", "gdk_display_get_startup_notification_id", [
             {
@@ -231,6 +353,9 @@ export class Display extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Finds out if the display has been closed.
+     */
     isClosed() {
         return call("libgtk-4.so.1", "gdk_display_is_closed", [
             {
@@ -239,6 +364,18 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether surfaces can reasonably be expected to have
+     * their alpha channel drawn correctly on the screen.
+     *
+     * Check [method@Gdk.Display.is_rgba] for whether the display
+     * supports an alpha channel.
+     *
+     * On X11 this function returns whether a compositing manager is
+     * compositing on @display.
+     *
+     * On modern displays, this value is always %TRUE.
+     */
     isComposited() {
         return call("libgtk-4.so.1", "gdk_display_is_composited", [
             {
@@ -247,6 +384,19 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether surfaces on this `display` are created with an
+     * alpha channel.
+     *
+     * Even if a %TRUE is returned, it is possible that the
+     * surface’s alpha channel won’t be honored when displaying the
+     * surface on the screen: in particular, for X an appropriate
+     * windowing manager and compositing manager must be running to
+     * provide appropriate display. Use [method@Gdk.Display.is_composited]
+     * to check if that is the case.
+     *
+     * On modern displays, this value is always %TRUE.
+     */
     isRgba() {
         return call("libgtk-4.so.1", "gdk_display_is_rgba", [
             {
@@ -255,6 +405,9 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the list of seats known to @display.
+     */
     listSeats() {
         const ptrs = call("libgtk-4.so.1", "gdk_display_list_seats", [
             {
@@ -269,6 +422,21 @@ export class Display extends GObject.GObject {
         });
         return ptrs.map((ptr) => getObject(ptr, Seat));
     }
+    /**
+     * Returns the keyvals bound to @keycode.
+     *
+     * The Nth `GdkKeymapKey` in `keys` is bound to the Nth keyval in @keyvals.
+     *
+     * When a keycode is pressed by the user, the keyval from
+     * this list of entries is selected by considering the effective
+     * keyboard group and level.
+     *
+     * Free the returned arrays with g_free().
+     * @param keycode - a keycode
+     * @param keys - return
+     * @param keyvals - return
+     * @param nEntries - length of `keys` and @keyvals
+     */
     mapKeycode(keycode, nEntries, keys, keyvals) {
         return call("libgtk-4.so.1", "gdk_display_map_keycode", [
             {
@@ -310,6 +478,26 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Obtains a list of keycode/group/level combinations that will
+     * generate @keyval.
+     *
+     * Groups and levels are two kinds of keyboard mode; in general, the level
+     * determines whether the top or bottom symbol on a key is used, and the
+     * group determines whether the left or right symbol is used.
+     *
+     * On US keyboards, the shift key changes the keyboard level, and there
+     * are no groups. A group switch key might convert a keyboard between
+     * Hebrew to English modes, for example.
+     *
+     * `GdkEventKey` contains a %group field that indicates the active
+     * keyboard group. The level is computed from the modifier mask.
+     *
+     * The returned array should be freed with g_free().
+     * @param keyval - a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
+     * @param keys - return location
+     * @param nKeys - return location for number of elements in returned array
+     */
     mapKeyval(keyval, keys, nKeys) {
         return call("libgtk-4.so.1", "gdk_display_map_keyval", [
             {
@@ -339,6 +527,16 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Indicates to the GUI environment that the application has
+     * finished loading, using a given identifier.
+     *
+     * GTK will call this function automatically for GtkWindow
+     * with custom startup-notification identifier unless
+     * gtk_window_set_auto_startup_notification()
+     * is called to disable that feature.
+     * @param startupId - a startup-notification identifier, for which
+     */
     notifyStartupComplete(startupId) {
         call("libgtk-4.so.1", "gdk_display_notify_startup_complete", [
             {
@@ -351,6 +549,22 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Checks that OpenGL is available for `self` and ensures that it is
+     * properly initialized.
+     * When this fails, an `error` will be set describing the error and this
+     * function returns %FALSE.
+     *
+     * Note that even if this function succeeds, creating a `GdkGLContext`
+     * may still fail.
+     *
+     * This function is idempotent. Calling it multiple times will just
+     * return the same value or error.
+     *
+     * You never need to call this function, GDK will call it automatically
+     * as needed. But you can use it as a check when setting up code that
+     * might make use of OpenGL.
+     */
     prepareGl() {
         const error = { value: null };
         const result = call("libgtk-4.so.1", "gdk_display_prepare_gl", [
@@ -375,6 +589,10 @@ export class Display extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Adds the given event to the event queue for @display.
+     * @param event - a `GdkEvent`
+     */
     putEvent(event) {
         call("libgtk-4.so.1", "gdk_display_put_event", [
             {
@@ -387,6 +605,14 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns %TRUE if the display supports input shapes.
+     *
+     * This means that [method@Gdk.Surface.set_input_region] can
+     * be used to modify the input shape of surfaces on @display.
+     *
+     * On modern displays, this value is always %TRUE.
+     */
     supportsInputShapes() {
         return call("libgtk-4.so.1", "gdk_display_supports_input_shapes", [
             {
@@ -395,6 +621,12 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether it's possible for a surface to draw outside of the window area.
+     *
+     * If %TRUE is returned the application decides if it wants to draw shadows.
+     * If %FALSE is returned, the compositor decides if it wants to draw shadows.
+     */
     supportsShadowWidth() {
         return call("libgtk-4.so.1", "gdk_display_supports_shadow_width", [
             {
@@ -403,6 +635,18 @@ export class Display extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Flushes any requests queued for the windowing system and waits until all
+     * requests have been handled.
+     *
+     * This is often used for making sure that the display is synchronized
+     * with the current state of the program. Calling [method@Gdk.Display.sync]
+     * before [method@GdkX11.Display.error_trap_pop] makes sure that any errors
+     * generated from earlier requests are handled before the error trap is removed.
+     *
+     * This is most useful for X11. On windowing systems where requests are
+     * handled synchronously, this function will do nothing.
+     */
     sync() {
         call("libgtk-4.so.1", "gdk_display_sync", [
             {
@@ -411,6 +655,34 @@ export class Display extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Translates the contents of a `GdkEventKey` into a keyval, effective group,
+     * and level.
+     *
+     * Modifiers that affected the translation and are thus unavailable for
+     * application use are returned in @consumed_modifiers.
+     *
+     * The `effective_group` is the group that was actually used for the
+     * translation; some keys such as Enter are not affected by the active
+     * keyboard group. The `level` is derived from @state.
+     *
+     * `consumed_modifiers` gives modifiers that should be masked out
+     * from `state` when comparing this key press to a keyboard shortcut.
+     * For instance, on a US keyboard, the `plus` symbol is shifted, so
+     * when comparing a key press to a `<Control>plus` accelerator `<Shift>`
+     * should be masked out.
+     *
+     * This function should rarely be needed, since `GdkEventKey` already
+     * contains the translated keyval. It is exported for the benefit of
+     * virtualized test environments.
+     * @param keycode - a keycode
+     * @param state - a modifier state
+     * @param group - active keyboard group
+     * @param keyval - return location for keyval
+     * @param effectiveGroup - return location for effective group
+     * @param level - return location for level
+     * @param consumed - return location for modifiers that were used
+     */
     translateKey(keycode, state, group, keyval, effectiveGroup, level, consumed) {
         return call("libgtk-4.so.1", "gdk_display_translate_key", [
             {

package/dist/generated/gdk/dmabuf-formats.d.ts

@@ -1,12 +1,67 @@
 import { Ref } from "@gtkx/native";
+/**
+ * Provides information about supported DMA buffer formats.
+ *
+ * You can query whether a given format is supported with
+ * [method@Gdk.DmabufFormats.contains] and you can iterate
+ * over the list of all supported formats with
+ * [method@Gdk.DmabufFormats.get_n_formats] and
+ * [method@Gdk.DmabufFormats.get_format].
+ *
+ * The list of supported formats is sorted by preference,
+ * with the best formats coming first.
+ *
+ * The list may contains (format, modifier) pairs where the modifier
+ * is `DMA_FORMAT_MOD_INVALID`, indicating that **_implicit modifiers_**
+ * may be used with this format.
+ *
+ * See [class@Gdk.DmabufTextureBuilder] for more information
+ * about DMA buffers.
+ *
+ * Note that DMA buffers only exist on Linux.
+ */
 export declare class DmabufFormats {
     ptr: unknown;
     constructor();
     protected createPtr(_init: Record<string, unknown>): unknown;
+    /**
+     * Returns whether a given format is contained in @formats.
+     * @param fourcc - a format code
+     * @param modifier - a format modifier
+     */
     contains(fourcc: number, modifier: number): boolean;
+    /**
+     * Returns whether `formats1` and `formats2` contain the
+     * same dmabuf formats, in the same order.
+     * @param formats2 - another `GdkDmabufFormats`
+     */
     equal(formats2?: DmabufFormats | null): boolean;
+    /**
+     * Gets the fourcc code and modifier for a format
+     * that is contained in @formats.
+     * @param idx - the index of the format to return
+     * @param fourcc - return location for the format code
+     * @param modifier - return location for the format modifier
+     */
     getFormat(idx: number, fourcc: Ref<number>, modifier: Ref<number>): void;
+    /**
+     * Returns the number of formats that the `formats` object
+     * contains.
+     *
+     * Note that DMA buffers are a Linux concept, so on other
+     * platforms, [method@Gdk.DmabufFormats.get_n_formats] will
+     * always return zero.
+     */
     getNFormats(): number;
+    /**
+     * Increases the reference count of @formats.
+     */
     ref(): DmabufFormats;
+    /**
+     * Decreases the reference count of @formats.
+     *
+     * When the reference count reaches zero,
+     * the object is freed.
+     */
     unref(): void;
 }

package/dist/generated/gdk/dmabuf-formats.js

@@ -1,5 +1,26 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * Provides information about supported DMA buffer formats.
+ *
+ * You can query whether a given format is supported with
+ * [method@Gdk.DmabufFormats.contains] and you can iterate
+ * over the list of all supported formats with
+ * [method@Gdk.DmabufFormats.get_n_formats] and
+ * [method@Gdk.DmabufFormats.get_format].
+ *
+ * The list of supported formats is sorted by preference,
+ * with the best formats coming first.
+ *
+ * The list may contains (format, modifier) pairs where the modifier
+ * is `DMA_FORMAT_MOD_INVALID`, indicating that **_implicit modifiers_**
+ * may be used with this format.
+ *
+ * See [class@Gdk.DmabufTextureBuilder] for more information
+ * about DMA buffers.
+ *
+ * Note that DMA buffers only exist on Linux.
+ */
 export class DmabufFormats {
     ptr;
     constructor() {
@@ -8,6 +29,11 @@ export class DmabufFormats {
     createPtr(_init) {
         return null;
     }
+    /**
+     * Returns whether a given format is contained in @formats.
+     * @param fourcc - a format code
+     * @param modifier - a format modifier
+     */
     contains(fourcc, modifier) {
         return call("libgtk-4.so.1", "gdk_dmabuf_formats_contains", [
             {
@@ -24,6 +50,11 @@ export class DmabufFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether `formats1` and `formats2` contain the
+     * same dmabuf formats, in the same order.
+     * @param formats2 - another `GdkDmabufFormats`
+     */
     equal(formats2) {
         return call("libgtk-4.so.1", "gdk_dmabuf_formats_equal", [
             {
@@ -42,6 +73,13 @@ export class DmabufFormats {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the fourcc code and modifier for a format
+     * that is contained in @formats.
+     * @param idx - the index of the format to return
+     * @param fourcc - return location for the format code
+     * @param modifier - return location for the format modifier
+     */
     getFormat(idx, fourcc, modifier) {
         call("libgtk-4.so.1", "gdk_dmabuf_formats_get_format", [
             {
@@ -68,6 +106,14 @@ export class DmabufFormats {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the number of formats that the `formats` object
+     * contains.
+     *
+     * Note that DMA buffers are a Linux concept, so on other
+     * platforms, [method@Gdk.DmabufFormats.get_n_formats] will
+     * always return zero.
+     */
     getNFormats() {
         return call("libgtk-4.so.1", "gdk_dmabuf_formats_get_n_formats", [
             {
@@ -76,6 +122,9 @@ export class DmabufFormats {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Increases the reference count of @formats.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gdk_dmabuf_formats_ref", [
             {
@@ -90,6 +139,12 @@ export class DmabufFormats {
         });
         return getObject(ptr, DmabufFormats);
     }
+    /**
+     * Decreases the reference count of @formats.
+     *
+     * When the reference count reaches zero,
+     * the object is freed.
+     */
     unref() {
         call("libgtk-4.so.1", "gdk_dmabuf_formats_unref", [
             {