@gtkx/ffi 0.1.44 → 0.1.46

package/dist/generated/gio/action-map.d.ts

@@ -1,11 +1,113 @@
 import { Action } from "./action.js";
+/**
+ * `GActionMap` is an interface for action containers.
+ *
+ * The `GActionMap` interface is implemented by [iface@Gio.ActionGroup]
+ * implementations that operate by containing a number of named
+ * [iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup].
+ *
+ * One useful application of this interface is to map the
+ * names of actions from various action groups to unique,
+ * prefixed names (e.g. by prepending "app." or "win.").
+ * This is the motivation for the ‘Map’ part of the interface
+ * name.
+ */
 export declare class ActionMap {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): ActionMap;
+    /**
+     * Adds an action to the @action_map.
+     *
+     * If the action map already contains an action with the same name
+     * as `action` then the old action is dropped from the action map.
+     *
+     * The action map takes its own reference on @action.
+     * @param action - a [iface@Gio.Action]
+     */
     addAction(action: Action): void;
+    /**
+     * A convenience function for creating multiple [class@Gio.SimpleAction]
+     * instances and adding them to a [iface@Gio.ActionMap].
+     *
+     * Each action is constructed as per one [struct@Gio.ActionEntry].
+     *
+     * ```c
+     * static void
+     * activate_quit (GSimpleAction *simple,
+     * GVariant      *parameter,
+     * gpointer       user_data)
+     * {
+     * exit (0);
+     * }
+     *
+     * static void
+     * activate_print_string (GSimpleAction *simple,
+     * GVariant      *parameter,
+     * gpointer       user_data)
+     * {
+     * g_print ("%s\n", g_variant_get_string (parameter, NULL));
+     * }
+     *
+     * static GActionGroup *
+     * create_action_group (void)
+     * {
+     * const GActionEntry entries[] = {
+     * { "quit",         activate_quit              },
+     * { "print-string", activate_print_string, "s" }
+     * };
+     * GSimpleActionGroup *group;
+     *
+     * group = g_simple_action_group_new ();
+     * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+     *
+     * return G_ACTION_GROUP (group);
+     * }
+     * ```
+     * @param entries - a pointer to
+     * @param nEntries - the length of @entries, or -1 if `entries` is `NULL`-terminated
+     * @param userData - the user data for signal connections
+     */
     addActionEntries(entries: number[], nEntries: number, userData?: number | null): void;
+    /**
+     * Looks up the action with the name `action_name` in @action_map.
+     *
+     * If no such action exists, returns `NULL`.
+     * @param actionName - the name of an action
+     */
     lookupAction(actionName: string): Action | null;
+    /**
+     * Removes the named action from the action map.
+     *
+     * If no action of this name is in the map then nothing happens.
+     * @param actionName - the name of the action
+     */
     removeAction(actionName: string): void;
+    /**
+     * Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of
+     * [method@Gio.ActionMap.add_action_entries].
+     *
+     *
+     * ```c
+     * static const GActionEntry entries[] = {
+     * { "quit",         activate_quit              },
+     * { "print-string", activate_print_string, "s" }
+     * };
+     *
+     * void
+     * add_actions (GActionMap *map)
+     * {
+     * g_action_map_add_action_entries (map, entries, G_N_ELEMENTS (entries), NULL);
+     * }
+     *
+     * void
+     * remove_actions (GActionMap *map)
+     * {
+     * g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries));
+     * }
+     * ```
+     * @param entries - a pointer to
+     * @param nEntries - the length of @entries, or -1 if `entries` is `NULL`-terminated
+     */
     removeActionEntries(entries: number[], nEntries: number): void;
 }

package/dist/generated/gio/action-map.js

@@ -1,6 +1,19 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Action } from "./action.js";
+/**
+ * `GActionMap` is an interface for action containers.
+ *
+ * The `GActionMap` interface is implemented by [iface@Gio.ActionGroup]
+ * implementations that operate by containing a number of named
+ * [iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup].
+ *
+ * One useful application of this interface is to map the
+ * names of actions from various action groups to unique,
+ * prefixed names (e.g. by prepending "app." or "win.").
+ * This is the motivation for the ‘Map’ part of the interface
+ * name.
+ */
 export class ActionMap {
     ptr;
     constructor(ptr) {
@@ -9,6 +22,15 @@ export class ActionMap {
     static fromPtr(ptr) {
         return new ActionMap(ptr);
     }
+    /**
+     * Adds an action to the @action_map.
+     *
+     * If the action map already contains an action with the same name
+     * as `action` then the old action is dropped from the action map.
+     *
+     * The action map takes its own reference on @action.
+     * @param action - a [iface@Gio.Action]
+     */
     addAction(action) {
         call("libgio-2.0.so.0", "g_action_map_add_action", [
             {
@@ -21,6 +43,48 @@ export class ActionMap {
             },
         ], { type: "undefined" });
     }
+    /**
+     * A convenience function for creating multiple [class@Gio.SimpleAction]
+     * instances and adding them to a [iface@Gio.ActionMap].
+     *
+     * Each action is constructed as per one [struct@Gio.ActionEntry].
+     *
+     * ```c
+     * static void
+     * activate_quit (GSimpleAction *simple,
+     * GVariant      *parameter,
+     * gpointer       user_data)
+     * {
+     * exit (0);
+     * }
+     *
+     * static void
+     * activate_print_string (GSimpleAction *simple,
+     * GVariant      *parameter,
+     * gpointer       user_data)
+     * {
+     * g_print ("%s\n", g_variant_get_string (parameter, NULL));
+     * }
+     *
+     * static GActionGroup *
+     * create_action_group (void)
+     * {
+     * const GActionEntry entries[] = {
+     * { "quit",         activate_quit              },
+     * { "print-string", activate_print_string, "s" }
+     * };
+     * GSimpleActionGroup *group;
+     *
+     * group = g_simple_action_group_new ();
+     * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+     *
+     * return G_ACTION_GROUP (group);
+     * }
+     * ```
+     * @param entries - a pointer to
+     * @param nEntries - the length of @entries, or -1 if `entries` is `NULL`-terminated
+     * @param userData - the user data for signal connections
+     */
     addActionEntries(entries, nEntries, userData) {
         call("libgio-2.0.so.0", "g_action_map_add_action_entries", [
             {
@@ -45,6 +109,12 @@ export class ActionMap {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Looks up the action with the name `action_name` in @action_map.
+     *
+     * If no such action exists, returns `NULL`.
+     * @param actionName - the name of an action
+     */
     lookupAction(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_action_map_lookup_action", [
             {
@@ -60,6 +130,12 @@ export class ActionMap {
             return null;
         return getObject(ptr, Action);
     }
+    /**
+     * Removes the named action from the action map.
+     *
+     * If no action of this name is in the map then nothing happens.
+     * @param actionName - the name of the action
+     */
     removeAction(actionName) {
         call("libgio-2.0.so.0", "g_action_map_remove_action", [
             {
@@ -72,6 +148,32 @@ export class ActionMap {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of
+     * [method@Gio.ActionMap.add_action_entries].
+     *
+     *
+     * ```c
+     * static const GActionEntry entries[] = {
+     * { "quit",         activate_quit              },
+     * { "print-string", activate_print_string, "s" }
+     * };
+     *
+     * void
+     * add_actions (GActionMap *map)
+     * {
+     * g_action_map_add_action_entries (map, entries, G_N_ELEMENTS (entries), NULL);
+     * }
+     *
+     * void
+     * remove_actions (GActionMap *map)
+     * {
+     * g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries));
+     * }
+     * ```
+     * @param entries - a pointer to
+     * @param nEntries - the length of @entries, or -1 if `entries` is `NULL`-terminated
+     */
     removeActionEntries(entries, nEntries) {
         call("libgio-2.0.so.0", "g_action_map_remove_action_entries", [
             {

package/dist/generated/gio/action.d.ts

@@ -1,14 +1,132 @@
 import * as GLib from "../glib/index.js";
+/**
+ * `GAction` represents a single named action.
+ *
+ * The main interface to an action is that it can be activated with
+ * [method@Gio.Action.activate]. This results in the 'activate' signal being
+ * emitted. An activation has a `GVariant` parameter (which may be
+ * `NULL`). The correct type for the parameter is determined by a static
+ * parameter type (which is given at construction time).
+ *
+ * An action may optionally have a state, in which case the state may be
+ * set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The
+ * correct type for the state is determined by a static state type
+ * (which is given at construction time).
+ *
+ * The state may have a hint associated with it, specifying its valid
+ * range.
+ *
+ * `GAction` is merely the interface to the concept of an action, as
+ * described above.  Various implementations of actions exist, including
+ * [class@Gio.SimpleAction].
+ *
+ * In all cases, the implementing class is responsible for storing the
+ * name of the action, the parameter type, the enabled state, the optional
+ * state type and the state and emitting the appropriate signals when these
+ * change. The implementor is responsible for filtering calls to
+ * [method@Gio.Action.activate] and [method@Gio.Action.change_state]
+ * for type safety and for the state being enabled.
+ *
+ * Probably the only useful thing to do with a `GAction` is to put it
+ * inside of a [class@Gio.SimpleActionGroup].
+ */
 export declare class Action {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): Action;
+    /**
+     * Activates the action.
+     *
+     * `parameter` must be the correct type of parameter for the action (ie:
+     * the parameter type given at construction time).  If the parameter
+     * type was `NULL` then `parameter` must also be `NULL`.
+     *
+     * If the `parameter` [type@GLib.Variant] is floating, it is consumed.
+     * @param parameter - the parameter to the activation
+     */
     activate(parameter?: GLib.Variant | null): void;
+    /**
+     * Request for the state of `action` to be changed to @value.
+     *
+     * The action must be stateful and `value` must be of the correct type.
+     * See [method@Gio.Action.get_state_type].
+     *
+     * This call merely requests a change.  The action may refuse to change
+     * its state or may change its state to something other than @value.
+     * See [method@Gio.Action.get_state_hint].
+     *
+     * If the `value` [type@GLib.Variant] is floating, it is consumed.
+     * @param value - the new state
+     */
     changeState(value: GLib.Variant): void;
+    /**
+     * Checks if `action` is currently enabled.
+     *
+     * An action must be enabled in order to be activated or in order to
+     * have its state changed from outside callers.
+     */
     getEnabled(): boolean;
+    /**
+     * Queries the name of @action.
+     */
     getName(): string;
+    /**
+     * Queries the type of the parameter that must be given when activating
+     * @action.
+     *
+     * When activating the action using [method@Gio.Action.activate], the
+     * [type@GLib.Variant] given to that function must be of the type returned by
+     * this function.
+     *
+     * In the case that this function returns `NULL`, you must not give any
+     * [type@GLib.Variant], but `NULL` instead.
+     */
     getParameterType(): GLib.VariantType | null;
+    /**
+     * Queries the current state of @action.
+     *
+     * If the action is not stateful then `NULL` will be returned.  If the
+     * action is stateful then the type of the return value is the type
+     * given by [method@Gio.Action.get_state_type].
+     *
+     * The return value (if non-`NULL`) should be freed with
+     * [method@GLib.Variant.unref] when it is no longer required.
+     */
     getState(): GLib.Variant | null;
+    /**
+     * Requests a hint about the valid range of values for the state of
+     * @action.
+     *
+     * If `NULL` is returned it either means that the action is not stateful
+     * or that there is no hint about the valid range of values for the
+     * state of the action.
+     *
+     * If a [type@GLib.Variant] array is returned then each item in the array is a
+     * possible value for the state.  If a [type@GLib.Variant] pair (ie: two-tuple) is
+     * returned then the tuple specifies the inclusive lower and upper bound
+     * of valid values for the state.
+     *
+     * In any case, the information is merely a hint.  It may be possible to
+     * have a state value outside of the hinted range and setting a value
+     * within the range may fail.
+     *
+     * The return value (if non-`NULL`) should be freed with
+     * [method@GLib.Variant.unref] when it is no longer required.
+     */
     getStateHint(): GLib.Variant | null;
+    /**
+     * Queries the type of the state of @action.
+     *
+     * If the action is stateful (e.g. created with
+     * [ctor@Gio.SimpleAction.new_stateful]) then this function returns the
+     * [type@GLib.VariantType] of the state.  This is the type of the initial value
+     * given as the state. All calls to [method@Gio.Action.change_state] must give a
+     * [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a
+     * [type@GLib.Variant] of the same type.
+     *
+     * If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new])
+     * then this function will return `NULL`. In that case, [method@Gio.Action.get_state]
+     * will return `NULL` and you must not call [method@Gio.Action.change_state].
+     */
     getStateType(): GLib.VariantType | null;
 }

package/dist/generated/gio/action.js

@@ -1,6 +1,37 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
+/**
+ * `GAction` represents a single named action.
+ *
+ * The main interface to an action is that it can be activated with
+ * [method@Gio.Action.activate]. This results in the 'activate' signal being
+ * emitted. An activation has a `GVariant` parameter (which may be
+ * `NULL`). The correct type for the parameter is determined by a static
+ * parameter type (which is given at construction time).
+ *
+ * An action may optionally have a state, in which case the state may be
+ * set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The
+ * correct type for the state is determined by a static state type
+ * (which is given at construction time).
+ *
+ * The state may have a hint associated with it, specifying its valid
+ * range.
+ *
+ * `GAction` is merely the interface to the concept of an action, as
+ * described above.  Various implementations of actions exist, including
+ * [class@Gio.SimpleAction].
+ *
+ * In all cases, the implementing class is responsible for storing the
+ * name of the action, the parameter type, the enabled state, the optional
+ * state type and the state and emitting the appropriate signals when these
+ * change. The implementor is responsible for filtering calls to
+ * [method@Gio.Action.activate] and [method@Gio.Action.change_state]
+ * for type safety and for the state being enabled.
+ *
+ * Probably the only useful thing to do with a `GAction` is to put it
+ * inside of a [class@Gio.SimpleActionGroup].
+ */
 export class Action {
     ptr;
     constructor(ptr) {
@@ -9,6 +40,16 @@ export class Action {
     static fromPtr(ptr) {
         return new Action(ptr);
     }
+    /**
+     * Activates the action.
+     *
+     * `parameter` must be the correct type of parameter for the action (ie:
+     * the parameter type given at construction time).  If the parameter
+     * type was `NULL` then `parameter` must also be `NULL`.
+     *
+     * If the `parameter` [type@GLib.Variant] is floating, it is consumed.
+     * @param parameter - the parameter to the activation
+     */
     activate(parameter) {
         call("libgio-2.0.so.0", "g_action_activate", [
             {
@@ -27,6 +68,19 @@ export class Action {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Request for the state of `action` to be changed to @value.
+     *
+     * The action must be stateful and `value` must be of the correct type.
+     * See [method@Gio.Action.get_state_type].
+     *
+     * This call merely requests a change.  The action may refuse to change
+     * its state or may change its state to something other than @value.
+     * See [method@Gio.Action.get_state_hint].
+     *
+     * If the `value` [type@GLib.Variant] is floating, it is consumed.
+     * @param value - the new state
+     */
     changeState(value) {
         call("libgio-2.0.so.0", "g_action_change_state", [
             {
@@ -44,6 +98,12 @@ export class Action {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Checks if `action` is currently enabled.
+     *
+     * An action must be enabled in order to be activated or in order to
+     * have its state changed from outside callers.
+     */
     getEnabled() {
         return call("libgio-2.0.so.0", "g_action_get_enabled", [
             {
@@ -52,6 +112,9 @@ export class Action {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Queries the name of @action.
+     */
     getName() {
         return call("libgio-2.0.so.0", "g_action_get_name", [
             {
@@ -60,6 +123,17 @@ export class Action {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Queries the type of the parameter that must be given when activating
+     * @action.
+     *
+     * When activating the action using [method@Gio.Action.activate], the
+     * [type@GLib.Variant] given to that function must be of the type returned by
+     * this function.
+     *
+     * In the case that this function returns `NULL`, you must not give any
+     * [type@GLib.Variant], but `NULL` instead.
+     */
     getParameterType() {
         const ptr = call("libgio-2.0.so.0", "g_action_get_parameter_type", [
             {
@@ -76,6 +150,16 @@ export class Action {
             return null;
         return getObject(ptr, GLib.VariantType);
     }
+    /**
+     * Queries the current state of @action.
+     *
+     * If the action is not stateful then `NULL` will be returned.  If the
+     * action is stateful then the type of the return value is the type
+     * given by [method@Gio.Action.get_state_type].
+     *
+     * The return value (if non-`NULL`) should be freed with
+     * [method@GLib.Variant.unref] when it is no longer required.
+     */
     getState() {
         const ptr = call("libgio-2.0.so.0", "g_action_get_state", [
             {
@@ -92,6 +176,26 @@ export class Action {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Requests a hint about the valid range of values for the state of
+     * @action.
+     *
+     * If `NULL` is returned it either means that the action is not stateful
+     * or that there is no hint about the valid range of values for the
+     * state of the action.
+     *
+     * If a [type@GLib.Variant] array is returned then each item in the array is a
+     * possible value for the state.  If a [type@GLib.Variant] pair (ie: two-tuple) is
+     * returned then the tuple specifies the inclusive lower and upper bound
+     * of valid values for the state.
+     *
+     * In any case, the information is merely a hint.  It may be possible to
+     * have a state value outside of the hinted range and setting a value
+     * within the range may fail.
+     *
+     * The return value (if non-`NULL`) should be freed with
+     * [method@GLib.Variant.unref] when it is no longer required.
+     */
     getStateHint() {
         const ptr = call("libgio-2.0.so.0", "g_action_get_state_hint", [
             {
@@ -108,6 +212,20 @@ export class Action {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Queries the type of the state of @action.
+     *
+     * If the action is stateful (e.g. created with
+     * [ctor@Gio.SimpleAction.new_stateful]) then this function returns the
+     * [type@GLib.VariantType] of the state.  This is the type of the initial value
+     * given as the state. All calls to [method@Gio.Action.change_state] must give a
+     * [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a
+     * [type@GLib.Variant] of the same type.
+     *
+     * If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new])
+     * then this function will return `NULL`. In that case, [method@Gio.Action.get_state]
+     * will return `NULL` and you must not call [method@Gio.Action.change_state].
+     */
     getStateType() {
         const ptr = call("libgio-2.0.so.0", "g_action_get_state_type", [
             {

package/dist/generated/gio/app-info-monitor.d.ts

@@ -2,6 +2,21 @@ import * as GObject from "../gobject/index.js";
 export declare class AppInfoMonitor extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the #GAppInfoMonitor for the current thread-default main
+     * context.
+     *
+     * The #GAppInfoMonitor will emit a “changed” signal in the
+     * thread-default main context whenever the list of installed
+     * applications (as reported by g_app_info_get_all()) may have changed.
+     *
+     * The #GAppInfoMonitor::changed signal will only be emitted once until
+     * g_app_info_get_all() (or another `g_app_info_*()` function) is called. Doing
+     * so will re-arm the signal ready to notify about the next change.
+     *
+     * You must only call g_object_unref() on the return value from under
+     * the same main context as you created it.
+     */
     static get(): AppInfoMonitor;
     connect(signal: "changed", handler: (self: AppInfoMonitor) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: AppInfoMonitor, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gio/app-info-monitor.js

@@ -1,6 +1,47 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GAppInfoMonitor` monitors application information for changes.
+ *
+ * `GAppInfoMonitor` is a very simple object used for monitoring the app
+ * info database for changes (newly installed or removed applications).
+ *
+ * Call [func@Gio.AppInfoMonitor.get] to get a `GAppInfoMonitor` and connect
+ * to the [signal@Gio.AppInfoMonitor::changed] signal. The signal will be emitted once when
+ * the app info database changes, and will not be emitted again until after the
+ * next call to [func@Gio.AppInfo.get_all] or another `g_app_info_*()` function.
+ * This is because monitoring the app info database for changes is expensive.
+ *
+ * The following functions will re-arm the [signal@Gio.AppInfoMonitor::changed]
+ * signal so it can be emitted again:
+ *
+ * - [func@Gio.AppInfo.get_all]
+ * - [func@Gio.AppInfo.get_all_for_type]
+ * - [func@Gio.AppInfo.get_default_for_type]
+ * - [func@Gio.AppInfo.get_fallback_for_type]
+ * - [func@Gio.AppInfo.get_recommended_for_type]
+ * - `g_desktop_app_info_get_implementations()`
+ * - `g_desktop_app_info_new()`
+ * - `g_desktop_app_info_new_from_filename()`
+ * - `g_desktop_app_info_new_from_keyfile()`
+ * - `g_desktop_app_info_search()`
+ *
+ * The latter functions are available if using
+ * `GDesktopAppInfo` from
+ * `gio-unix-2.0.pc` (GIR namespace `GioUnix-2.0`).
+ *
+ * In the usual case, applications should try to make note of the change
+ * (doing things like invalidating caches) but not act on it. In
+ * particular, applications should avoid making calls to `GAppInfo` APIs
+ * in response to the change signal, deferring these until the time that
+ * the updated data is actually required. The exception to this case is when
+ * application information is actually being displayed on the screen
+ * (for example, during a search or when the list of all applications is shown).
+ * The reason for this is that changes to the list of installed applications
+ * often come in groups (like during system updates) and rescanning the list
+ * on every change is pointless and expensive.
+ */
 const SIGNAL_META = {
     changed: { params: [], returnType: { type: "undefined" } },
 };
@@ -19,6 +60,21 @@ export class AppInfoMonitor extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Gets the #GAppInfoMonitor for the current thread-default main
+     * context.
+     *
+     * The #GAppInfoMonitor will emit a “changed” signal in the
+     * thread-default main context whenever the list of installed
+     * applications (as reported by g_app_info_get_all()) may have changed.
+     *
+     * The #GAppInfoMonitor::changed signal will only be emitted once until
+     * g_app_info_get_all() (or another `g_app_info_*()` function) is called. Doing
+     * so will re-arm the signal ready to notify about the next change.
+     *
+     * You must only call g_object_unref() on the return value from under
+     * the same main context as you created it.
+     */
     static get() {
         const ptr = call("libgio-2.0.so.0", "g_app_info_monitor_get", [], {
             type: "gobject",