@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/simple-action-group.js

@@ -3,7 +3,15 @@ import { getObject } from "@gtkx/ffi";
 import { Action } from "./action.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects,
+ * implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap]
+ * interfaces.
+ */
 export class SimpleActionGroup extends GObject.GObject {
+    /**
+     * Creates a new, empty, #GSimpleActionGroup.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -13,6 +21,13 @@ export class SimpleActionGroup extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * A convenience function for creating multiple #GSimpleAction instances
+     * and adding them to the action group.
+     * @param entries - a pointer to the first item in
+     * @param nEntries - the length of @entries, or -1
+     * @param userData - the user data for signal connections
+     */
     addEntries(entries, nEntries, userData) {
         call("libgio-2.0.so.0", "g_simple_action_group_add_entries", [
             {
@@ -37,6 +52,15 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds an action to the action group.
+     *
+     * If the action group already contains an action with the same name as
+     * `action` then the old action is dropped from the group.
+     *
+     * The action group takes its own reference on @action.
+     * @param action - a #GAction
+     */
     insert(action) {
         call("libgio-2.0.so.0", "g_simple_action_group_insert", [
             {
@@ -49,6 +73,12 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Looks up the action with the name `action_name` in the group.
+     *
+     * If no such action exists, returns %NULL.
+     * @param actionName - the name of an action
+     */
     lookup(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_simple_action_group_lookup", [
             {
@@ -62,6 +92,12 @@ export class SimpleActionGroup extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Action);
     }
+    /**
+     * Removes the named action from the action group.
+     *
+     * If no action of this name is in the group then nothing happens.
+     * @param actionName - the name of the action
+     */
     remove(actionName) {
         call("libgio-2.0.so.0", "g_simple_action_group_remove", [
             {
@@ -74,6 +110,12 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group.
+     *
+     * This function should only be called by [type@Gio.ActionGroup] implementations.
+     * @param actionName - the name of an action in the group
+     */
     actionAdded(actionName) {
         call("libgio-2.0.so.0", "g_action_group_action_added", [
             {
@@ -86,6 +128,13 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group.
+     *
+     * This function should only be called by [type@Gio.ActionGroup] implementations.
+     * @param actionName - the name of an action in the group
+     * @param enabled - whether the action is now enabled
+     */
     actionEnabledChanged(actionName, enabled) {
         call("libgio-2.0.so.0", "g_action_group_action_enabled_changed", [
             {
@@ -102,6 +151,12 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group.
+     *
+     * This function should only be called by [type@Gio.ActionGroup] implementations.
+     * @param actionName - the name of an action in the group
+     */
     actionRemoved(actionName) {
         call("libgio-2.0.so.0", "g_action_group_action_removed", [
             {
@@ -114,6 +169,13 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group.
+     *
+     * This function should only be called by [type@Gio.ActionGroup] implementations.
+     * @param actionName - the name of an action in the group
+     * @param state - the new state of the named action
+     */
     actionStateChanged(actionName, state) {
         call("libgio-2.0.so.0", "g_action_group_action_state_changed", [
             {
@@ -135,6 +197,43 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Activate the named action within @action_group.
+     *
+     * If the action is expecting a parameter, then the correct type of
+     * parameter must be given as @parameter.  If the action is expecting no
+     * parameters then `parameter` must be `NULL`.  See
+     * [method@Gio.ActionGroup.get_action_parameter_type].
+     *
+     * If the [type@Gio.ActionGroup] implementation supports asynchronous remote
+     * activation over D-Bus, this call may return before the relevant
+     * D-Bus traffic has been sent, or any replies have been received. In
+     * order to block on such asynchronous activation calls,
+     * [method@Gio.DBusConnection.flush] should be called prior to the code, which
+     * depends on the result of the action activation. Without flushing
+     * the D-Bus connection, there is no guarantee that the action would
+     * have been activated.
+     *
+     * The following code which runs in a remote app instance, shows an
+     * example of a ‘quit’ action being activated on the primary app
+     * instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called
+     * before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action
+     * may fail to be activated on the primary instance.
+     *
+     * ```c
+     * // call ‘quit’ action on primary instance
+     * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
+     *
+     * // make sure the action is activated now
+     * g_dbus_connection_flush (…);
+     *
+     * g_debug ("Application has been terminated. Exiting.");
+     *
+     * exit (0);
+     * ```
+     * @param actionName - the name of the action to activate
+     * @param parameter - parameters to the activation
+     */
     activateAction(actionName, parameter) {
         call("libgio-2.0.so.0", "g_action_group_activate_action", [
             {
@@ -157,6 +256,21 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Request for the state of the named action within `action_group` to be
+     * changed to @value.
+     *
+     * The action must be stateful and `value` must be of the correct type.
+     * See [method@Gio.ActionGroup.get_action_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.ActionGroup.get_action_state_hint].
+     *
+     * If the `value` GVariant is floating, it is consumed.
+     * @param actionName - the name of the action to request the change on
+     * @param value - the new state
+     */
     changeActionState(actionName, value) {
         call("libgio-2.0.so.0", "g_action_group_change_action_state", [
             {
@@ -178,6 +292,13 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Checks if the named action within `action_group` is currently enabled.
+     *
+     * An action must be enabled in order to be activated or in order to
+     * have its state changed from outside callers.
+     * @param actionName - the name of the action to query
+     */
     getActionEnabled(actionName) {
         return call("libgio-2.0.so.0", "g_action_group_get_action_enabled", [
             {
@@ -190,6 +311,22 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Queries the type of the parameter that must be given when activating
+     * the named action within @action_group.
+     *
+     * When activating the action using [method@Gio.ActionGroup.activate_action],
+     * 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.
+     *
+     * The parameter type of a particular action will never change but it is
+     * possible for an action to be removed and for a new action to be added
+     * with the same name but a different parameter type.
+     * @param actionName - the name of the action to query
+     */
     getActionParameterType(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_action_group_get_action_parameter_type", [
             {
@@ -210,6 +347,17 @@ export class SimpleActionGroup extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.VariantType);
     }
+    /**
+     * Queries the current state of the named action within @action_group.
+     *
+     * 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.ActionGroup.get_action_state_type].
+     *
+     * The return value (if non-`NULL`) should be freed with
+     * [method@GLib.Variant.unref] when it is no longer required.
+     * @param actionName - the name of the action to query
+     */
     getActionState(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_action_group_get_action_state", [
             {
@@ -230,6 +378,27 @@ export class SimpleActionGroup extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Requests a hint about the valid range of values for the state of the
+     * named action within @action_group.
+     *
+     * 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.
+     * @param actionName - the name of the action to query
+     */
     getActionStateHint(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_action_group_get_action_state_hint", [
             {
@@ -250,6 +419,25 @@ export class SimpleActionGroup extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Queries the type of the state of the named action within
+     * @action_group.
+     *
+     * If the action is stateful then this function returns the
+     * [type@GLib.VariantType] of the state.  All calls to
+     * [method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this
+     * type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant]
+     * of the same type.
+     *
+     * If the action is not stateful then this function will return `NULL`.
+     * In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL`
+     * and you must not call [method@Gio.ActionGroup.change_action_state].
+     *
+     * The state type of a particular action will never change but it is
+     * possible for an action to be removed and for a new action to be added
+     * with the same name but a different state type.
+     * @param actionName - the name of the action to query
+     */
     getActionStateType(actionName) {
         const ptr = call("libgio-2.0.so.0", "g_action_group_get_action_state_type", [
             {
@@ -270,6 +458,10 @@ export class SimpleActionGroup extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.VariantType);
     }
+    /**
+     * Checks if the named action exists within @action_group.
+     * @param actionName - the name of the action to check for
+     */
     hasAction(actionName) {
         return call("libgio-2.0.so.0", "g_action_group_has_action", [
             {
@@ -282,6 +474,12 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Lists the actions contained within @action_group.
+     *
+     * The caller is responsible for freeing the list with [func@GLib.strfreev] when
+     * it is no longer required.
+     */
     listActions() {
         return call("libgio-2.0.so.0", "g_action_group_list_actions", [
             {
@@ -290,6 +488,41 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Queries all aspects of the named action within an @action_group.
+     *
+     * This function acquires the information available from
+     * [method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled],
+     * [method@Gio.ActionGroup.get_action_parameter_type],
+     * [method@Gio.ActionGroup.get_action_state_type],
+     * [method@Gio.ActionGroup.get_action_state_hint] and
+     * [method@Gio.ActionGroup.get_action_state] with a single function call.
+     *
+     * This provides two main benefits.
+     *
+     * The first is the improvement in efficiency that comes with not having
+     * to perform repeated lookups of the action in order to discover
+     * different things about it.  The second is that implementing
+     * [type@Gio.ActionGroup] can now be done by only overriding this one virtual
+     * function.
+     *
+     * The interface provides a default implementation of this function that
+     * calls the individual functions, as required, to fetch the
+     * information.  The interface also provides default implementations of
+     * those functions that call this function.  All implementations,
+     * therefore, must override either this function or all of the others.
+     *
+     * If the action exists, `TRUE` is returned and any of the requested
+     * fields (as indicated by having a non-`NULL` reference passed in) are
+     * filled.  If the action doesn’t exist, `FALSE` is returned and the
+     * fields may or may not have been modified.
+     * @param actionName - the name of an action in the group
+     * @param enabled - if the action is presently enabled
+     * @param parameterType - the parameter type, or `NULL` if none needed
+     * @param stateType - the state type, or `NULL` if stateless
+     * @param stateHint - the state hint, or `NULL` if none
+     * @param state - the current state, or `NULL` if stateless
+     */
     queryAction(actionName, enabled, parameterType, stateType, stateHint, state) {
         return call("libgio-2.0.so.0", "g_action_group_query_action", [
             {
@@ -354,6 +587,15 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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", [
             {
@@ -366,6 +608,48 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -390,6 +674,12 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -405,6 +695,12 @@ export class SimpleActionGroup extends GObject.GObject {
             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", [
             {
@@ -417,6 +713,32 @@ export class SimpleActionGroup extends GObject.GObject {
             },
         ], { 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/simple-action.d.ts

@@ -1,20 +1,156 @@
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 export declare class SimpleAction extends GObject.GObject {
+    /**
+     * Creates a new action.
+     *
+     * The created action is stateless. See g_simple_action_new_stateful() to create
+     * an action that has state.
+     * @param name - the name of the action
+     * @param parameterType - the type of parameter that will be passed to
+     */
     constructor(name: string, parameterType?: GLib.VariantType | null);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new stateful action.
+     *
+     * All future state values must have the same #GVariantType as the initial
+     * @state.
+     *
+     * If the `state` #GVariant is floating, it is consumed.
+     * @param name - the name of the action
+     * @param parameterType - the type of the parameter that will be passed to
+     * @param state - the initial state of the action
+     */
     static actionNewStateful(name: string, state: GLib.Variant, parameterType?: GLib.VariantType | null): SimpleAction;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Sets the action as enabled or not.
+     *
+     * An action must be enabled in order to be activated or in order to
+     * have its state changed from outside callers.
+     *
+     * This should only be called by the implementor of the action.  Users
+     * of the action should not attempt to modify its enabled flag.
+     * @param enabled - whether the action is enabled
+     */
     setEnabled(enabled: boolean): void;
+    /**
+     * Sets the state of the action.
+     *
+     * This directly updates the 'state' property to the given value.
+     *
+     * This should only be called by the implementor of the action.  Users
+     * of the action should not attempt to directly modify the 'state'
+     * property.  Instead, they should call g_action_change_state() to
+     * request the change.
+     *
+     * If the `value` GVariant is floating, it is consumed.
+     * @param value - the new #GVariant for the state
+     */
     setState(value: GLib.Variant): void;
+    /**
+     * Sets the state hint for the action.
+     *
+     * See g_action_get_state_hint() for more information about
+     * action state hints.
+     * @param stateHint - a #GVariant representing the state hint
+     */
     setStateHint(stateHint?: GLib.Variant | null): void;
+    /**
+     * 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;
     connect(signal: "activate", handler: (self: SimpleAction, parameter: GLib.Variant) => void, after?: boolean): number;
     connect(signal: "change-state", handler: (self: SimpleAction, value: GLib.Variant) => void, after?: boolean): number;