@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -2,12 +2,82 @@ import { ShortcutActionFlags } from "./enums.js";
 import { Widget } from "./widget.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Encodes an action that can be triggered by a keyboard shortcut.
+ *
+ * `GtkShortcutActions` contain functions that allow easy presentation
+ * to end users as well as being printed for debugging.
+ *
+ * All `GtkShortcutActions` are immutable, you can only specify their
+ * properties during construction. If you want to change a action, you
+ * have to replace it with a new one. If you need to pass arguments to
+ * an action, these are specified by the higher-level `GtkShortcut` object.
+ *
+ * To activate a `GtkShortcutAction` manually, [method@Gtk.ShortcutAction.activate]
+ * can be called.
+ *
+ * GTK provides various actions:
+ *
+ * - [class@Gtk.MnemonicAction]: a shortcut action that calls
+ * gtk_widget_mnemonic_activate()
+ * - [class@Gtk.CallbackAction]: a shortcut action that invokes
+ * a given callback
+ * - [class@Gtk.SignalAction]: a shortcut action that emits a
+ * given signal
+ * - [class@Gtk.ActivateAction]: a shortcut action that calls
+ * gtk_widget_activate()
+ * - [class@Gtk.NamedAction]: a shortcut action that calls
+ * gtk_widget_activate_action()
+ * - [class@Gtk.NothingAction]: a shortcut action that does nothing
+ */
 export declare class ShortcutAction extends GObject.GObject {
+    /**
+     * Tries to parse the given string into an action.
+     *
+     * On success, the parsed action is returned. When parsing
+     * failed, %NULL is returned.
+     *
+     * The accepted strings are:
+     *
+     * - `nothing`, for `GtkNothingAction`
+     * - `activate`, for `GtkActivateAction`
+     * - `mnemonic-activate`, for `GtkMnemonicAction`
+     * - `action(NAME)`, for a `GtkNamedAction` for the action named `NAME`
+     * - `signal(NAME)`, for a `GtkSignalAction` for the signal `NAME`
+     * @param string - the string to parse
+     */
     constructor(string: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Activates the action on the `widget` with the given @args.
+     *
+     * Note that some actions ignore the passed in @flags, `widget` or @args.
+     *
+     * Activation of an action can fail for various reasons. If the action
+     * is not supported by the @widget, if the `args` don't match the action
+     * or if the activation otherwise had no effect, %FALSE will be returned.
+     * @param flags - flags to activate with
+     * @param widget - Target of the activation
+     * @param args - arguments to pass
+     */
     activate(flags: ShortcutActionFlags, widget: Widget, args?: GLib.Variant | null): boolean;
+    /**
+     * Prints the given action into a string for the developer.
+     *
+     * This is meant for debugging and logging.
+     *
+     * The form of the representation may change at any time and is
+     * not guaranteed to stay identical.
+     * @param string - a `GString` to print into
+     */
     print(string: GLib.String): void;
+    /**
+     * Prints the given action into a human-readable string.
+     *
+     * This is a small wrapper around [method@Gtk.ShortcutAction.print]
+     * to help when debugging.
+     */
     toString(): string;
     connect(signal: "notify", handler: (self: ShortcutAction, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

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

@@ -1,6 +1,34 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Encodes an action that can be triggered by a keyboard shortcut.
+ *
+ * `GtkShortcutActions` contain functions that allow easy presentation
+ * to end users as well as being printed for debugging.
+ *
+ * All `GtkShortcutActions` are immutable, you can only specify their
+ * properties during construction. If you want to change a action, you
+ * have to replace it with a new one. If you need to pass arguments to
+ * an action, these are specified by the higher-level `GtkShortcut` object.
+ *
+ * To activate a `GtkShortcutAction` manually, [method@Gtk.ShortcutAction.activate]
+ * can be called.
+ *
+ * GTK provides various actions:
+ *
+ * - [class@Gtk.MnemonicAction]: a shortcut action that calls
+ * gtk_widget_mnemonic_activate()
+ * - [class@Gtk.CallbackAction]: a shortcut action that invokes
+ * a given callback
+ * - [class@Gtk.SignalAction]: a shortcut action that emits a
+ * given signal
+ * - [class@Gtk.ActivateAction]: a shortcut action that calls
+ * gtk_widget_activate()
+ * - [class@Gtk.NamedAction]: a shortcut action that calls
+ * gtk_widget_activate_action()
+ * - [class@Gtk.NothingAction]: a shortcut action that does nothing
+ */
 export class ShortcutAction extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -14,6 +42,18 @@ export class ShortcutAction extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Activates the action on the `widget` with the given @args.
+     *
+     * Note that some actions ignore the passed in @flags, `widget` or @args.
+     *
+     * Activation of an action can fail for various reasons. If the action
+     * is not supported by the @widget, if the `args` don't match the action
+     * or if the activation otherwise had no effect, %FALSE will be returned.
+     * @param flags - flags to activate with
+     * @param widget - Target of the activation
+     * @param args - arguments to pass
+     */
     activate(flags, widget, args) {
         return call("libgtk-4.so.1", "gtk_shortcut_action_activate", [
             {
@@ -40,6 +80,15 @@ export class ShortcutAction extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Prints the given action into a string for the developer.
+     *
+     * This is meant for debugging and logging.
+     *
+     * The form of the representation may change at any time and is
+     * not guaranteed to stay identical.
+     * @param string - a `GString` to print into
+     */
     print(string) {
         call("libgtk-4.so.1", "gtk_shortcut_action_print", [
             {
@@ -57,6 +106,12 @@ export class ShortcutAction extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Prints the given action into a human-readable string.
+     *
+     * This is a small wrapper around [method@Gtk.ShortcutAction.print]
+     * to help when debugging.
+     */
     toString() {
         return call("libgtk-4.so.1", "gtk_shortcut_action_to_string", [
             {

package/dist/generated/gtk/shortcut-controller.d.ts

@@ -3,15 +3,125 @@ import { Shortcut } from "./shortcut.js";
 import * as Gdk from "../gdk/index.js";
 import * as Gio from "../gio/index.js";
 import { EventController } from "./event-controller.js";
+/**
+ * Manages keyboard shortcuts and their activation.
+ *
+ * Most common shortcuts are using this controller implicitly, e.g. by
+ * adding a mnemonic underline to a [class@Gtk.Label], or by installing a key
+ * binding using [method@Gtk.WidgetClass.add_binding], or by adding accelerators
+ * to global actions using [method@Gtk.Application.set_accels_for_action].
+ *
+ * But it is possible to create your own shortcut controller, and add
+ * shortcuts to it.
+ *
+ * `GtkShortcutController` implements [iface@Gio.ListModel] for querying the
+ * shortcuts that have been added to it.
+ *
+ * # GtkShortcutController as GtkBuildable
+ *
+ * `GtkShortcutController`s can be created in [class@Gtk.Builder] ui files, to set up
+ * shortcuts in the same place as the widgets.
+ *
+ * An example of a UI definition fragment with `GtkShortcutController`:
+ * ```xml
+ * <object class='GtkButton'>
+ * <child>
+ * <object class='GtkShortcutController'>
+ * <property name='scope'>managed</property>
+ * <child>
+ * <object class='GtkShortcut'>
+ * <property name='trigger'>&lt;Control&gt;k</property>
+ * <property name='action'>activate</property>
+ * </object>
+ * </child>
+ * </object>
+ * </child>
+ * </object>
+ * ```
+ *
+ * This example creates a [class@Gtk.ActivateAction] for triggering the
+ * `activate` signal of the [class@Gtk.Button]. See [ctor@Gtk.ShortcutAction.parse_string]
+ * for the syntax for other kinds of [class@Gtk.ShortcutAction]. See
+ * [ctor@Gtk.ShortcutTrigger.parse_string] to learn more about the syntax
+ * for triggers.
+ */
 export declare class ShortcutController extends EventController {
+    /**
+     * Creates a new shortcut controller.
+     */
     constructor(...args: unknown[]);
+    /**
+     * Creates a new shortcut controller that takes its shortcuts from
+     * the given list model.
+     *
+     * A controller created by this function does not let you add or
+     * remove individual shortcuts using the shortcut controller api,
+     * but you can change the contents of the model.
+     * @param model - a `GListModel` containing shortcuts
+     */
     static controllerNewForModel(model: Gio.ListModel): ShortcutController;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Adds `shortcut` to the list of shortcuts handled by @self.
+     *
+     * If this controller uses an external shortcut list, this
+     * function does nothing.
+     * @param shortcut - a `GtkShortcut`
+     */
     addShortcut(shortcut: Shortcut): void;
+    /**
+     * Gets the mnemonics modifiers for when this controller activates its shortcuts.
+     */
     getMnemonicsModifiers(): Gdk.ModifierType;
+    /**
+     * Gets the scope for when this controller activates its shortcuts.
+     *
+     * See [method@Gtk.ShortcutController.set_scope] for details.
+     */
     getScope(): ShortcutScope;
+    /**
+     * Removes `shortcut` from the list of shortcuts handled by @self.
+     *
+     * If `shortcut` had not been added to `controller` or this controller
+     * uses an external shortcut list, this function does nothing.
+     * @param shortcut - a `GtkShortcut`
+     */
     removeShortcut(shortcut: Shortcut): void;
+    /**
+     * Sets the controller to use the given modifier for mnemonics.
+     *
+     * The mnemonics modifiers determines which modifiers need to be pressed to allow
+     * activation of shortcuts with mnemonics triggers.
+     *
+     * GTK normally uses the Alt modifier for mnemonics, except in `GtkPopoverMenu`s,
+     * where mnemonics can be triggered without any modifiers. It should be very
+     * rarely necessary to change this, and doing so is likely to interfere with
+     * other shortcuts.
+     *
+     * This value is only relevant for local shortcut controllers. Global and managed
+     * shortcut controllers will have their shortcuts activated from other places which
+     * have their own modifiers for activating mnemonics.
+     * @param modifiers - the new mnemonics_modifiers to use
+     */
     setMnemonicsModifiers(modifiers: Gdk.ModifierType): void;
+    /**
+     * Sets the controller to have the given @scope.
+     *
+     * The scope allows shortcuts to be activated outside of the normal
+     * event propagation. In particular, it allows installing global
+     * keyboard shortcuts that can be activated even when a widget does
+     * not have focus.
+     *
+     * With %GTK_SHORTCUT_SCOPE_LOCAL, shortcuts will only be activated
+     * when the widget has focus.
+     * @param scope - the new scope to use
+     */
     setScope(scope: ShortcutScope): void;
+    /**
+     * Gets the ID of the `buildable` object.
+     *
+     * `GtkBuilder` sets the name based on the ID attribute
+     * of the `<object>` tag used to construct the @buildable.
+     */
     getBuildableId(): string | null;
 }

package/dist/generated/gtk/shortcut-controller.js

@@ -1,10 +1,64 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { EventController } from "./event-controller.js";
+/**
+ * Manages keyboard shortcuts and their activation.
+ *
+ * Most common shortcuts are using this controller implicitly, e.g. by
+ * adding a mnemonic underline to a [class@Gtk.Label], or by installing a key
+ * binding using [method@Gtk.WidgetClass.add_binding], or by adding accelerators
+ * to global actions using [method@Gtk.Application.set_accels_for_action].
+ *
+ * But it is possible to create your own shortcut controller, and add
+ * shortcuts to it.
+ *
+ * `GtkShortcutController` implements [iface@Gio.ListModel] for querying the
+ * shortcuts that have been added to it.
+ *
+ * # GtkShortcutController as GtkBuildable
+ *
+ * `GtkShortcutController`s can be created in [class@Gtk.Builder] ui files, to set up
+ * shortcuts in the same place as the widgets.
+ *
+ * An example of a UI definition fragment with `GtkShortcutController`:
+ * ```xml
+ * <object class='GtkButton'>
+ * <child>
+ * <object class='GtkShortcutController'>
+ * <property name='scope'>managed</property>
+ * <child>
+ * <object class='GtkShortcut'>
+ * <property name='trigger'>&lt;Control&gt;k</property>
+ * <property name='action'>activate</property>
+ * </object>
+ * </child>
+ * </object>
+ * </child>
+ * </object>
+ * ```
+ *
+ * This example creates a [class@Gtk.ActivateAction] for triggering the
+ * `activate` signal of the [class@Gtk.Button]. See [ctor@Gtk.ShortcutAction.parse_string]
+ * for the syntax for other kinds of [class@Gtk.ShortcutAction]. See
+ * [ctor@Gtk.ShortcutTrigger.parse_string] to learn more about the syntax
+ * for triggers.
+ */
 export class ShortcutController extends EventController {
+    /**
+     * Creates a new shortcut controller.
+     */
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new shortcut controller that takes its shortcuts from
+     * the given list model.
+     *
+     * A controller created by this function does not let you add or
+     * remove individual shortcuts using the shortcut controller api,
+     * but you can change the contents of the model.
+     * @param model - a `GListModel` containing shortcuts
+     */
     static controllerNewForModel(model) {
         const ptr = call("libgtk-4.so.1", "gtk_shortcut_controller_new_for_model", [
             {
@@ -20,6 +74,13 @@ export class ShortcutController extends EventController {
             borrowed: false,
         });
     }
+    /**
+     * Adds `shortcut` to the list of shortcuts handled by @self.
+     *
+     * If this controller uses an external shortcut list, this
+     * function does nothing.
+     * @param shortcut - a `GtkShortcut`
+     */
     addShortcut(shortcut) {
         call("libgtk-4.so.1", "gtk_shortcut_controller_add_shortcut", [
             {
@@ -32,6 +93,9 @@ export class ShortcutController extends EventController {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the mnemonics modifiers for when this controller activates its shortcuts.
+     */
     getMnemonicsModifiers() {
         return call("libgtk-4.so.1", "gtk_shortcut_controller_get_mnemonics_modifiers", [
             {
@@ -40,6 +104,11 @@ export class ShortcutController extends EventController {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the scope for when this controller activates its shortcuts.
+     *
+     * See [method@Gtk.ShortcutController.set_scope] for details.
+     */
     getScope() {
         return call("libgtk-4.so.1", "gtk_shortcut_controller_get_scope", [
             {
@@ -48,6 +117,13 @@ export class ShortcutController extends EventController {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Removes `shortcut` from the list of shortcuts handled by @self.
+     *
+     * If `shortcut` had not been added to `controller` or this controller
+     * uses an external shortcut list, this function does nothing.
+     * @param shortcut - a `GtkShortcut`
+     */
     removeShortcut(shortcut) {
         call("libgtk-4.so.1", "gtk_shortcut_controller_remove_shortcut", [
             {
@@ -60,6 +136,22 @@ export class ShortcutController extends EventController {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the controller to use the given modifier for mnemonics.
+     *
+     * The mnemonics modifiers determines which modifiers need to be pressed to allow
+     * activation of shortcuts with mnemonics triggers.
+     *
+     * GTK normally uses the Alt modifier for mnemonics, except in `GtkPopoverMenu`s,
+     * where mnemonics can be triggered without any modifiers. It should be very
+     * rarely necessary to change this, and doing so is likely to interfere with
+     * other shortcuts.
+     *
+     * This value is only relevant for local shortcut controllers. Global and managed
+     * shortcut controllers will have their shortcuts activated from other places which
+     * have their own modifiers for activating mnemonics.
+     * @param modifiers - the new mnemonics_modifiers to use
+     */
     setMnemonicsModifiers(modifiers) {
         call("libgtk-4.so.1", "gtk_shortcut_controller_set_mnemonics_modifiers", [
             {
@@ -72,6 +164,18 @@ export class ShortcutController extends EventController {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the controller to have the given @scope.
+     *
+     * The scope allows shortcuts to be activated outside of the normal
+     * event propagation. In particular, it allows installing global
+     * keyboard shortcuts that can be activated even when a widget does
+     * not have focus.
+     *
+     * With %GTK_SHORTCUT_SCOPE_LOCAL, shortcuts will only be activated
+     * when the widget has focus.
+     * @param scope - the new scope to use
+     */
     setScope(scope) {
         call("libgtk-4.so.1", "gtk_shortcut_controller_set_scope", [
             {
@@ -84,6 +188,12 @@ export class ShortcutController extends EventController {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the ID of the `buildable` object.
+     *
+     * `GtkBuilder` sets the name based on the ID attribute
+     * of the `<object>` tag used to construct the @buildable.
+     */
     getBuildableId() {
         return call("libgtk-4.so.1", "gtk_buildable_get_buildable_id", [
             {

package/dist/generated/gtk/shortcut-label.d.ts

@@ -1,12 +1,35 @@
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * `GtkShortcutLabel` displays a single keyboard shortcut or gesture.
+ *
+ * The main use case for `GtkShortcutLabel` is inside a [class@Gtk.ShortcutsWindow].
+ */
 export declare class ShortcutLabel extends Widget {
+    /**
+     * Creates a new `GtkShortcutLabel` with `accelerator` set.
+     * @param accelerator - the initial accelerator
+     */
     constructor(accelerator: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Retrieves the current accelerator of @self.
+     */
     getAccelerator(): string | null;
+    /**
+     * Retrieves the text that is displayed when no accelerator is set.
+     */
     getDisabledText(): string | null;
+    /**
+     * Sets the accelerator to be displayed by @self.
+     * @param accelerator - the new accelerator
+     */
     setAccelerator(accelerator: string): void;
+    /**
+     * Sets the text to be displayed by `self` when no accelerator is set.
+     * @param disabledText - the text to be displayed when no accelerator is set
+     */
     setDisabledText(disabledText: string): void;
     connect(signal: "notify", handler: (self: ShortcutLabel, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/shortcut-label.js

@@ -1,6 +1,11 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * `GtkShortcutLabel` displays a single keyboard shortcut or gesture.
+ *
+ * The main use case for `GtkShortcutLabel` is inside a [class@Gtk.ShortcutsWindow].
+ */
 export class ShortcutLabel extends Widget {
     constructor(...args) {
         super(...args);
@@ -14,6 +19,9 @@ export class ShortcutLabel extends Widget {
             },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Retrieves the current accelerator of @self.
+     */
     getAccelerator() {
         return call("libgtk-4.so.1", "gtk_shortcut_label_get_accelerator", [
             {
@@ -22,6 +30,9 @@ export class ShortcutLabel extends Widget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Retrieves the text that is displayed when no accelerator is set.
+     */
     getDisabledText() {
         return call("libgtk-4.so.1", "gtk_shortcut_label_get_disabled_text", [
             {
@@ -30,6 +41,10 @@ export class ShortcutLabel extends Widget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Sets the accelerator to be displayed by @self.
+     * @param accelerator - the new accelerator
+     */
     setAccelerator(accelerator) {
         call("libgtk-4.so.1", "gtk_shortcut_label_set_accelerator", [
             {
@@ -42,6 +57,10 @@ export class ShortcutLabel extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the text to be displayed by `self` when no accelerator is set.
+     * @param disabledText - the text to be displayed when no accelerator is set
+     */
     setDisabledText(disabledText) {
         call("libgtk-4.so.1", "gtk_shortcut_label_set_disabled_text", [
             {

package/dist/generated/gtk/shortcut-manager.d.ts

@@ -1,3 +1,16 @@
+/**
+ * An interface that is used to implement shortcut scopes.
+ *
+ * This is important for [iface@Gtk.Native] widgets that have their
+ * own surface, since the event controllers that are used to implement
+ * managed and global scopes are limited to the same native.
+ *
+ * Examples for widgets implementing `GtkShortcutManager` are
+ * [class@Gtk.Window] and [class@Gtk.Popover].
+ *
+ * Every widget that implements `GtkShortcutManager` will be used as a
+ * `GTK_SHORTCUT_SCOPE_MANAGED`.
+ */
 export declare class ShortcutManager {
     ptr: unknown;
     protected constructor(ptr: unknown);

package/dist/generated/gtk/shortcut-manager.js

@@ -1,3 +1,16 @@
+/**
+ * An interface that is used to implement shortcut scopes.
+ *
+ * This is important for [iface@Gtk.Native] widgets that have their
+ * own surface, since the event controllers that are used to implement
+ * managed and global scopes are limited to the same native.
+ *
+ * Examples for widgets implementing `GtkShortcutManager` are
+ * [class@Gtk.Window] and [class@Gtk.Popover].
+ *
+ * Every widget that implements `GtkShortcutManager` will be used as a
+ * `GTK_SHORTCUT_SCOPE_MANAGED`.
+ */
 export class ShortcutManager {
     ptr;
     constructor(ptr) {