@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/selection-filter-model.js

@@ -2,6 +2,7 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SelectionModel } from "./selection-model.js";
 import * as GObject from "../gobject/index.js";
+/** A list model that presents the selection from a `GtkSelectionModel`. */
 export class SelectionFilterModel extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -16,6 +17,9 @@ export class SelectionFilterModel extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the model currently filtered or %NULL if none.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_selection_filter_model_get_model", [
             {
@@ -27,6 +31,15 @@ export class SelectionFilterModel extends GObject.GObject {
             return null;
         return getObject(ptr, SelectionModel);
     }
+    /**
+     * Sets the model to be filtered.
+     *
+     * Note that GTK makes no effort to ensure that `model` conforms to
+     * the item type of @self. It assumes that the caller knows what they
+     * are doing and have set up an appropriate filter to ensure that item
+     * types match.
+     * @param model - The model to be filtered
+     */
     setModel(model) {
         call("libgtk-4.so.1", "gtk_selection_filter_model_set_model", [
             {

package/dist/generated/gtk/selection-model.d.ts

@@ -1,17 +1,148 @@
 import { Bitset } from "./bitset.js";
+/**
+ * An interface that adds support for selection to list models.
+ *
+ * This support is then used by widgets using list models to add the ability
+ * to select and unselect various items.
+ *
+ * GTK provides default implementations of the most common selection modes such
+ * as [class@Gtk.SingleSelection], so you will only need to implement this
+ * interface if you want detailed control about how selections should be handled.
+ *
+ * A `GtkSelectionModel` supports a single boolean per item indicating if an item is
+ * selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected].
+ * When the selected state of one or more items changes, the model will emit the
+ * [signal@Gtk.SelectionModel::selection-changed] signal by calling the
+ * [method@Gtk.SelectionModel.selection_changed] function. The positions given
+ * in that signal may have their selection state changed, though that is not a
+ * requirement. If new items added to the model via the
+ * [signal@Gio.ListModel::items-changed] signal are selected or not is up to the
+ * implementation.
+ *
+ * Note that items added via [signal@Gio.ListModel::items-changed] may already
+ * be selected and no [signal@Gtk.SelectionModel::selection-changed] will be
+ * emitted for them. So to track which items are selected, it is necessary to
+ * listen to both signals.
+ *
+ * Additionally, the interface can expose functionality to select and unselect
+ * items. If these functions are implemented, GTK's list widgets will allow users
+ * to select and unselect items. However, `GtkSelectionModel`s are free to only
+ * implement them partially or not at all. In that case the widgets will not
+ * support the unimplemented operations.
+ *
+ * When selecting or unselecting is supported by a model, the return values of
+ * the selection functions do *not* indicate if selection or unselection happened.
+ * They are only meant to indicate complete failure, like when this mode of
+ * selecting is not supported by the model.
+ *
+ * Selections may happen asynchronously, so the only reliable way to find out
+ * when an item was selected is to listen to the signals that indicate selection.
+ */
 export declare class SelectionModel {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): SelectionModel;
+    /**
+     * Gets the set containing all currently selected items in the model.
+     *
+     * This function may be slow, so if you are only interested in single item,
+     * consider using [method@Gtk.SelectionModel.is_selected] or if you are only
+     * interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range].
+     */
     getSelection(): Bitset;
+    /**
+     * Gets the set of selected items in a range.
+     *
+     * This function is an optimization for
+     * [method@Gtk.SelectionModel.get_selection] when you are only
+     * interested in part of the model's selected state. A common use
+     * case is in response to the [signal@Gtk.SelectionModel::selection-changed]
+     * signal.
+     * @param position - start of the queried range
+     * @param nItems - number of items in the queried range
+     */
     getSelectionInRange(position: number, nItems: number): Bitset;
+    /**
+     * Checks if the given item is selected.
+     * @param position - the position of the item to query
+     */
     isSelected(position: number): boolean;
+    /**
+     * Requests to select all items in the model.
+     */
     selectAll(): boolean;
+    /**
+     * Requests to select an item in the model.
+     * @param position - the position of the item to select
+     * @param unselectRest - whether previously selected items should be unselected
+     */
     selectItem(position: number, unselectRest: boolean): boolean;
+    /**
+     * Requests to select a range of items in the model.
+     * @param position - the first item to select
+     * @param nItems - the number of items to select
+     * @param unselectRest - whether previously selected items should be unselected
+     */
     selectRange(position: number, nItems: number, unselectRest: boolean): boolean;
+    /**
+     * Helper function for implementations of `GtkSelectionModel`.
+     *
+     * Call this when the selection changes to emit the
+     * [signal@Gtk.SelectionModel::selection-changed] signal.
+     * @param position - the first changed item
+     * @param nItems - the number of changed items
+     */
     selectionChanged(position: number, nItems: number): void;
+    /**
+     * Make selection changes.
+     *
+     * This is the most advanced selection updating method that allows
+     * the most fine-grained control over selection changes. If you can,
+     * you should try the simpler versions, as implementations are more
+     * likely to implement support for those.
+     *
+     * Requests that the selection state of all positions set in `mask` be updated to the respective value in the `selected` bitmask.
+     *
+     * In pseudocode, it would look something like this:
+     *
+     * ```c
+     * for (i = 0; i < n_items; i++)
+     * {
+     * // don't change values not in the mask
+     * if (!gtk_bitset_contains (mask, i))
+     * continue;
+     *
+     * if (gtk_bitset_contains (selected, i))
+     * select_item (i);
+     * else
+     * unselect_item (i);
+     * }
+     *
+     * gtk_selection_model_selection_changed (model,
+     * first_changed_item,
+     * n_changed_items);
+     * ```
+     *
+     * `mask` and `selected` must not be modified. They may refer to the
+     * same bitset, which would mean that every item in the set should
+     * be selected.
+     * @param selected - bitmask specifying if items should be selected or unselected
+     * @param mask - bitmask specifying which items should be updated
+     */
     setSelection(selected: Bitset, mask: Bitset): boolean;
+    /**
+     * Requests to unselect all items in the model.
+     */
     unselectAll(): boolean;
+    /**
+     * Requests to unselect an item in the model.
+     * @param position - the position of the item to unselect
+     */
     unselectItem(position: number): boolean;
+    /**
+     * Requests to unselect a range of items in the model.
+     * @param position - the first item to unselect
+     * @param nItems - the number of items to unselect
+     */
     unselectRange(position: number, nItems: number): boolean;
 }

package/dist/generated/gtk/selection-model.js

@@ -1,6 +1,45 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Bitset } from "./bitset.js";
+/**
+ * An interface that adds support for selection to list models.
+ *
+ * This support is then used by widgets using list models to add the ability
+ * to select and unselect various items.
+ *
+ * GTK provides default implementations of the most common selection modes such
+ * as [class@Gtk.SingleSelection], so you will only need to implement this
+ * interface if you want detailed control about how selections should be handled.
+ *
+ * A `GtkSelectionModel` supports a single boolean per item indicating if an item is
+ * selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected].
+ * When the selected state of one or more items changes, the model will emit the
+ * [signal@Gtk.SelectionModel::selection-changed] signal by calling the
+ * [method@Gtk.SelectionModel.selection_changed] function. The positions given
+ * in that signal may have their selection state changed, though that is not a
+ * requirement. If new items added to the model via the
+ * [signal@Gio.ListModel::items-changed] signal are selected or not is up to the
+ * implementation.
+ *
+ * Note that items added via [signal@Gio.ListModel::items-changed] may already
+ * be selected and no [signal@Gtk.SelectionModel::selection-changed] will be
+ * emitted for them. So to track which items are selected, it is necessary to
+ * listen to both signals.
+ *
+ * Additionally, the interface can expose functionality to select and unselect
+ * items. If these functions are implemented, GTK's list widgets will allow users
+ * to select and unselect items. However, `GtkSelectionModel`s are free to only
+ * implement them partially or not at all. In that case the widgets will not
+ * support the unimplemented operations.
+ *
+ * When selecting or unselecting is supported by a model, the return values of
+ * the selection functions do *not* indicate if selection or unselection happened.
+ * They are only meant to indicate complete failure, like when this mode of
+ * selecting is not supported by the model.
+ *
+ * Selections may happen asynchronously, so the only reliable way to find out
+ * when an item was selected is to listen to the signals that indicate selection.
+ */
 export class SelectionModel {
     ptr;
     constructor(ptr) {
@@ -9,6 +48,13 @@ export class SelectionModel {
     static fromPtr(ptr) {
         return new SelectionModel(ptr);
     }
+    /**
+     * Gets the set containing all currently selected items in the model.
+     *
+     * This function may be slow, so if you are only interested in single item,
+     * consider using [method@Gtk.SelectionModel.is_selected] or if you are only
+     * interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range].
+     */
     getSelection() {
         const ptr = call("libgtk-4.so.1", "gtk_selection_model_get_selection", [
             {
@@ -23,6 +69,17 @@ export class SelectionModel {
         });
         return getObject(ptr, Bitset);
     }
+    /**
+     * Gets the set of selected items in a range.
+     *
+     * This function is an optimization for
+     * [method@Gtk.SelectionModel.get_selection] when you are only
+     * interested in part of the model's selected state. A common use
+     * case is in response to the [signal@Gtk.SelectionModel::selection-changed]
+     * signal.
+     * @param position - start of the queried range
+     * @param nItems - number of items in the queried range
+     */
     getSelectionInRange(position, nItems) {
         const ptr = call("libgtk-4.so.1", "gtk_selection_model_get_selection_in_range", [
             {
@@ -45,6 +102,10 @@ export class SelectionModel {
         });
         return getObject(ptr, Bitset);
     }
+    /**
+     * Checks if the given item is selected.
+     * @param position - the position of the item to query
+     */
     isSelected(position) {
         return call("libgtk-4.so.1", "gtk_selection_model_is_selected", [
             {
@@ -57,6 +118,9 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to select all items in the model.
+     */
     selectAll() {
         return call("libgtk-4.so.1", "gtk_selection_model_select_all", [
             {
@@ -65,6 +129,11 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to select an item in the model.
+     * @param position - the position of the item to select
+     * @param unselectRest - whether previously selected items should be unselected
+     */
     selectItem(position, unselectRest) {
         return call("libgtk-4.so.1", "gtk_selection_model_select_item", [
             {
@@ -81,6 +150,12 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to select a range of items in the model.
+     * @param position - the first item to select
+     * @param nItems - the number of items to select
+     * @param unselectRest - whether previously selected items should be unselected
+     */
     selectRange(position, nItems, unselectRest) {
         return call("libgtk-4.so.1", "gtk_selection_model_select_range", [
             {
@@ -101,6 +176,14 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Helper function for implementations of `GtkSelectionModel`.
+     *
+     * Call this when the selection changes to emit the
+     * [signal@Gtk.SelectionModel::selection-changed] signal.
+     * @param position - the first changed item
+     * @param nItems - the number of changed items
+     */
     selectionChanged(position, nItems) {
         call("libgtk-4.so.1", "gtk_selection_model_selection_changed", [
             {
@@ -117,6 +200,42 @@ export class SelectionModel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Make selection changes.
+     *
+     * This is the most advanced selection updating method that allows
+     * the most fine-grained control over selection changes. If you can,
+     * you should try the simpler versions, as implementations are more
+     * likely to implement support for those.
+     *
+     * Requests that the selection state of all positions set in `mask` be updated to the respective value in the `selected` bitmask.
+     *
+     * In pseudocode, it would look something like this:
+     *
+     * ```c
+     * for (i = 0; i < n_items; i++)
+     * {
+     * // don't change values not in the mask
+     * if (!gtk_bitset_contains (mask, i))
+     * continue;
+     *
+     * if (gtk_bitset_contains (selected, i))
+     * select_item (i);
+     * else
+     * unselect_item (i);
+     * }
+     *
+     * gtk_selection_model_selection_changed (model,
+     * first_changed_item,
+     * n_changed_items);
+     * ```
+     *
+     * `mask` and `selected` must not be modified. They may refer to the
+     * same bitset, which would mean that every item in the set should
+     * be selected.
+     * @param selected - bitmask specifying if items should be selected or unselected
+     * @param mask - bitmask specifying which items should be updated
+     */
     setSelection(selected, mask) {
         return call("libgtk-4.so.1", "gtk_selection_model_set_selection", [
             {
@@ -143,6 +262,9 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to unselect all items in the model.
+     */
     unselectAll() {
         return call("libgtk-4.so.1", "gtk_selection_model_unselect_all", [
             {
@@ -151,6 +273,10 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to unselect an item in the model.
+     * @param position - the position of the item to unselect
+     */
     unselectItem(position) {
         return call("libgtk-4.so.1", "gtk_selection_model_unselect_item", [
             {
@@ -163,6 +289,11 @@ export class SelectionModel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Requests to unselect a range of items in the model.
+     * @param position - the first item to unselect
+     * @param nItems - the number of items to unselect
+     */
     unselectRange(position, nItems) {
         return call("libgtk-4.so.1", "gtk_selection_model_unselect_range", [
             {

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

@@ -1,11 +1,40 @@
 import { Orientation } from "./enums.js";
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Draws a horizontal or vertical line to separate other widgets.
+ *
+ *
+ *
+ * A `GtkSeparator` can be used to group the widgets within a window.
+ * It displays a line with a shadow to make it appear sunken into the
+ * interface.
+ *
+ * # CSS nodes
+ *
+ * `GtkSeparator` has a single CSS node with name separator. The node
+ * gets one of the .horizontal or .vertical style classes.
+ *
+ * # Accessibility
+ *
+ * `GtkSeparator` uses the [enum@Gtk.AccessibleRole.separator] role.
+ */
 export declare class Separator extends Widget {
+    /**
+     * Creates a new `GtkSeparator` with the given orientation.
+     * @param orientation - the separator’s orientation.
+     */
     constructor(orientation: Orientation);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Retrieves the orientation of the @orientable.
+     */
     getOrientation(): Orientation;
+    /**
+     * Sets the orientation of the @orientable.
+     * @param orientation - the orientable’s new orientation
+     */
     setOrientation(orientation: Orientation): void;
     connect(signal: "notify", handler: (self: Separator, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/separator.js

@@ -1,6 +1,24 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Draws a horizontal or vertical line to separate other widgets.
+ *
+ *
+ *
+ * A `GtkSeparator` can be used to group the widgets within a window.
+ * It displays a line with a shadow to make it appear sunken into the
+ * interface.
+ *
+ * # CSS nodes
+ *
+ * `GtkSeparator` has a single CSS node with name separator. The node
+ * gets one of the .horizontal or .vertical style classes.
+ *
+ * # Accessibility
+ *
+ * `GtkSeparator` uses the [enum@Gtk.AccessibleRole.separator] role.
+ */
 export class Separator extends Widget {
     constructor(...args) {
         super(...args);
@@ -14,6 +32,9 @@ export class Separator extends Widget {
             },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Retrieves the orientation of the @orientable.
+     */
     getOrientation() {
         return call("libgtk-4.so.1", "gtk_orientable_get_orientation", [
             {
@@ -22,6 +43,10 @@ export class Separator extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets the orientation of the @orientable.
+     * @param orientation - the orientable’s new orientation
+     */
     setOrientation(orientation) {
         call("libgtk-4.so.1", "gtk_orientable_set_orientation", [
             {

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

@@ -1,10 +1,57 @@
 import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
+/**
+ * Provides a mechanism to share global settings between applications.
+ *
+ * On the X window system, this sharing is realized by an
+ * [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec)
+ * manager that is usually part of the desktop environment, along with
+ * utilities that let the user change these settings.
+ *
+ * On Wayland, the settings are obtained either via a settings portal,
+ * or by reading desktop settings from [class@Gio.Settings].
+ *
+ * On macOS, the settings are obtained from `NSUserDefaults`.
+ *
+ * In the absence of these sharing mechanisms, GTK reads default values for
+ * settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0`
+ * and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see
+ * `GKeyFile`), and have a section called Settings. Themes can also provide
+ * default values for settings by installing a `settings.ini` file
+ * next to their `gtk.css` file.
+ *
+ * Applications can override system-wide settings by setting the property
+ * of the `GtkSettings` object with g_object_set(). This should be restricted
+ * to special cases though; `GtkSettings` are not meant as an application
+ * configuration facility.
+ *
+ * There is one `GtkSettings` instance per display. It can be obtained with
+ * [func@Gtk.Settings.get_for_display], but in many cases, it is more
+ * convenient to use [method@Gtk.Widget.get_settings].
+ */
 export declare class Settings extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the `GtkSettings` object for the default display, creating
+     * it if necessary.
+     *
+     * See [func@Gtk.Settings.get_for_display].
+     */
     static getDefault(): Settings;
+    /**
+     * Gets the `GtkSettings` object for @display, creating it if necessary.
+     * @param display - a `GdkDisplay`
+     */
     static getForDisplay(display: Gdk.Display): Settings;
+    /**
+     * Undoes the effect of calling g_object_set() to install an
+     * application-specific value for a setting.
+     *
+     * After this call, the setting will again follow the session-wide
+     * value for this setting.
+     * @param name - the name of the setting to reset
+     */
     resetProperty(name: string): void;
     connect(signal: "notify", handler: (self: Settings, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/settings.js

@@ -1,6 +1,35 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Provides a mechanism to share global settings between applications.
+ *
+ * On the X window system, this sharing is realized by an
+ * [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec)
+ * manager that is usually part of the desktop environment, along with
+ * utilities that let the user change these settings.
+ *
+ * On Wayland, the settings are obtained either via a settings portal,
+ * or by reading desktop settings from [class@Gio.Settings].
+ *
+ * On macOS, the settings are obtained from `NSUserDefaults`.
+ *
+ * In the absence of these sharing mechanisms, GTK reads default values for
+ * settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0`
+ * and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see
+ * `GKeyFile`), and have a section called Settings. Themes can also provide
+ * default values for settings by installing a `settings.ini` file
+ * next to their `gtk.css` file.
+ *
+ * Applications can override system-wide settings by setting the property
+ * of the `GtkSettings` object with g_object_set(). This should be restricted
+ * to special cases though; `GtkSettings` are not meant as an application
+ * configuration facility.
+ *
+ * There is one `GtkSettings` instance per display. It can be obtained with
+ * [func@Gtk.Settings.get_for_display], but in many cases, it is more
+ * convenient to use [method@Gtk.Widget.get_settings].
+ */
 export class Settings extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -16,6 +45,12 @@ export class Settings extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Gets the `GtkSettings` object for the default display, creating
+     * it if necessary.
+     *
+     * See [func@Gtk.Settings.get_for_display].
+     */
     static getDefault() {
         const ptr = call("libgtk-4.so.1", "gtk_settings_get_default", [], {
             type: "gobject",
@@ -23,6 +58,10 @@ export class Settings extends GObject.GObject {
         });
         return getObject(ptr, Settings);
     }
+    /**
+     * Gets the `GtkSettings` object for @display, creating it if necessary.
+     * @param display - a `GdkDisplay`
+     */
     static getForDisplay(display) {
         const ptr = call("libgtk-4.so.1", "gtk_settings_get_for_display", [
             {
@@ -32,6 +71,14 @@ export class Settings extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Settings);
     }
+    /**
+     * Undoes the effect of calling g_object_set() to install an
+     * application-specific value for a setting.
+     *
+     * After this call, the setting will again follow the session-wide
+     * value for this setting.
+     * @param name - the name of the setting to reset
+     */
     resetProperty(name) {
         call("libgtk-4.so.1", "gtk_settings_reset_property", [
             {