@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/accessible.d.ts

@@ -2,25 +2,179 @@ import { Ref } from "@gtkx/native";
 import { AccessibleAnnouncementPriority, AccessiblePlatformState, AccessibleProperty, AccessibleRelation, AccessibleRole, AccessibleState } from "./enums.js";
 import { ATContext } from "./atcontext.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * An interface for describing UI elements for Assistive Technologies.
+ *
+ * Every accessible implementation has:
+ *
+ * - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration
+ * - “attributes”, represented by a set of [enum@Gtk.AccessibleState],
+ * [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values
+ *
+ * The role cannot be changed after instantiating a `GtkAccessible`
+ * implementation.
+ *
+ * The attributes are updated every time a UI element's state changes in
+ * a way that should be reflected by assistive technologies. For instance,
+ * if a `GtkWidget` visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN
+ * state will also change to reflect the [property@Gtk.Widget:visible] property.
+ *
+ * Every accessible implementation is part of a tree of accessible objects.
+ * Normally, this tree corresponds to the widget tree, but can be customized
+ * by reimplementing the [vfunc@Gtk.Accessible.get_accessible_parent],
+ * [vfunc@Gtk.Accessible.get_first_accessible_child] and
+ * [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions.
+ *
+ * Note that you can not create a top-level accessible object as of now,
+ * which means that you must always have a parent accessible object.
+ *
+ * Also note that when an accessible object does not correspond to a widget,
+ * and it has children, whose implementation you don't control,
+ * it is necessary to ensure the correct shape of the a11y tree
+ * by calling [method@Gtk.Accessible.set_accessible_parent] and
+ * updating the sibling by [method@Gtk.Accessible.update_next_accessible_sibling].
+ */
 export declare class Accessible {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): Accessible;
+    /**
+     * Requests the user's screen reader to announce the given message.
+     *
+     * This kind of notification is useful for messages that
+     * either have only a visual representation or that are not
+     * exposed visually at all, e.g. a notification about a
+     * successful operation.
+     *
+     * Also, by using this API, you can ensure that the message
+     * does not interrupts the user's current screen reader output.
+     * @param message - the string to announce
+     * @param priority - the priority of the announcement
+     */
     announce(message: string, priority: AccessibleAnnouncementPriority): void;
+    /**
+     * Retrieves the accessible parent for an accessible object.
+     *
+     * This function returns `NULL` for top level widgets.
+     */
     getAccessibleParent(): Accessible | null;
+    /**
+     * Retrieves the accessible role of an accessible object.
+     */
     getAccessibleRole(): AccessibleRole;
+    /**
+     * Retrieves the implementation for the given accessible object.
+     */
     getAtContext(): ATContext;
+    /**
+     * Queries the coordinates and dimensions of this accessible
+     *
+     * This functionality can be overridden by `GtkAccessible`
+     * implementations, e.g. to get the bounds from an ignored
+     * child widget.
+     * @param x - the x coordinate of the top left corner of the accessible
+     * @param y - the y coordinate of the top left corner of the widget
+     * @param width - the width of the accessible object
+     * @param height - the height of the accessible object
+     */
     getBounds(x: Ref<number>, y: Ref<number>, width: Ref<number>, height: Ref<number>): boolean;
+    /**
+     * Retrieves the first accessible child of an accessible object.
+     */
     getFirstAccessibleChild(): Accessible | null;
+    /**
+     * Retrieves the next accessible sibling of an accessible object
+     */
     getNextAccessibleSibling(): Accessible | null;
+    /**
+     * Queries a platform state, such as focus.
+     *
+     * This functionality can be overridden by `GtkAccessible`
+     * implementations, e.g. to get platform state from an ignored
+     * child widget, as is the case for `GtkText` wrappers.
+     * @param state - platform state to query
+     */
     getPlatformState(state: AccessiblePlatformState): boolean;
+    /**
+     * Resets the accessible property to its default value.
+     * @param property - the accessible property
+     */
     resetProperty(property: AccessibleProperty): void;
+    /**
+     * Resets the accessible relation to its default value.
+     * @param relation - the accessible relation
+     */
     resetRelation(relation: AccessibleRelation): void;
+    /**
+     * Resets the accessible state to its default value.
+     * @param state - the accessible state
+     */
     resetState(state: AccessibleState): void;
+    /**
+     * Sets the parent and sibling of an accessible object.
+     *
+     * This function is meant to be used by accessible implementations that are
+     * not part of the widget hierarchy, and but act as a logical bridge between
+     * widgets. For instance, if a widget creates an object that holds metadata
+     * for each child, and you want that object to implement the `GtkAccessible`
+     * interface, you will use this function to ensure that the parent of each
+     * child widget is the metadata object, and the parent of each metadata
+     * object is the container widget.
+     * @param parent - the parent accessible object
+     * @param nextSibling - the sibling accessible object
+     */
     setAccessibleParent(parent?: Accessible | null, nextSibling?: Accessible | null): void;
+    /**
+     * Updates the next accessible sibling.
+     *
+     * That might be useful when a new child of a custom accessible
+     * is created, and it needs to be linked to a previous child.
+     * @param newSibling - the new next accessible sibling to set
+     */
     updateNextAccessibleSibling(newSibling?: Accessible | null): void;
+    /**
+     * Informs ATs that the platform state has changed.
+     *
+     * This function should be used by `GtkAccessible` implementations that
+     * have a platform state but are not widgets. Widgets handle platform
+     * states automatically.
+     * @param state - the platform state to update
+     */
     updatePlatformState(state: AccessiblePlatformState): void;
+    /**
+     * Updates an array of accessible properties.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * property change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nProperties - the number of accessible properties to set
+     * @param properties - an array of accessible properties
+     * @param values - an array of `GValues`, one for each property
+     */
     updatePropertyValue(nProperties: number, properties: AccessibleProperty[], values: GObject.Value[]): void;
+    /**
+     * Updates an array of accessible relations.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * relation change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nRelations - the number of accessible relations to set
+     * @param relations - an array of accessible relations
+     * @param values - an array of `GValues`, one for each relation
+     */
     updateRelationValue(nRelations: number, relations: AccessibleRelation[], values: GObject.Value[]): void;
+    /**
+     * Updates an array of accessible states.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * state change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nStates - the number of accessible states to set
+     * @param states - an array of accessible states
+     * @param values - an array of `GValues`, one for each state
+     */
     updateStateValue(nStates: number, states: AccessibleState[], values: GObject.Value[]): void;
 }

package/dist/generated/gtk/accessible.js

@@ -1,6 +1,38 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { ATContext } from "./atcontext.js";
+/**
+ * An interface for describing UI elements for Assistive Technologies.
+ *
+ * Every accessible implementation has:
+ *
+ * - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration
+ * - “attributes”, represented by a set of [enum@Gtk.AccessibleState],
+ * [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values
+ *
+ * The role cannot be changed after instantiating a `GtkAccessible`
+ * implementation.
+ *
+ * The attributes are updated every time a UI element's state changes in
+ * a way that should be reflected by assistive technologies. For instance,
+ * if a `GtkWidget` visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN
+ * state will also change to reflect the [property@Gtk.Widget:visible] property.
+ *
+ * Every accessible implementation is part of a tree of accessible objects.
+ * Normally, this tree corresponds to the widget tree, but can be customized
+ * by reimplementing the [vfunc@Gtk.Accessible.get_accessible_parent],
+ * [vfunc@Gtk.Accessible.get_first_accessible_child] and
+ * [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions.
+ *
+ * Note that you can not create a top-level accessible object as of now,
+ * which means that you must always have a parent accessible object.
+ *
+ * Also note that when an accessible object does not correspond to a widget,
+ * and it has children, whose implementation you don't control,
+ * it is necessary to ensure the correct shape of the a11y tree
+ * by calling [method@Gtk.Accessible.set_accessible_parent] and
+ * updating the sibling by [method@Gtk.Accessible.update_next_accessible_sibling].
+ */
 export class Accessible {
     ptr;
     constructor(ptr) {
@@ -9,6 +41,19 @@ export class Accessible {
     static fromPtr(ptr) {
         return new Accessible(ptr);
     }
+    /**
+     * Requests the user's screen reader to announce the given message.
+     *
+     * This kind of notification is useful for messages that
+     * either have only a visual representation or that are not
+     * exposed visually at all, e.g. a notification about a
+     * successful operation.
+     *
+     * Also, by using this API, you can ensure that the message
+     * does not interrupts the user's current screen reader output.
+     * @param message - the string to announce
+     * @param priority - the priority of the announcement
+     */
     announce(message, priority) {
         call("libgtk-4.so.1", "gtk_accessible_announce", [
             {
@@ -25,6 +70,11 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves the accessible parent for an accessible object.
+     *
+     * This function returns `NULL` for top level widgets.
+     */
     getAccessibleParent() {
         const ptr = call("libgtk-4.so.1", "gtk_accessible_get_accessible_parent", [
             {
@@ -36,6 +86,9 @@ export class Accessible {
             return null;
         return getObject(ptr, Accessible);
     }
+    /**
+     * Retrieves the accessible role of an accessible object.
+     */
     getAccessibleRole() {
         return call("libgtk-4.so.1", "gtk_accessible_get_accessible_role", [
             {
@@ -44,6 +97,9 @@ export class Accessible {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the implementation for the given accessible object.
+     */
     getAtContext() {
         const ptr = call("libgtk-4.so.1", "gtk_accessible_get_at_context", [
             {
@@ -53,6 +109,17 @@ export class Accessible {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, ATContext);
     }
+    /**
+     * Queries the coordinates and dimensions of this accessible
+     *
+     * This functionality can be overridden by `GtkAccessible`
+     * implementations, e.g. to get the bounds from an ignored
+     * child widget.
+     * @param x - the x coordinate of the top left corner of the accessible
+     * @param y - the y coordinate of the top left corner of the widget
+     * @param width - the width of the accessible object
+     * @param height - the height of the accessible object
+     */
     getBounds(x, y, width, height) {
         return call("libgtk-4.so.1", "gtk_accessible_get_bounds", [
             {
@@ -89,6 +156,9 @@ export class Accessible {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the first accessible child of an accessible object.
+     */
     getFirstAccessibleChild() {
         const ptr = call("libgtk-4.so.1", "gtk_accessible_get_first_accessible_child", [
             {
@@ -100,6 +170,9 @@ export class Accessible {
             return null;
         return getObject(ptr, Accessible);
     }
+    /**
+     * Retrieves the next accessible sibling of an accessible object
+     */
     getNextAccessibleSibling() {
         const ptr = call("libgtk-4.so.1", "gtk_accessible_get_next_accessible_sibling", [
             {
@@ -111,6 +184,14 @@ export class Accessible {
             return null;
         return getObject(ptr, Accessible);
     }
+    /**
+     * Queries a platform state, such as focus.
+     *
+     * This functionality can be overridden by `GtkAccessible`
+     * implementations, e.g. to get platform state from an ignored
+     * child widget, as is the case for `GtkText` wrappers.
+     * @param state - platform state to query
+     */
     getPlatformState(state) {
         return call("libgtk-4.so.1", "gtk_accessible_get_platform_state", [
             {
@@ -123,6 +204,10 @@ export class Accessible {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Resets the accessible property to its default value.
+     * @param property - the accessible property
+     */
     resetProperty(property) {
         call("libgtk-4.so.1", "gtk_accessible_reset_property", [
             {
@@ -135,6 +220,10 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Resets the accessible relation to its default value.
+     * @param relation - the accessible relation
+     */
     resetRelation(relation) {
         call("libgtk-4.so.1", "gtk_accessible_reset_relation", [
             {
@@ -147,6 +236,10 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Resets the accessible state to its default value.
+     * @param state - the accessible state
+     */
     resetState(state) {
         call("libgtk-4.so.1", "gtk_accessible_reset_state", [
             {
@@ -159,6 +252,19 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the parent and sibling of an accessible object.
+     *
+     * This function is meant to be used by accessible implementations that are
+     * not part of the widget hierarchy, and but act as a logical bridge between
+     * widgets. For instance, if a widget creates an object that holds metadata
+     * for each child, and you want that object to implement the `GtkAccessible`
+     * interface, you will use this function to ensure that the parent of each
+     * child widget is the metadata object, and the parent of each metadata
+     * object is the container widget.
+     * @param parent - the parent accessible object
+     * @param nextSibling - the sibling accessible object
+     */
     setAccessibleParent(parent, nextSibling) {
         call("libgtk-4.so.1", "gtk_accessible_set_accessible_parent", [
             {
@@ -177,6 +283,13 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Updates the next accessible sibling.
+     *
+     * That might be useful when a new child of a custom accessible
+     * is created, and it needs to be linked to a previous child.
+     * @param newSibling - the new next accessible sibling to set
+     */
     updateNextAccessibleSibling(newSibling) {
         call("libgtk-4.so.1", "gtk_accessible_update_next_accessible_sibling", [
             {
@@ -190,6 +303,14 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Informs ATs that the platform state has changed.
+     *
+     * This function should be used by `GtkAccessible` implementations that
+     * have a platform state but are not widgets. Widgets handle platform
+     * states automatically.
+     * @param state - the platform state to update
+     */
     updatePlatformState(state) {
         call("libgtk-4.so.1", "gtk_accessible_update_platform_state", [
             {
@@ -202,6 +323,17 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Updates an array of accessible properties.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * property change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nProperties - the number of accessible properties to set
+     * @param properties - an array of accessible properties
+     * @param values - an array of `GValues`, one for each property
+     */
     updatePropertyValue(nProperties, properties, values) {
         call("libgtk-4.so.1", "gtk_accessible_update_property_value", [
             {
@@ -232,6 +364,17 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Updates an array of accessible relations.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * relation change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nRelations - the number of accessible relations to set
+     * @param relations - an array of accessible relations
+     * @param values - an array of `GValues`, one for each relation
+     */
     updateRelationValue(nRelations, relations, values) {
         call("libgtk-4.so.1", "gtk_accessible_update_relation_value", [
             {
@@ -262,6 +405,17 @@ export class Accessible {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Updates an array of accessible states.
+     *
+     * This function should be called by `GtkWidget` types whenever an accessible
+     * state change must be communicated to assistive technologies.
+     *
+     * This function is meant to be used by language bindings.
+     * @param nStates - the number of accessible states to set
+     * @param states - an array of accessible states
+     * @param values - an array of `GValues`, one for each state
+     */
     updateStateValue(nStates, states, values) {
         call("libgtk-4.so.1", "gtk_accessible_update_state_value", [
             {

package/dist/generated/gtk/action-bar.d.ts

@@ -1,14 +1,89 @@
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Presents contextual actions.
+ *
+ *
+ *
+ * `GtkActionBar` is expected to be displayed below the content and expand
+ * horizontally to fill the area.
+ *
+ * It allows placing children at the start or the end. In addition, it
+ * contains an internal centered box which is centered with respect to
+ * the full width of the box, even if the children at either side take
+ * up different amounts of space.
+ *
+ * # GtkActionBar as GtkBuildable
+ *
+ * The `GtkActionBar` implementation of the `GtkBuildable` interface supports
+ * adding children at the start or end sides by specifying “start” or “end” as
+ * the “type” attribute of a `<child>` element, or setting the center widget
+ * by specifying “center” value.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * actionbar
+ * ╰── revealer
+ * ╰── box
+ * ├── box.start
+ * │   ╰── [start children]
+ * ├── [center widget]
+ * ╰── box.end
+ * ╰── [end children]
+ * ```
+ *
+ * A `GtkActionBar`'s CSS node is called `actionbar`. It contains a `revealer`
+ * subnode, which contains a `box` subnode, which contains two `box` subnodes at
+ * the start and end of the action bar, with `start` and `end` style classes
+ * respectively, as well as a center node that represents the center child.
+ *
+ * Each of the boxes contains children packed for that side.
+ */
 export declare class ActionBar extends Widget {
+    /**
+     * Creates a new action bar widget.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Retrieves the center bar widget of the bar.
+     */
     getCenterWidget(): Widget | null;
+    /**
+     * Gets whether the contents of the action bar are revealed.
+     */
     getRevealed(): boolean;
+    /**
+     * Adds a child to the action bar, packed with reference to the
+     * end of the action bar.
+     * @param child - the widget to be added
+     */
     packEnd(child: Widget): void;
+    /**
+     * Adds a child to the action, packed with reference to the
+     * start of the action bar.
+     * @param child - the widget to be added
+     */
     packStart(child: Widget): void;
+    /**
+     * Removes a child from the action bar.
+     * @param child - the widget to be removed
+     */
     remove(child: Widget): void;
+    /**
+     * Sets the center widget for the action bar.
+     * @param centerWidget - a widget to use for the center
+     */
     setCenterWidget(centerWidget?: Widget | null): void;
+    /**
+     * Reveals or conceals the content of the action bar.
+     *
+     * Note: this does not show or hide the action bar in the
+     * [property@Gtk.Widget:visible] sense, so revealing has
+     * no effect if the action bar is hidden.
+     * @param revealed - the new value for the property
+     */
     setRevealed(revealed: boolean): void;
     connect(signal: "notify", handler: (self: ActionBar, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/action-bar.js

@@ -1,7 +1,50 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Presents contextual actions.
+ *
+ *
+ *
+ * `GtkActionBar` is expected to be displayed below the content and expand
+ * horizontally to fill the area.
+ *
+ * It allows placing children at the start or the end. In addition, it
+ * contains an internal centered box which is centered with respect to
+ * the full width of the box, even if the children at either side take
+ * up different amounts of space.
+ *
+ * # GtkActionBar as GtkBuildable
+ *
+ * The `GtkActionBar` implementation of the `GtkBuildable` interface supports
+ * adding children at the start or end sides by specifying “start” or “end” as
+ * the “type” attribute of a `<child>` element, or setting the center widget
+ * by specifying “center” value.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * actionbar
+ * ╰── revealer
+ * ╰── box
+ * ├── box.start
+ * │   ╰── [start children]
+ * ├── [center widget]
+ * ╰── box.end
+ * ╰── [end children]
+ * ```
+ *
+ * A `GtkActionBar`'s CSS node is called `actionbar`. It contains a `revealer`
+ * subnode, which contains a `box` subnode, which contains two `box` subnodes at
+ * the start and end of the action bar, with `start` and `end` style classes
+ * respectively, as well as a center node that represents the center child.
+ *
+ * Each of the boxes contains children packed for that side.
+ */
 export class ActionBar extends Widget {
+    /**
+     * Creates a new action bar widget.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +54,9 @@ export class ActionBar extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Retrieves the center bar widget of the bar.
+     */
     getCenterWidget() {
         const ptr = call("libgtk-4.so.1", "gtk_action_bar_get_center_widget", [
             {
@@ -22,6 +68,9 @@ export class ActionBar extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Gets whether the contents of the action bar are revealed.
+     */
     getRevealed() {
         return call("libgtk-4.so.1", "gtk_action_bar_get_revealed", [
             {
@@ -30,6 +79,11 @@ export class ActionBar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Adds a child to the action bar, packed with reference to the
+     * end of the action bar.
+     * @param child - the widget to be added
+     */
     packEnd(child) {
         call("libgtk-4.so.1", "gtk_action_bar_pack_end", [
             {
@@ -42,6 +96,11 @@ export class ActionBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a child to the action, packed with reference to the
+     * start of the action bar.
+     * @param child - the widget to be added
+     */
     packStart(child) {
         call("libgtk-4.so.1", "gtk_action_bar_pack_start", [
             {
@@ -54,6 +113,10 @@ export class ActionBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Removes a child from the action bar.
+     * @param child - the widget to be removed
+     */
     remove(child) {
         call("libgtk-4.so.1", "gtk_action_bar_remove", [
             {
@@ -66,6 +129,10 @@ export class ActionBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the center widget for the action bar.
+     * @param centerWidget - a widget to use for the center
+     */
     setCenterWidget(centerWidget) {
         call("libgtk-4.so.1", "gtk_action_bar_set_center_widget", [
             {
@@ -79,6 +146,14 @@ export class ActionBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Reveals or conceals the content of the action bar.
+     *
+     * Note: this does not show or hide the action bar in the
+     * [property@Gtk.Widget:visible] sense, so revealing has
+     * no effect if the action bar is hidden.
+     * @param revealed - the new value for the property
+     */
     setRevealed(revealed) {
         call("libgtk-4.so.1", "gtk_action_bar_set_revealed", [
             {