@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gobject/closure.d.ts

@@ -1,19 +1,206 @@
 import { Ref } from "@gtkx/native";
 import { Value } from "./value.js";
 import { GObject } from "./object.js";
+/**
+ * A `GClosure` represents a callback supplied by the programmer.
+ *
+ * It will generally comprise a function of some kind and a marshaller
+ * used to call it. It is the responsibility of the marshaller to
+ * convert the arguments for the invocation from #GValues into
+ * a suitable form, perform the callback on the converted arguments,
+ * and transform the return value back into a #GValue.
+ *
+ * In the case of C programs, a closure usually just holds a pointer
+ * to a function and maybe a data argument, and the marshaller
+ * converts between #GValue and native C types. The GObject
+ * library provides the #GCClosure type for this purpose. Bindings for
+ * other languages need marshallers which convert between #GValues
+ * and suitable representations in the runtime of the language in
+ * order to use functions written in that language as callbacks. Use
+ * g_closure_set_marshal() to set the marshaller on such a custom
+ * closure implementation.
+ *
+ * Within GObject, closures play an important role in the
+ * implementation of signals. When a signal is registered, the
+ * `c_marshaller` argument to g_signal_new() specifies the default C
+ * marshaller for any closure which is connected to this
+ * signal. GObject provides a number of C marshallers for this
+ * purpose, see the g_cclosure_marshal_*() functions. Additional C
+ * marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
+ * utility.  Closures can be explicitly connected to signals with
+ * g_signal_connect_closure(), but it usually more convenient to let
+ * GObject create a closure automatically by using one of the
+ * g_signal_connect_*() functions which take a callback function/user
+ * data pair.
+ *
+ * Using closures has a number of important advantages over a simple
+ * callback function/data pointer combination:
+ *
+ * - Closures allow the callee to get the types of the callback parameters,
+ * which means that language bindings don't have to write individual glue
+ * for each callback type.
+ *
+ * - The reference counting of #GClosure makes it easy to handle reentrancy
+ * right; if a callback is removed while it is being invoked, the closure
+ * and its parameters won't be freed until the invocation finishes.
+ *
+ * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
+ * automatically removed when the objects they point to go away.
+ */
 export declare class Closure {
     ptr: unknown;
+    /**
+     * A variant of g_closure_new_simple() which stores `object` in the
+     * `data` field of the closure and calls g_object_watch_closure() on
+     * `object` and the created closure. This function is mainly useful
+     * when implementing new types of closures.
+     * @param sizeofClosure - the size of the structure to allocate, must be at least
+     * @param object - a #GObject pointer to store in the `data` field of the newly
+     */
     constructor(sizeofClosure: number, object: GObject);
     constructor(_args: unknown[]);
+    /**
+     * Allocates a struct of the given size and initializes the initial
+     * part as a #GClosure.
+     *
+     * This function is mainly useful when implementing new types of closures:
+     *
+     * |[<!-- language="C" -->
+     * typedef struct _MyClosure MyClosure;
+     * struct _MyClosure
+     * {
+     * GClosure closure;
+     * // extra data goes here
+     * };
+     *
+     * static void
+     * my_closure_finalize (gpointer  notify_data,
+     * GClosure *closure)
+     * {
+     * MyClosure *my_closure = (MyClosure *)closure;
+     *
+     * // free extra data here
+     * }
+     *
+     * MyClosure *my_closure_new (gpointer data)
+     * {
+     * GClosure *closure;
+     * MyClosure *my_closure;
+     *
+     * closure = g_closure_new_simple (sizeof (MyClosure), data);
+     * my_closure = (MyClosure *) closure;
+     *
+     * // initialize extra data here
+     *
+     * g_closure_add_finalize_notifier (closure, notify_data,
+     * my_closure_finalize);
+     * return my_closure;
+     * }
+     * ]|
+     * @param sizeofClosure - the size of the structure to allocate, must be at least
+     * @param data - data to store in the `data` field of the newly allocated #GClosure
+     */
     static newSimple(sizeofClosure: number, data?: number | null): Closure;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Sets a flag on the closure to indicate that its calling
+     * environment has become invalid, and thus causes any future
+     * invocations of g_closure_invoke() on this `closure` to be
+     * ignored.
+     *
+     * Also, invalidation notifiers installed on the closure will
+     * be called at this point. Note that unless you are holding a
+     * reference to the closure yourself, the invalidation notifiers may
+     * unref the closure and cause it to be destroyed, so if you need to
+     * access the closure after calling g_closure_invalidate(), make sure
+     * that you've previously called g_closure_ref().
+     *
+     * Note that g_closure_invalidate() will also be called when the
+     * reference count of a closure drops to zero (unless it has already
+     * been invalidated before).
+     */
     invalidate(): void;
+    /**
+     * Invokes the closure, i.e. executes the callback represented by the @closure.
+     * @param returnValue - a #GValue to store the return
+     * @param nParamValues - the length of the `param_values` array
+     * @param paramValues - an array of
+     * @param invocationHint - a context-dependent invocation hint
+     */
     invoke(nParamValues: number, paramValues: Value[], returnValue?: Ref<Value> | null, invocationHint?: number | null): void;
+    /**
+     * Increments the reference count on a closure to force it staying
+     * alive while the caller holds a pointer to it.
+     */
     ref(): Closure;
+    /**
+     * Takes over the initial ownership of a closure.
+     *
+     * Each closure is initially created in a "floating" state, which means
+     * that the initial reference count is not owned by any caller.
+     *
+     * This function checks to see if the object is still floating, and if so,
+     * unsets the floating state and decreases the reference count. If the
+     * closure is not floating, g_closure_sink() does nothing.
+     *
+     * The reason for the existence of the floating state is to prevent
+     * cumbersome code sequences like:
+     *
+     * |[<!-- language="C" -->
+     * closure = g_cclosure_new (cb_func, cb_data);
+     * g_source_set_closure (source, closure);
+     * g_closure_unref (closure); // GObject doesn't really need this
+     * ]|
+     *
+     * Because g_source_set_closure() (and similar functions) take ownership of the
+     * initial reference count, if it is unowned, we instead can write:
+     *
+     * |[<!-- language="C" -->
+     * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
+     * ]|
+     *
+     * Generally, this function is used together with g_closure_ref(). An example
+     * of storing a closure for later notification looks like:
+     *
+     * |[<!-- language="C" -->
+     * static GClosure *notify_closure = NULL;
+     * void
+     * foo_notify_set_closure (GClosure *closure)
+     * {
+     * if (notify_closure)
+     * g_closure_unref (notify_closure);
+     * notify_closure = closure;
+     * if (notify_closure)
+     * {
+     * g_closure_ref (notify_closure);
+     * g_closure_sink (notify_closure);
+     * }
+     * }
+     * ]|
+     *
+     * Because g_closure_sink() may decrement the reference count of a closure
+     * (if it hasn't been called on `closure` yet) just like g_closure_unref(),
+     * g_closure_ref() should be called prior to this function.
+     */
     sink(): void;
+    /**
+     * Decrements the reference count of a closure after it was previously
+     * incremented by the same caller.
+     *
+     * If no other callers are using the closure, then the closure will be
+     * destroyed and freed.
+     */
     unref(): void;
+    /**
+     * Indicates whether the closure is currently being invoked with
+     * g_closure_invoke()
+     */
     get inMarshal(): number;
     set inMarshal(value: number);
+    /**
+     * Indicates whether the closure has been invalidated by
+     * g_closure_invalidate()
+     */
     get isInvalid(): number;
     set isInvalid(value: number);
 }

package/dist/generated/gobject/closure.js

@@ -1,11 +1,98 @@
 import { call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `GClosure` represents a callback supplied by the programmer.
+ *
+ * It will generally comprise a function of some kind and a marshaller
+ * used to call it. It is the responsibility of the marshaller to
+ * convert the arguments for the invocation from #GValues into
+ * a suitable form, perform the callback on the converted arguments,
+ * and transform the return value back into a #GValue.
+ *
+ * In the case of C programs, a closure usually just holds a pointer
+ * to a function and maybe a data argument, and the marshaller
+ * converts between #GValue and native C types. The GObject
+ * library provides the #GCClosure type for this purpose. Bindings for
+ * other languages need marshallers which convert between #GValues
+ * and suitable representations in the runtime of the language in
+ * order to use functions written in that language as callbacks. Use
+ * g_closure_set_marshal() to set the marshaller on such a custom
+ * closure implementation.
+ *
+ * Within GObject, closures play an important role in the
+ * implementation of signals. When a signal is registered, the
+ * `c_marshaller` argument to g_signal_new() specifies the default C
+ * marshaller for any closure which is connected to this
+ * signal. GObject provides a number of C marshallers for this
+ * purpose, see the g_cclosure_marshal_*() functions. Additional C
+ * marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
+ * utility.  Closures can be explicitly connected to signals with
+ * g_signal_connect_closure(), but it usually more convenient to let
+ * GObject create a closure automatically by using one of the
+ * g_signal_connect_*() functions which take a callback function/user
+ * data pair.
+ *
+ * Using closures has a number of important advantages over a simple
+ * callback function/data pointer combination:
+ *
+ * - Closures allow the callee to get the types of the callback parameters,
+ * which means that language bindings don't have to write individual glue
+ * for each callback type.
+ *
+ * - The reference counting of #GClosure makes it easy to handle reentrancy
+ * right; if a callback is removed while it is being invoked, the closure
+ * and its parameters won't be freed until the invocation finishes.
+ *
+ * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
+ * automatically removed when the objects they point to go away.
+ */
 export class Closure {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Allocates a struct of the given size and initializes the initial
+     * part as a #GClosure.
+     *
+     * This function is mainly useful when implementing new types of closures:
+     *
+     * |[<!-- language="C" -->
+     * typedef struct _MyClosure MyClosure;
+     * struct _MyClosure
+     * {
+     * GClosure closure;
+     * // extra data goes here
+     * };
+     *
+     * static void
+     * my_closure_finalize (gpointer  notify_data,
+     * GClosure *closure)
+     * {
+     * MyClosure *my_closure = (MyClosure *)closure;
+     *
+     * // free extra data here
+     * }
+     *
+     * MyClosure *my_closure_new (gpointer data)
+     * {
+     * GClosure *closure;
+     * MyClosure *my_closure;
+     *
+     * closure = g_closure_new_simple (sizeof (MyClosure), data);
+     * my_closure = (MyClosure *) closure;
+     *
+     * // initialize extra data here
+     *
+     * g_closure_add_finalize_notifier (closure, notify_data,
+     * my_closure_finalize);
+     * return my_closure;
+     * }
+     * ]|
+     * @param sizeofClosure - the size of the structure to allocate, must be at least
+     * @param data - data to store in the `data` field of the newly allocated #GClosure
+     */
     static newSimple(sizeofClosure, data) {
         const ptr = call("libgobject-2.0.so.0", "g_closure_new_simple", [
             {
@@ -33,6 +120,23 @@ export class Closure {
             },
         ], { type: "boxed", borrowed: true, innerType: "GClosure" });
     }
+    /**
+     * Sets a flag on the closure to indicate that its calling
+     * environment has become invalid, and thus causes any future
+     * invocations of g_closure_invoke() on this `closure` to be
+     * ignored.
+     *
+     * Also, invalidation notifiers installed on the closure will
+     * be called at this point. Note that unless you are holding a
+     * reference to the closure yourself, the invalidation notifiers may
+     * unref the closure and cause it to be destroyed, so if you need to
+     * access the closure after calling g_closure_invalidate(), make sure
+     * that you've previously called g_closure_ref().
+     *
+     * Note that g_closure_invalidate() will also be called when the
+     * reference count of a closure drops to zero (unless it has already
+     * been invalidated before).
+     */
     invalidate() {
         call("libgobject-2.0.so.0", "g_closure_invalidate", [
             {
@@ -41,6 +145,13 @@ export class Closure {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Invokes the closure, i.e. executes the callback represented by the @closure.
+     * @param returnValue - a #GValue to store the return
+     * @param nParamValues - the length of the `param_values` array
+     * @param paramValues - an array of
+     * @param invocationHint - a context-dependent invocation hint
+     */
     invoke(nParamValues, paramValues, returnValue, invocationHint) {
         call("libgobject-2.0.so.0", "g_closure_invoke", [
             {
@@ -81,6 +192,10 @@ export class Closure {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Increments the reference count on a closure to force it staying
+     * alive while the caller holds a pointer to it.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0", "g_closure_ref", [
             {
@@ -95,6 +210,55 @@ export class Closure {
         });
         return getObject(ptr, Closure);
     }
+    /**
+     * Takes over the initial ownership of a closure.
+     *
+     * Each closure is initially created in a "floating" state, which means
+     * that the initial reference count is not owned by any caller.
+     *
+     * This function checks to see if the object is still floating, and if so,
+     * unsets the floating state and decreases the reference count. If the
+     * closure is not floating, g_closure_sink() does nothing.
+     *
+     * The reason for the existence of the floating state is to prevent
+     * cumbersome code sequences like:
+     *
+     * |[<!-- language="C" -->
+     * closure = g_cclosure_new (cb_func, cb_data);
+     * g_source_set_closure (source, closure);
+     * g_closure_unref (closure); // GObject doesn't really need this
+     * ]|
+     *
+     * Because g_source_set_closure() (and similar functions) take ownership of the
+     * initial reference count, if it is unowned, we instead can write:
+     *
+     * |[<!-- language="C" -->
+     * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
+     * ]|
+     *
+     * Generally, this function is used together with g_closure_ref(). An example
+     * of storing a closure for later notification looks like:
+     *
+     * |[<!-- language="C" -->
+     * static GClosure *notify_closure = NULL;
+     * void
+     * foo_notify_set_closure (GClosure *closure)
+     * {
+     * if (notify_closure)
+     * g_closure_unref (notify_closure);
+     * notify_closure = closure;
+     * if (notify_closure)
+     * {
+     * g_closure_ref (notify_closure);
+     * g_closure_sink (notify_closure);
+     * }
+     * }
+     * ]|
+     *
+     * Because g_closure_sink() may decrement the reference count of a closure
+     * (if it hasn't been called on `closure` yet) just like g_closure_unref(),
+     * g_closure_ref() should be called prior to this function.
+     */
     sink() {
         call("libgobject-2.0.so.0", "g_closure_sink", [
             {
@@ -103,6 +267,13 @@ export class Closure {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Decrements the reference count of a closure after it was previously
+     * incremented by the same caller.
+     *
+     * If no other callers are using the closure, then the closure will be
+     * destroyed and freed.
+     */
     unref() {
         call("libgobject-2.0.so.0", "g_closure_unref", [
             {
@@ -111,12 +282,20 @@ export class Closure {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Indicates whether the closure is currently being invoked with
+     * g_closure_invoke()
+     */
     get inMarshal() {
         return read(this.ptr, { type: "int", size: 32, unsigned: true }, 0);
     }
     set inMarshal(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: true }, 0, value);
     }
+    /**
+     * Indicates whether the closure has been invalidated by
+     * g_closure_invalidate()
+     */
     get isInvalid() {
         return read(this.ptr, { type: "int", size: 32, unsigned: true }, 4);
     }

package/dist/generated/gobject/enums.d.ts

@@ -1,12 +1,53 @@
+/**
+ * Flags to be passed to g_object_bind_property() or
+ * g_object_bind_property_full().
+ *
+ * This enumeration can be extended at later date.
+ */
 export declare enum BindingFlags {
+    /**
+     * The default binding; if the source property
+     * changes, the target property is updated with its value.
+     */
     DEFAULT = 0,
+    /**
+     * Bidirectional binding; if either the
+     * property of the source or the property of the target changes,
+     * the other is updated.
+     */
     BIDIRECTIONAL = 1,
+    /**
+     * Synchronize the values of the source and
+     * target properties when creating the binding; the direction of
+     * the synchronization is always from the source to the target.
+     */
     SYNC_CREATE = 2,
+    /**
+     * If the two properties being bound are
+     * booleans, setting one to %TRUE will result in the other being
+     * set to %FALSE and vice versa. This flag will only work for
+     * boolean properties, and cannot be used when passing custom
+     * transformation functions to g_object_bind_property_full().
+     */
     INVERT_BOOLEAN = 4
 }
+/**
+ * The connection flags are used to specify the behaviour of a signal's
+ * connection.
+ */
 export declare enum ConnectFlags {
+    /** Default behaviour (no special flags). Since: 2.74 */
     DEFAULT = 0,
+    /**
+     * If set, the handler should be called after the
+     * default handler of the signal. Normally, the handler is called before
+     * the default handler.
+     */
     AFTER = 1,
+    /**
+     * If set, the instance and data should be swapped when
+     * calling the handler; see g_signal_connect_swapped() for an example.
+     */
     SWAPPED = 2
 }
 export declare enum IOCondition {
@@ -17,57 +58,199 @@ export declare enum IOCondition {
     HUP = 16,
     NVAL = 32
 }
+/**
+ * Through the #GParamFlags flag values, certain aspects of parameters
+ * can be configured.
+ *
+ * See also: %G_PARAM_STATIC_STRINGS
+ */
 export declare enum ParamFlags {
+    /** the parameter is readable */
     READABLE = 1,
+    /** the parameter is writable */
     WRITABLE = 2,
+    /** alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE */
     READWRITE = 3,
+    /**
+     * the parameter will be set upon object construction.
+     * See [vfunc@Object.constructed] for more details
+     */
     CONSTRUCT = 4,
+    /**
+     * the parameter can only be set upon object construction.
+     * See [vfunc@Object.constructed] for more details
+     */
     CONSTRUCT_ONLY = 8,
+    /**
+     * upon parameter conversion (see g_param_value_convert())
+     * strict validation is not required
+     */
     LAX_VALIDATION = 16,
+    /**
+     * the string used as name when constructing the
+     * parameter is guaranteed to remain valid and
+     * unmodified for the lifetime of the parameter.
+     * Since 2.8
+     */
     STATIC_NAME = 32,
+    /** internal */
     PRIVATE = 32,
+    /**
+     * the string used as nick when constructing the
+     * parameter is guaranteed to remain valid and
+     * unmmodified for the lifetime of the parameter.
+     * Since 2.8
+     */
     STATIC_NICK = 64,
+    /**
+     * the string used as blurb when constructing the
+     * parameter is guaranteed to remain valid and
+     * unmodified for the lifetime of the parameter.
+     * Since 2.8
+     */
     STATIC_BLURB = 128,
+    /**
+     * calls to g_object_set_property() for this
+     * property will not automatically result in a "notify" signal being
+     * emitted: the implementation must call g_object_notify() themselves
+     * in case the property actually changes.  Since: 2.42.
+     */
     EXPLICIT_NOTIFY = 1073741824,
+    /**
+     * the parameter is deprecated and will be removed
+     * in a future version. A warning will be generated if it is used
+     * while running with G_ENABLE_DIAGNOSTIC=1.
+     * Since 2.26
+     */
     DEPRECATED = 2147483648
 }
+/** The signal flags are used to specify a signal's behaviour. */
 export declare enum SignalFlags {
+    /** Invoke the object method handler in the first emission stage. */
     RUN_FIRST = 1,
+    /** Invoke the object method handler in the third emission stage. */
     RUN_LAST = 2,
+    /** Invoke the object method handler in the last emission stage. */
     RUN_CLEANUP = 4,
+    /**
+     * Signals being emitted for an object while currently being in
+     * emission for this very object will not be emitted recursively,
+     * but instead cause the first emission to be restarted.
+     */
     NO_RECURSE = 8,
+    /**
+     * This signal supports "::detail" appendices to the signal name
+     * upon handler connections and emissions.
+     */
     DETAILED = 16,
+    /**
+     * Action signals are signals that may freely be emitted on alive
+     * objects from user code via g_signal_emit() and friends, without
+     * the need of being embedded into extra code that performs pre or
+     * post emission adjustments on the object. They can also be thought
+     * of as object methods which can be called generically by
+     * third-party code.
+     */
     ACTION = 32,
+    /** No emissions hooks are supported for this signal. */
     NO_HOOKS = 64,
+    /**
+     * Varargs signal emission will always collect the arguments, even if there
+     * are no signal handlers connected.
+     */
     MUST_COLLECT = 128,
+    /**
+     * The signal is deprecated and will be removed in a future version.
+     *
+     * A warning will be generated if it is connected while running with
+     * `G_ENABLE_DIAGNOSTIC=1`.
+     */
     DEPRECATED = 256,
+    /**
+     * The signal accumulator was invoked for the first time.
+     *
+     * This flag is only used in [callback@GObject.SignalAccumulator][accumulator functions]
+     * for the `run_type` field of the [struct@GObject.SignalInvocationHint], to
+     * mark the first call to the accumulator function for a signal emission.
+     */
     ACCUMULATOR_FIRST_RUN = 131072
 }
+/**
+ * The match types specify what g_signal_handlers_block_matched(),
+ * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
+ * match signals by.
+ */
 export declare enum SignalMatchType {
+    /** The signal id must be equal. */
     ID = 1,
+    /** The signal detail must be equal. */
     DETAIL = 2,
+    /** The closure must be the same. */
     CLOSURE = 4,
+    /** The C closure callback must be the same. */
     FUNC = 8,
+    /** The closure data must be the same. */
     DATA = 16,
+    /** Only unblocked signals may be matched. */
     UNBLOCKED = 32
 }
+/**
+ * These flags used to be passed to g_type_init_with_debug_flags() which
+ * is now deprecated.
+ *
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
+ * environment variable.
+ */
 export declare enum TypeDebugFlags {
+    /** Print no messages */
     NONE = 0,
+    /** Print messages about object bookkeeping */
     OBJECTS = 1,
+    /** Print messages about signal emissions */
     SIGNALS = 2,
+    /** Keep a count of instances of each type */
     INSTANCE_COUNT = 4,
+    /** Mask covering all debug flags */
     MASK = 7
 }
+/** Bit masks used to check or determine characteristics of a type. */
 export declare enum TypeFlags {
+    /** No special flags. Since: 2.74 */
     NONE = 0,
+    /**
+     * Indicates an abstract type. No instances can be
+     * created for an abstract type
+     */
     ABSTRACT = 16,
+    /**
+     * Indicates an abstract value type, i.e. a type
+     * that introduces a value table, but can't be used for
+     * g_value_init()
+     */
     VALUE_ABSTRACT = 32,
+    /**
+     * Indicates a final type. A final type is a non-derivable
+     * leaf node in a deep derivable type hierarchy tree. Since: 2.70
+     */
     FINAL = 64,
+    /**
+     * The type is deprecated and may be removed in a
+     * future version. A warning will be emitted if it is instantiated while
+     * running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76
+     */
     DEPRECATED = 128
 }
+/**
+ * Bit masks used to check or determine specific characteristics of a
+ * fundamental type.
+ */
 export declare enum TypeFundamentalFlags {
+    /** Indicates a classed type */
     CLASSED = 1,
+    /** Indicates an instantiatable type (implies classed) */
     INSTANTIATABLE = 2,
+    /** Indicates a flat derivable type */
     DERIVABLE = 4,
+    /** Indicates a deep derivable type (implies derivable) */
     DEEP_DERIVABLE = 8
 }