@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/shortcuts-window.js

@@ -1,6 +1,66 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Window } from "./window.js";
+/**
+ * A `GtkShortcutsWindow` shows information about the keyboard shortcuts
+ * and gestures of an application.
+ *
+ * The shortcuts can be grouped, and you can have multiple sections in this
+ * window, corresponding to the major modes of your application.
+ *
+ * Additionally, the shortcuts can be filtered by the current view, to avoid
+ * showing information that is not relevant in the current application context.
+ *
+ * The recommended way to construct a `GtkShortcutsWindow` is with
+ * [class@Gtk.Builder], by using the `<child>` tag to populate a
+ * `GtkShortcutsWindow` with one or more [class@Gtk.ShortcutsSection] objects,
+ * which contain one or more [class@Gtk.ShortcutsGroup] instances, which, in turn,
+ * contain [class@Gtk.ShortcutsShortcut] instances.
+ *
+ * If you need to add a section programmatically, use [method@Gtk.ShortcutsWindow.add_section]
+ * instead of [method@Gtk.Window.set_child], as the shortcuts window manages
+ * its children directly.
+ *
+ * # A simple example:
+ *
+ *
+ *
+ * This example has as single section. As you can see, the shortcut groups
+ * are arranged in columns, and spread across several pages if there are too
+ * many to find on a single page.
+ *
+ * The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-gedit.ui).
+ *
+ * # An example with multiple views:
+ *
+ *
+ *
+ * This example shows a `GtkShortcutsWindow` that has been configured to show only
+ * the shortcuts relevant to the “Stopwatch” view.
+ *
+ * The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-clocks.ui).
+ *
+ * # An example with multiple sections:
+ *
+ *
+ *
+ * This example shows a `GtkShortcutsWindow` with two sections, “Editor Shortcuts”
+ * and “Terminal Shortcuts”.
+ *
+ * The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-builder.ui).
+ *
+ * # Shortcuts and Gestures
+ *
+ * The following signals have default keybindings:
+ *
+ * - [signal@Gtk.ShortcutsWindow::close]
+ * - [signal@Gtk.ShortcutsWindow::search]
+ *
+ * # CSS nodes
+ *
+ * `GtkShortcutsWindow` has a single CSS node with the name `window` and style
+ * class `.shortcuts`.
+ */
 const SIGNAL_META = {
     close: { params: [], returnType: { type: "undefined" } },
     search: { params: [], returnType: { type: "undefined" } },
@@ -28,6 +88,16 @@ export class ShortcutsWindow extends Window {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Adds a section to the shortcuts window.
+     *
+     * This is the programmatic equivalent to using [class@Gtk.Builder] and a
+     * `<child>` tag to add the child.
+     *
+     * Using [method@Gtk.Window.set_child] is not appropriate as the shortcuts
+     * window manages its children internally.
+     * @param section - the `GtkShortcutsSection` to add
+     */
     addSection(section) {
         call("libgtk-4.so.1", "gtk_shortcuts_window_add_section", [
             {

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

@@ -1,7 +1,23 @@
 import { ShortcutAction } from "./shortcut-action.js";
+/**
+ * Emits a signal on a widget.
+ *
+ * Signals that are used in this way are referred to as keybinding signals,
+ * and they are expected to be defined with the `G_SIGNAL_ACTION` flag.
+ */
 export declare class SignalAction extends ShortcutAction {
+    /**
+     * Creates an action that when activated, emits the given action signal
+     * on the provided widget.
+     *
+     * It will also unpack the args into arguments passed to the signal.
+     * @param signalName - name of the signal to emit
+     */
     constructor(signalName: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Returns the name of the signal that will be emitted.
+     */
     getSignalName(): string;
 }

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

@@ -1,5 +1,11 @@
 import { call } from "@gtkx/native";
 import { ShortcutAction } from "./shortcut-action.js";
+/**
+ * Emits a signal on a widget.
+ *
+ * Signals that are used in this way are referred to as keybinding signals,
+ * and they are expected to be defined with the `G_SIGNAL_ACTION` flag.
+ */
 export class SignalAction extends ShortcutAction {
     constructor(...args) {
         super(...args);
@@ -13,6 +19,9 @@ export class SignalAction extends ShortcutAction {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Returns the name of the signal that will be emitted.
+     */
     getSignalName() {
         return call("libgtk-4.so.1", "gtk_signal_action_get_signal_name", [
             {

package/dist/generated/gtk/signal-list-item-factory.d.ts

@@ -1,6 +1,11 @@
 import * as GObject from "../gobject/index.js";
 import { ListItemFactory } from "./list-item-factory.js";
 export declare class SignalListItemFactory extends ListItemFactory {
+    /**
+     * Creates a new `GtkSignalListItemFactory`.
+     *
+     * You need to connect signal handlers before you use it.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
     connect(signal: "bind", handler: (self: SignalListItemFactory, object: GObject.GObject) => void, after?: boolean): number;

package/dist/generated/gtk/signal-list-item-factory.js

@@ -2,6 +2,47 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 import { ListItemFactory } from "./list-item-factory.js";
+/**
+ * Emits signals to manage listitems.
+ *
+ * Signals are emitted for every listitem in the same order:
+ *
+ * 1. [signal@Gtk.SignalListItemFactory::setup] is emitted to set up permanent
+ * things on the listitem. This usually means constructing the widgets used in
+ * the row and adding them to the listitem.
+ *
+ * 2. [signal@Gtk.SignalListItemFactory::bind] is emitted to bind the item passed
+ * via [property@Gtk.ListItem:item] to the widgets that have been created in
+ * step 1 or to add item-specific widgets. Signals are connected to listen to
+ * changes - both to changes in the item to update the widgets or to changes
+ * in the widgets to update the item. After this signal has been called, the
+ * listitem may be shown in a list widget.
+ *
+ * 3. [signal@Gtk.SignalListItemFactory::unbind] is emitted to undo everything
+ * done in step 2. Usually this means disconnecting signal handlers. Once this
+ * signal has been called, the listitem will no longer be used in a list
+ * widget.
+ *
+ * 4. [signal@Gtk.SignalListItemFactory::bind] and
+ * [signal@Gtk.SignalListItemFactory::unbind] may be emitted multiple times
+ * again to bind the listitem for use with new items. By reusing listitems,
+ * potentially costly setup can be avoided. However, it means code needs to
+ * make sure to properly clean up the listitem in step 3 so that no information
+ * from the previous use leaks into the next one.
+ *
+ * 5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing
+ * the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal
+ * was emitted on a listitem, the listitem will be destroyed and not be used again.
+ *
+ * Note that during the signal emissions, changing properties on the listitems
+ * passed will not trigger notify signals as the listitem's notifications are
+ * frozen. See [method@GObject.Object.freeze_notify] for details.
+ *
+ * For tracking changes in other properties in the listitem, the
+ * ::notify signal is recommended. The signal can be connected in the
+ * [signal@Gtk.SignalListItemFactory::setup] signal and removed again during
+ * [signal@Gtk.SignalListItemFactory::teardown].
+ */
 const SIGNAL_META = {
     bind: {
         params: [
@@ -41,6 +82,11 @@ const SIGNAL_META = {
     },
 };
 export class SignalListItemFactory extends ListItemFactory {
+    /**
+     * Creates a new `GtkSignalListItemFactory`.
+     *
+     * You need to connect signal handlers before you use it.
+     */
     constructor(...args) {
         super(...args);
     }

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

@@ -2,31 +2,220 @@ import { Ref } from "@gtkx/native";
 import { Bitset } from "./bitset.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A selection model that allows selecting a single item.
+ *
+ * Note that the selection is *persistent* -- if the selected item is removed
+ * and re-added in the same [signal@Gio.ListModel::items-changed] emission, it
+ * stays selected. In particular, this means that changing the sort order of an
+ * underlying sort model will preserve the selection.
+ */
 export declare class SingleSelection extends GObject.GObject {
+    /**
+     * Creates a new selection to handle @model.
+     * @param model - the `GListModel` to manage
+     */
     constructor(model?: Gio.ListModel | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Checks if autoselect has been enabled or disabled via
+     * gtk_single_selection_set_autoselect().
+     */
     getAutoselect(): boolean;
+    /**
+     * If %TRUE, gtk_selection_model_unselect_item() is supported and allows
+     * unselecting the selected item.
+     */
     getCanUnselect(): boolean;
+    /**
+     * Gets the model that `self` is wrapping.
+     */
     getModel(): Gio.ListModel | null;
+    /**
+     * Gets the position of the selected item.
+     *
+     * If no item is selected, %GTK_INVALID_LIST_POSITION is returned.
+     */
     getSelected(): number;
+    /**
+     * Gets the selected item.
+     *
+     * If no item is selected, %NULL is returned.
+     */
     getSelectedItem(): GObject.GObject | null;
+    /**
+     * Enables or disables autoselect.
+     *
+     * If `autoselect` is %TRUE, `self` will enforce that an item is always
+     * selected. It will select a new item when the currently selected
+     * item is deleted and it will disallow unselecting the current item.
+     * @param autoselect - %TRUE to always select an item
+     */
     setAutoselect(autoselect: boolean): void;
+    /**
+     * If %TRUE, unselecting the current item via
+     * gtk_selection_model_unselect_item() is supported.
+     *
+     * Note that setting [property@Gtk.SingleSelection:autoselect] will
+     * cause unselecting to not work, so it practically makes no sense
+     * to set both at the same time.
+     * @param canUnselect - %TRUE to allow unselecting
+     */
     setCanUnselect(canUnselect: boolean): void;
+    /**
+     * Sets the model that `self` should wrap.
+     *
+     * If `model` is %NULL, `self` will be empty.
+     * @param model - A `GListModel` to wrap
+     */
     setModel(model?: Gio.ListModel | null): void;
+    /**
+     * Selects the item at the given position.
+     *
+     * If the list does not have an item at `position` or
+     * %GTK_INVALID_LIST_POSITION is given, the behavior depends on the
+     * value of the [property@Gtk.SingleSelection:autoselect] property:
+     * If it is set, no change will occur and the old item will stay
+     * selected. If it is unset, the selection will be unset and no item
+     * will be selected. This also applies if [property@Gtk.SingleSelection:can-unselect]
+     * is set to %FALSE.
+     * @param position - the item to select or %GTK_INVALID_LIST_POSITION
+     */
     setSelected(position: number): void;
+    /**
+     * Query the section that covers the given position. The number of
+     * items in the section can be computed by `out_end - out_start`.
+     *
+     * If the position is larger than the number of items, a single
+     * range from n_items to G_MAXUINT will be returned.
+     * @param position - the position of the item to query
+     * @param outStart - the position of the first item in the section
+     * @param outEnd - the position of the first item not part of the section
+     */
     getSection(position: number, outStart: Ref<number>, outEnd: Ref<number>): void;
+    /**
+     * This function emits the [signal@Gtk.SectionModel::sections-changed]
+     * signal to notify about changes to sections.
+     *
+     * It must cover all positions that used to be a section start or that
+     * are now a section start. It does not have to cover all positions for
+     * which the section has changed.
+     *
+     * The [signal@Gio.ListModel::items-changed] implies the effect of the
+     * [signal@Gtk.SectionModel::sections-changed] signal for all the items
+     * it covers.
+     *
+     * It is recommended that when changes to the items cause section changes
+     * in a larger range, that the larger range is included in the emission
+     * of the [signal@Gio.ListModel::items-changed] instead of emitting
+     * two signals.
+     * @param position - the first changed item
+     * @param nItems - the number of changed items
+     */
     sectionsChanged(position: number, nItems: number): void;
+    /**
+     * 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;
     connect(signal: "notify", handler: (self: SingleSelection, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;