@gtkx/ffi 0.1.44 → 0.1.46

package/dist/generated/gdk/event-sequence.d.ts

@@ -1,3 +1,4 @@
+/** An opaque type representing a sequence of related events. */
 export declare class EventSequence {
     ptr: unknown;
     constructor();

package/dist/generated/gdk/event-sequence.js

@@ -1,3 +1,4 @@
+/** An opaque type representing a sequence of related events. */
 export class EventSequence {
     ptr;
     constructor() {

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

@@ -6,28 +6,170 @@ import { DeviceTool } from "./device-tool.js";
 import { Display } from "./display.js";
 import { Seat } from "./seat.js";
 import { Surface } from "./surface.js";
+/**
+ * Represents windowing system events.
+ *
+ * In GTK applications the events are handled automatically by toplevel
+ * widgets and passed on to the event controllers of appropriate widgets,
+ * so using `GdkEvent` and its related API is rarely needed.
+ *
+ * `GdkEvent` structs are immutable.
+ */
 export declare class Event {
     ptr: unknown;
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns the relative angle from `event1` to @event2.
+     *
+     * The relative angle is the angle between the X axis and the line
+     * through both events' positions. The rotation direction for positive
+     * angles is from the positive X axis towards the positive Y axis.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param angle - return location for the relative angle between both events
+     */
     GetAngle(event2: Event, angle: Ref<number>): boolean;
+    /**
+     * Returns the point halfway between the events' positions.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param x - return location for the X coordinate of the center
+     * @param y - return location for the Y coordinate of the center
+     */
     GetCenter(event2: Event, x: Ref<number>, y: Ref<number>): boolean;
+    /**
+     * Returns the distance between the event locations.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param distance - return location for the distance
+     */
     GetDistance(event2: Event, distance: Ref<number>): boolean;
+    /**
+     * Extracts all axis values from an event.
+     *
+     * To find out which axes are used, use [method@Gdk.DeviceTool.get_axes]
+     * on the device tool returned by [method@Gdk.Event.get_device_tool].
+     * @param axes - the array of values for all axes
+     * @param nAxes - the length of array
+     */
     getAxes(axes: Ref<number[]>, nAxes: Ref<number>): boolean;
+    /**
+     * Extract the axis value for a particular axis use from
+     * an event structure.
+     *
+     * To find out which axes are used, use [method@Gdk.DeviceTool.get_axes]
+     * on the device tool returned by [method@Gdk.Event.get_device_tool].
+     * @param axisUse - the axis use to look for
+     * @param value - location to store the value found
+     */
     getAxis(axisUse: AxisUse, value: Ref<number>): boolean;
+    /**
+     * Returns the device of an event.
+     */
     getDevice(): Device | null;
+    /**
+     * Returns a `GdkDeviceTool` representing the tool that
+     * caused the event.
+     *
+     * If the was not generated by a device that supports
+     * different tools (such as a tablet), this function will
+     * return %NULL.
+     *
+     * Note: the `GdkDeviceTool` will be constant during
+     * the application lifetime, if settings must be stored
+     * persistently across runs, see [method@Gdk.DeviceTool.get_serial].
+     */
     getDeviceTool(): DeviceTool | null;
+    /**
+     * Retrieves the display associated to the @event.
+     */
     getDisplay(): Display | null;
+    /**
+     * Returns the event sequence to which the event belongs.
+     *
+     * Related touch events are connected in a sequence. Other
+     * events typically don't have event sequence information.
+     */
     getEventSequence(): EventSequence;
+    /**
+     * Retrieves the type of the event.
+     */
     getEventType(): EventType;
+    /**
+     * Retrieves the history of the device that `event` is for, as a list of
+     * time and coordinates.
+     *
+     * The history includes positions that are not delivered as separate events
+     * to the application because they occurred in the same frame as @event.
+     *
+     * Note that only motion and scroll events record history, and motion
+     * events do it only if one of the mouse buttons is down, or the device
+     * has a tool.
+     * @param outNCoords - Return location for the length of the returned array
+     */
     getHistory(outNCoords: Ref<number>): number[] | null;
+    /**
+     * Returns the modifier state field of an event.
+     */
     getModifierState(): ModifierType;
+    /**
+     * Returns whether this event is an 'emulated' pointer event.
+     *
+     * Emulated pointer events typically originate from a touch events.
+     */
     getPointerEmulated(): boolean;
+    /**
+     * Extract the event surface relative x/y coordinates from an event.
+     *
+     * This position is in surface coordinates.
+     * @param x - location to put event surface x coordinate
+     * @param y - location to put event surface y coordinate
+     */
     getPosition(x: Ref<number>, y: Ref<number>): boolean;
+    /**
+     * Returns the seat that originated the event.
+     */
     getSeat(): Seat | null;
+    /**
+     * Extracts the surface associated with an event.
+     */
     getSurface(): Surface | null;
+    /**
+     * Returns the timestamp of @event.
+     *
+     * Not all events have timestamps. In that case, this function
+     * returns %GDK_CURRENT_TIME.
+     */
     getTime(): number;
+    /**
+     * Increase the ref count of @event.
+     */
     ref(): Event;
+    /**
+     * Returns whether a `GdkEvent` should trigger a context menu,
+     * according to platform conventions.
+     *
+     * The right mouse button typically triggers context menus.
+     * On macOS, Control+left mouse button also triggers.
+     *
+     * This function should always be used instead of simply checking for
+     *
+     * ```c
+     * event->button == GDK_BUTTON_SECONDARY
+     * ```
+     */
     triggersContextMenu(): boolean;
+    /**
+     * Decrease the ref count of @event.
+     *
+     * If the last reference is dropped, the structure is freed.
+     */
     unref(): void;
 }

package/dist/generated/gdk/event.js

@@ -6,6 +6,15 @@ import { DeviceTool } from "./device-tool.js";
 import { Display } from "./display.js";
 import { Seat } from "./seat.js";
 import { Surface } from "./surface.js";
+/**
+ * Represents windowing system events.
+ *
+ * In GTK applications the events are handled automatically by toplevel
+ * widgets and passed on to the event controllers of appropriate widgets,
+ * so using `GdkEvent` and its related API is rarely needed.
+ *
+ * `GdkEvent` structs are immutable.
+ */
 export class Event {
     ptr;
     constructor(...args) {
@@ -14,6 +23,18 @@ export class Event {
     createPtr(_args) {
         return null;
     }
+    /**
+     * Returns the relative angle from `event1` to @event2.
+     *
+     * The relative angle is the angle between the X axis and the line
+     * through both events' positions. The rotation direction for positive
+     * angles is from the positive X axis towards the positive Y axis.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param angle - return location for the relative angle between both events
+     */
     GetAngle(event2, angle) {
         return call("libgtk-4.so.1", "gdk_events_get_angle", [
             {
@@ -30,6 +51,15 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the point halfway between the events' positions.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param x - return location for the X coordinate of the center
+     * @param y - return location for the Y coordinate of the center
+     */
     GetCenter(event2, x, y) {
         return call("libgtk-4.so.1", "gdk_events_get_center", [
             {
@@ -50,6 +80,14 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the distance between the event locations.
+     *
+     * This assumes that both events have X/Y information.
+     * If not, this function returns %FALSE.
+     * @param event2 - second `GdkEvent`
+     * @param distance - return location for the distance
+     */
     GetDistance(event2, distance) {
         return call("libgtk-4.so.1", "gdk_events_get_distance", [
             {
@@ -66,6 +104,14 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Extracts all axis values from an event.
+     *
+     * To find out which axes are used, use [method@Gdk.DeviceTool.get_axes]
+     * on the device tool returned by [method@Gdk.Event.get_device_tool].
+     * @param axes - the array of values for all axes
+     * @param nAxes - the length of array
+     */
     getAxes(axes, nAxes) {
         return call("libgtk-4.so.1", "gdk_event_get_axes", [
             {
@@ -88,6 +134,15 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Extract the axis value for a particular axis use from
+     * an event structure.
+     *
+     * To find out which axes are used, use [method@Gdk.DeviceTool.get_axes]
+     * on the device tool returned by [method@Gdk.Event.get_device_tool].
+     * @param axisUse - the axis use to look for
+     * @param value - location to store the value found
+     */
     getAxis(axisUse, value) {
         return call("libgtk-4.so.1", "gdk_event_get_axis", [
             {
@@ -104,6 +159,9 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the device of an event.
+     */
     getDevice() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_device", [
             {
@@ -115,6 +173,18 @@ export class Event {
             return null;
         return getObject(ptr, Device);
     }
+    /**
+     * Returns a `GdkDeviceTool` representing the tool that
+     * caused the event.
+     *
+     * If the was not generated by a device that supports
+     * different tools (such as a tablet), this function will
+     * return %NULL.
+     *
+     * Note: the `GdkDeviceTool` will be constant during
+     * the application lifetime, if settings must be stored
+     * persistently across runs, see [method@Gdk.DeviceTool.get_serial].
+     */
     getDeviceTool() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_device_tool", [
             {
@@ -126,6 +196,9 @@ export class Event {
             return null;
         return getObject(ptr, DeviceTool);
     }
+    /**
+     * Retrieves the display associated to the @event.
+     */
     getDisplay() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_display", [
             {
@@ -137,6 +210,12 @@ export class Event {
             return null;
         return getObject(ptr, Display);
     }
+    /**
+     * Returns the event sequence to which the event belongs.
+     *
+     * Related touch events are connected in a sequence. Other
+     * events typically don't have event sequence information.
+     */
     getEventSequence() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_event_sequence", [
             {
@@ -151,6 +230,9 @@ export class Event {
         });
         return getObject(ptr, EventSequence);
     }
+    /**
+     * Retrieves the type of the event.
+     */
     getEventType() {
         return call("libgtk-4.so.1", "gdk_event_get_event_type", [
             {
@@ -159,6 +241,18 @@ export class Event {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the history of the device that `event` is for, as a list of
+     * time and coordinates.
+     *
+     * The history includes positions that are not delivered as separate events
+     * to the application because they occurred in the same frame as @event.
+     *
+     * Note that only motion and scroll events record history, and motion
+     * events do it only if one of the mouse buttons is down, or the device
+     * has a tool.
+     * @param outNCoords - Return location for the length of the returned array
+     */
     getHistory(outNCoords) {
         return call("libgtk-4.so.1", "gdk_event_get_history", [
             {
@@ -174,6 +268,9 @@ export class Event {
             },
         ], { type: "array", itemType: { type: "int", size: 64, unsigned: true } });
     }
+    /**
+     * Returns the modifier state field of an event.
+     */
     getModifierState() {
         return call("libgtk-4.so.1", "gdk_event_get_modifier_state", [
             {
@@ -182,6 +279,11 @@ export class Event {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether this event is an 'emulated' pointer event.
+     *
+     * Emulated pointer events typically originate from a touch events.
+     */
     getPointerEmulated() {
         return call("libgtk-4.so.1", "gdk_event_get_pointer_emulated", [
             {
@@ -190,6 +292,13 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Extract the event surface relative x/y coordinates from an event.
+     *
+     * This position is in surface coordinates.
+     * @param x - location to put event surface x coordinate
+     * @param y - location to put event surface y coordinate
+     */
     getPosition(x, y) {
         return call("libgtk-4.so.1", "gdk_event_get_position", [
             {
@@ -206,6 +315,9 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the seat that originated the event.
+     */
     getSeat() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_seat", [
             {
@@ -217,6 +329,9 @@ export class Event {
             return null;
         return getObject(ptr, Seat);
     }
+    /**
+     * Extracts the surface associated with an event.
+     */
     getSurface() {
         const ptr = call("libgtk-4.so.1", "gdk_event_get_surface", [
             {
@@ -228,6 +343,12 @@ export class Event {
             return null;
         return getObject(ptr, Surface);
     }
+    /**
+     * Returns the timestamp of @event.
+     *
+     * Not all events have timestamps. In that case, this function
+     * returns %GDK_CURRENT_TIME.
+     */
     getTime() {
         return call("libgtk-4.so.1", "gdk_event_get_time", [
             {
@@ -236,6 +357,9 @@ export class Event {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Increase the ref count of @event.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gdk_event_ref", [
             {
@@ -245,6 +369,19 @@ export class Event {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Event);
     }
+    /**
+     * Returns whether a `GdkEvent` should trigger a context menu,
+     * according to platform conventions.
+     *
+     * The right mouse button typically triggers context menus.
+     * On macOS, Control+left mouse button also triggers.
+     *
+     * This function should always be used instead of simply checking for
+     *
+     * ```c
+     * event->button == GDK_BUTTON_SECONDARY
+     * ```
+     */
     triggersContextMenu() {
         return call("libgtk-4.so.1", "gdk_event_triggers_context_menu", [
             {
@@ -253,6 +390,11 @@ export class Event {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Decrease the ref count of @event.
+     *
+     * If the last reference is dropped, the structure is freed.
+     */
     unref() {
         call("libgtk-4.so.1", "gdk_event_unref", [
             {

package/dist/generated/gdk/file-list.d.ts

@@ -1,8 +1,28 @@
 import * as Gio from "../gio/index.js";
+/** An opaque type representing a list of files. */
 export declare class FileList {
     ptr: unknown;
+    /**
+     * Creates a new `GdkFileList` for the given array of files.
+     *
+     * This function is meant to be used by language bindings.
+     * @param files - the files to add to the list
+     * @param nFiles - the number of files in the array
+     */
     constructor(files: Gio.File[], nFiles: number);
+    /**
+     * Creates a new files list container from a singly linked list of
+     * `GFile` instances.
+     *
+     * This function is meant to be used by language bindings
+     * @param files - a list of files
+     */
     static listNewFromList(files: Gio.File[]): FileList;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Retrieves the list of files inside a `GdkFileList`.
+     *
+     * This function is meant for language bindings.
+     */
     getFiles(): Gio.File[];
 }

package/dist/generated/gdk/file-list.js

@@ -1,12 +1,27 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as Gio from "../gio/index.js";
+/** An opaque type representing a list of files. */
 export class FileList {
     ptr;
+    /**
+     * Creates a new `GdkFileList` for the given array of files.
+     *
+     * This function is meant to be used by language bindings.
+     * @param files - the files to add to the list
+     * @param nFiles - the number of files in the array
+     */
     constructor(files, nFiles) {
         const _args = [files, nFiles];
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a new files list container from a singly linked list of
+     * `GFile` instances.
+     *
+     * This function is meant to be used by language bindings
+     * @param files - a list of files
+     */
     static listNewFromList(files) {
         const ptr = call("libgtk-4.so.1", "gdk_file_list_new_from_list", [
             {
@@ -33,6 +48,11 @@ export class FileList {
             },
         ], { type: "boxed", borrowed: true, innerType: "GdkFileList" });
     }
+    /**
+     * Retrieves the list of files inside a `GdkFileList`.
+     *
+     * This function is meant for language bindings.
+     */
     getFiles() {
         const ptrs = call("libgtk-4.so.1", "gdk_file_list_get_files", [
             {

package/dist/generated/gdk/focus-event.d.ts

@@ -1,6 +1,11 @@
 import { Event } from "./event.js";
+/** An event related to a keyboard focus change. */
 export declare class FocusEvent extends Event {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Extracts whether this event is about focus entering or
+     * leaving the surface.
+     */
     getIn(): boolean;
 }

package/dist/generated/gdk/focus-event.js

@@ -1,5 +1,6 @@
 import { call } from "@gtkx/native";
 import { Event } from "./event.js";
+/** An event related to a keyboard focus change. */
 export class FocusEvent extends Event {
     constructor(...args) {
         super(...args);
@@ -15,6 +16,10 @@ export class FocusEvent extends Event {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Extracts whether this event is about focus entering or
+     * leaving the surface.
+     */
     getIn() {
         return call("libgtk-4.so.1", "gdk_focus_event_get_in", [
             {

package/dist/generated/gdk/frame-clock.d.ts

@@ -5,15 +5,94 @@ import * as GObject from "../gobject/index.js";
 export declare class FrameClock extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Starts updates for an animation.
+     *
+     * Until a matching call to [method@Gdk.FrameClock.end_updating] is made,
+     * the frame clock will continually request a new frame with the
+     * %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple
+     * times and frames will be requested until gdk_frame_clock_end_updating()
+     * is called the same number of times.
+     */
     beginUpdating(): void;
+    /**
+     * Stops updates for an animation.
+     *
+     * See the documentation for [method@Gdk.FrameClock.begin_updating].
+     */
     endUpdating(): void;
+    /**
+     * Gets the frame timings for the current frame.
+     */
     getCurrentTimings(): FrameTimings | null;
+    /**
+     * Calculates the current frames-per-second, based on the
+     * frame timings of @frame_clock.
+     */
     getFps(): number;
+    /**
+     * `GdkFrameClock` maintains a 64-bit counter that increments for
+     * each frame drawn.
+     */
     getFrameCounter(): number;
+    /**
+     * Gets the time that should currently be used for animations.
+     *
+     * Inside the processing of a frame, it’s the time used to compute the
+     * animation position of everything in a frame. Outside of a frame, it's
+     * the time of the conceptual “previous frame,” which may be either
+     * the actual previous frame time, or if that’s too old, an updated
+     * time.
+     */
     getFrameTime(): number;
+    /**
+     * Returns the frame counter for the oldest frame available in history.
+     *
+     * `GdkFrameClock` internally keeps a history of `GdkFrameTimings`
+     * objects for recent frames that can be retrieved with
+     * [method@Gdk.FrameClock.get_timings]. The set of stored frames
+     * is the set from the counter values given by
+     * [method@Gdk.FrameClock.get_history_start] and
+     * [method@Gdk.FrameClock.get_frame_counter], inclusive.
+     */
     getHistoryStart(): number;
+    /**
+     * Predicts a presentation time, based on history.
+     *
+     * Using the frame history stored in the frame clock, finds the last
+     * known presentation time and refresh interval, and assuming that
+     * presentation times are separated by the refresh interval,
+     * predicts a presentation time that is a multiple of the refresh
+     * interval after the last presentation time, and later than @base_time.
+     * @param baseTime - base time for determining a presentaton time
+     * @param refreshIntervalReturn - a location to store the
+     * @param presentationTimeReturn - a location to store the next
+     */
     getRefreshInfo(baseTime: number, presentationTimeReturn: Ref<number>, refreshIntervalReturn?: Ref<number> | null): void;
+    /**
+     * Retrieves a `GdkFrameTimings` object holding timing information
+     * for the current frame or a recent frame.
+     *
+     * The `GdkFrameTimings` object may not yet be complete: see
+     * [method@Gdk.FrameTimings.get_complete] and
+     * [method@Gdk.FrameClock.get_history_start].
+     * @param frameCounter - the frame counter value identifying the frame to
+     */
     getTimings(frameCounter: number): FrameTimings | null;
+    /**
+     * Asks the frame clock to run a particular phase.
+     *
+     * The signal corresponding the requested phase will be emitted the next
+     * time the frame clock processes. Multiple calls to
+     * gdk_frame_clock_request_phase() will be combined together
+     * and only one frame processed. If you are displaying animated
+     * content and want to continually request the
+     * %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time,
+     * you should use [method@Gdk.FrameClock.begin_updating] instead,
+     * since this allows GTK to adjust system parameters to get maximally
+     * smooth animations.
+     * @param phase - the phase that is requested
+     */
     requestPhase(phase: FrameClockPhase): void;
     connect(signal: "after-paint", handler: (self: FrameClock) => void, after?: boolean): number;
     connect(signal: "before-paint", handler: (self: FrameClock) => void, after?: boolean): number;