@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -2,6 +2,11 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A `GSimpleAction` is the obvious simple implementation of the
+ * [iface@Gio.Action] interface. This is the easiest way to create an action for
+ * purposes of adding it to a [class@Gio.SimpleActionGroup].
+ */
 const SIGNAL_META = {
     activate: {
         params: [
@@ -20,6 +25,17 @@ export class SimpleAction extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * 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, state, parameterType) {
         const ptr = call("libgio-2.0.so.0", "g_simple_action_new_stateful", [
             {
@@ -67,6 +83,16 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * 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) {
         call("libgio-2.0.so.0", "g_simple_action_set_enabled", [
             {
@@ -79,6 +105,19 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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) {
         call("libgio-2.0.so.0", "g_simple_action_set_state", [
             {
@@ -96,6 +135,13 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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) {
         call("libgio-2.0.so.0", "g_simple_action_set_state_hint", [
             {
@@ -114,6 +160,16 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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", [
             {
@@ -132,6 +188,19 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -149,6 +218,12 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -157,6 +232,9 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Queries the name of @action.
+     */
     getName() {
         return call("libgio-2.0.so.0", "g_action_get_name", [
             {
@@ -165,6 +243,17 @@ export class SimpleAction extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -181,6 +270,16 @@ export class SimpleAction extends GObject.GObject {
             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", [
             {
@@ -197,6 +296,26 @@ export class SimpleAction extends GObject.GObject {
             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", [
             {
@@ -213,6 +332,20 @@ export class SimpleAction extends GObject.GObject {
             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/simple-async-result.d.ts

@@ -2,25 +2,327 @@ import { AsyncResult } from "./async-result.js";
 import { Cancellable } from "./cancellable.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of
+ * [class@Gio.Task], which provides a simpler API.
+ *
+ * `GSimpleAsyncResult` implements [iface@Gio.AsyncResult].
+ *
+ * `GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error
+ * reporting, operation cancellation and the final state of an operation,
+ * completely transparent to the application. Results can be returned
+ * as a pointer e.g. for functions that return data that is collected
+ * asynchronously, a boolean value for checking the success or failure
+ * of an operation, or a `gssize` for operations which return the number
+ * of bytes modified by the operation; all of the simple return cases
+ * are covered.
+ *
+ * Most of the time, an application will not need to know of the details
+ * of this API; it is handled transparently, and any necessary operations
+ * are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing
+ * a new GIO module, for writing language bindings, or for complex
+ * applications that need better control of how asynchronous operations
+ * are completed, it is important to understand this functionality.
+ *
+ * `GSimpleAsyncResult`s are tagged with the calling function to ensure
+ * that asynchronous functions and their finishing functions are used
+ * together correctly.
+ *
+ * To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new].
+ * If the result needs to be created for a `GError`, use
+ * [ctor@Gio.SimpleAsyncResult.new_from_error] or
+ * [ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available
+ * (e.g. the asynchronous operation doesn’t take a `GError` argument),
+ * but the result still needs to be created for an error condition, use
+ * [ctor@Gio.SimpleAsyncResult.new_error] (or
+ * [method@Gio.SimpleAsyncResult.set_error_va] if your application or binding
+ * requires passing a variable argument list directly), and the error can then
+ * be propagated through the use of
+ * [method@Gio.SimpleAsyncResult.propagate_error].
+ *
+ * An asynchronous operation can be made to ignore a cancellation event by
+ * calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a
+ * `GSimpleAsyncResult` for the operation and `FALSE`. This is useful for
+ * operations that are dangerous to cancel, such as close (which would
+ * cause a leak if cancelled before being run).
+ *
+ * `GSimpleAsyncResult` can integrate into GLib’s event loop,
+ * [type@GLib.MainLoop], or it can use [type@GLib.Thread]s.
+ * [method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly
+ * from the point where it is called.
+ * [method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle
+ * handler in the  thread-default main context (see
+ * [method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult`
+ * was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in
+ * a separate thread and then use
+ * [method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result.
+ *
+ * To set the results of an asynchronous function,
+ * [method@Gio.SimpleAsyncResult.set_op_res_gpointer],
+ * [method@Gio.SimpleAsyncResult.set_op_res_gboolean], and
+ * [method@Gio.SimpleAsyncResult.set_op_res_gssize]
+ * are provided, setting the operation's result to a `gpointer`, `gboolean`, or
+ * `gssize`, respectively.
+ *
+ * Likewise, to get the result of an asynchronous function,
+ * [method@Gio.SimpleAsyncResult.get_op_res_gpointer],
+ * [method@Gio.SimpleAsyncResult.get_op_res_gboolean], and
+ * [method@Gio.SimpleAsyncResult.get_op_res_gssize] are
+ * provided, getting the operation’s result as a `gpointer`, `gboolean`, and
+ * `gssize`, respectively.
+ *
+ * For the details of the requirements implementations must respect, see
+ * [iface@Gio.AsyncResult].  A typical implementation of an asynchronous
+ * operation using `GSimpleAsyncResult` looks something like this:
+ *
+ * ```c
+ * static void
+ * baked_cb (Cake    *cake,
+ * gpointer user_data)
+ * {
+ * // In this example, this callback is not given a reference to the cake,
+ * // so the GSimpleAsyncResult has to take a reference to it.
+ * GSimpleAsyncResult *result = user_data;
+ *
+ * if (cake == NULL)
+ * g_simple_async_result_set_error (result,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * else
+ * g_simple_async_result_set_op_res_gpointer (result,
+ * g_object_ref (cake),
+ * g_object_unref);
+ *
+ *
+ * // In this example, we assume that baked_cb is called as a callback from
+ * // the mainloop, so it's safe to complete the operation synchronously here.
+ * // If, however, _baker_prepare_cake () might call its callback without
+ * // first returning to the mainloop — inadvisable, but some APIs do so —
+ * // we would need to use g_simple_async_result_complete_in_idle().
+ * g_simple_async_result_complete (result);
+ * g_object_unref (result);
+ * }
+ *
+ * void
+ * baker_bake_cake_async (Baker              *self,
+ * guint               radius,
+ * GAsyncReadyCallback callback,
+ * gpointer            user_data)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake               *cake;
+ *
+ * if (radius < 3)
+ * {
+ * g_simple_async_report_error_in_idle (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_TOO_SMALL,
+ * "%ucm radius cakes are silly",
+ * radius);
+ * return;
+ * }
+ *
+ * simple = g_simple_async_result_new (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * baker_bake_cake_async);
+ * cake = _baker_get_cached_cake (self, radius);
+ *
+ * if (cake != NULL)
+ * {
+ * g_simple_async_result_set_op_res_gpointer (simple,
+ * g_object_ref (cake),
+ * g_object_unref);
+ * g_simple_async_result_complete_in_idle (simple);
+ * g_object_unref (simple);
+ * // Drop the reference returned by _baker_get_cached_cake();
+ * // the GSimpleAsyncResult has taken its own reference.
+ * g_object_unref (cake);
+ * return;
+ * }
+ *
+ * _baker_prepare_cake (self, radius, baked_cb, simple);
+ * }
+ *
+ * Cake *
+ * baker_bake_cake_finish (Baker        *self,
+ * GAsyncResult *result,
+ * GError      **error)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake               *cake;
+ *
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (self),
+ * baker_bake_cake_async),
+ * NULL);
+ *
+ * simple = (GSimpleAsyncResult *) result;
+ *
+ * if (g_simple_async_result_propagate_error (simple, error))
+ * return NULL;
+ *
+ * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
+ * return g_object_ref (cake);
+ * }
+ * ```
+ */
 export declare class SimpleAsyncResult extends GObject.GObject {
+    /**
+     * Creates a #GSimpleAsyncResult.
+     *
+     * The common convention is to create the #GSimpleAsyncResult in the
+     * function that starts the asynchronous operation and use that same
+     * function as the @source_tag.
+     *
+     * If your operation supports cancellation with #GCancellable (which it
+     * probably should) then you should provide the user's cancellable to
+     * g_simple_async_result_set_check_cancellable() immediately after
+     * this function returns.
+     * @param sourceObject - a #GObject, or %NULL.
+     * @param callback - a #GAsyncReadyCallback.
+     * @param userData - user data passed to @callback.
+     * @param sourceTag - the asynchronous function.
+     */
     constructor(sourceObject?: GObject.GObject | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null, sourceTag?: number | null);
     constructor(...args: unknown[]);
+    /**
+     * Creates a #GSimpleAsyncResult from an error condition.
+     * @param sourceObject - a #GObject, or %NULL.
+     * @param callback - a #GAsyncReadyCallback.
+     * @param userData - user data passed to @callback.
+     * @param error - a #GError
+     */
     static asyncResultNewFromError(error: GLib.GError, sourceObject?: GObject.GObject | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): SimpleAsyncResult;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Ensures that the data passed to the _finish function of an async
+     * operation is consistent.  Three checks are performed.
+     *
+     * First, `result` is checked to ensure that it is really a
+     * #GSimpleAsyncResult.  Second, `source` is checked to ensure that it
+     * matches the source object of @result.  Third, `source_tag` is
+     * checked to ensure that it is equal to the `source_tag` argument given
+     * to g_simple_async_result_new() (which, by convention, is a pointer
+     * to the _async function corresponding to the _finish function from
+     * which this function is called).  (Alternatively, if either
+     * `source_tag` or @result's source tag is %NULL, then the source tag
+     * check is skipped.)
+     * @param result - the #GAsyncResult passed to the _finish function.
+     * @param source - the #GObject passed to the _finish function.
+     * @param sourceTag - the asynchronous function.
+     */
     static isValid(result: AsyncResult, source?: GObject.GObject | null, sourceTag?: number | null): boolean;
+    /**
+     * Completes an asynchronous I/O job immediately. Must be called in
+     * the thread where the asynchronous result was to be delivered, as it
+     * invokes the callback directly. If you are in a different thread use
+     * g_simple_async_result_complete_in_idle().
+     *
+     * Calling this function takes a reference to `simple` for as long as
+     * is needed to complete the call.
+     */
     complete(): void;
+    /**
+     * Completes an asynchronous function in an idle handler in the
+     * thread-default main context (see [method@GLib.MainContext.push_thread_default])
+     * of the thread that `simple` was initially created in
+     * (and re-pushes that context around the invocation of the callback).
+     *
+     * Calling this function takes a reference to `simple` for as long as
+     * is needed to complete the call.
+     */
     completeInIdle(): void;
+    /**
+     * Gets the operation result boolean from within the asynchronous result.
+     */
     getOpResGboolean(): boolean;
+    /**
+     * Gets a gssize from the asynchronous result.
+     */
     getOpResGssize(): number;
+    /**
+     * Propagates an error from within the simple asynchronous result to
+     * a given destination.
+     *
+     * If the #GCancellable given to a prior call to
+     * g_simple_async_result_set_check_cancellable() is cancelled then this
+     * function will return %TRUE with `dest` set appropriately.
+     */
     propagateError(): boolean;
+    /**
+     * Sets a #GCancellable to check before dispatching results.
+     *
+     * This function has one very specific purpose: the provided cancellable
+     * is checked at the time of g_simple_async_result_propagate_error() If
+     * it is cancelled, these functions will return an "Operation was
+     * cancelled" error (%G_IO_ERROR_CANCELLED).
+     *
+     * Implementors of cancellable asynchronous functions should use this in
+     * order to provide a guarantee to their callers that cancelling an
+     * async operation will reliably result in an error being returned for
+     * that operation (even if a positive result for the operation has
+     * already been sent as an idle to the main context to be dispatched).
+     *
+     * The checking described above is done regardless of any call to the
+     * unrelated g_simple_async_result_set_handle_cancellation() function.
+     * @param checkCancellable - a #GCancellable to check, or %NULL to unset
+     */
     setCheckCancellable(checkCancellable?: Cancellable | null): void;
+    /**
+     * Sets the result from a #GError.
+     * @param error - #GError.
+     */
     setFromError(error: GLib.GError): void;
+    /**
+     * Sets whether to handle cancellation within the asynchronous operation.
+     *
+     * This function has nothing to do with
+     * g_simple_async_result_set_check_cancellable().  It only refers to the
+     * #GCancellable passed to g_simple_async_result_run_in_thread().
+     * @param handleCancellation - a #gboolean.
+     */
     setHandleCancellation(handleCancellation: boolean): void;
+    /**
+     * Sets the operation result to a boolean within the asynchronous result.
+     * @param opRes - a #gboolean.
+     */
     setOpResGboolean(opRes: boolean): void;
+    /**
+     * Sets the operation result within the asynchronous result to
+     * the given @op_res.
+     * @param opRes - a #gssize.
+     */
     setOpResGssize(opRes: number): void;
+    /**
+     * Gets the source object from a [iface@Gio.AsyncResult].
+     */
     getSourceObject(): GObject.GObject | null;
+    /**
+     * Gets the user data from a [iface@Gio.AsyncResult].
+     */
     getUserData(): number | null;
+    /**
+     * Checks if `res` has the given `source_tag` (generally a function
+     * pointer indicating the function `res` was created by).
+     * @param sourceTag - an application-defined tag
+     */
     isTagged(sourceTag?: number | null): boolean;
+    /**
+     * If `res` is a [class@Gio.SimpleAsyncResult], this is equivalent to
+     * [method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns
+     * `FALSE`.
+     *
+     * This can be used for legacy error handling in async `*_finish()`
+     * wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult]
+     * error returns themselves rather than calling into the virtual method.
+     * This should not be used in new code; [iface@Gio.AsyncResult] errors that are
+     * set by virtual methods should also be extracted by virtual methods,
+     * to enable subclasses to chain up correctly.
+     */
     legacyPropagateError(): boolean;
     connect(signal: "notify", handler: (self: SimpleAsyncResult, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;