@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -1,9 +1,28 @@
+/** Errors returned by g_module_open_full(). */
 export declare enum ModuleError {
+    /** there was an error loading or opening a module file */
     FAILED = 0,
+    /** a module returned an error from its `g_module_check_init()` function */
     CHECK_FAILED = 1
 }
+/**
+ * Flags passed to g_module_open().
+ * Note that these flags are not supported on all platforms.
+ */
 export declare enum ModuleFlags {
+    /**
+     * specifies that symbols are only resolved when
+     * needed. The default action is to bind all symbols when the module
+     * is loaded.
+     */
     LAZY = 1,
+    /**
+     * specifies that symbols in the module should
+     * not be added to the global name space. The default action on most
+     * platforms is to place symbols in the module in the global name space,
+     * which may cause conflicts with existing symbols.
+     */
     LOCAL = 2,
+    /** mask for all flags. */
     MASK = 3
 }

package/dist/generated/gmodule/enums.js

@@ -1,11 +1,30 @@
+/** Errors returned by g_module_open_full(). */
 export var ModuleError;
 (function (ModuleError) {
+    /** there was an error loading or opening a module file */
     ModuleError[ModuleError["FAILED"] = 0] = "FAILED";
+    /** a module returned an error from its `g_module_check_init()` function */
     ModuleError[ModuleError["CHECK_FAILED"] = 1] = "CHECK_FAILED";
 })(ModuleError || (ModuleError = {}));
+/**
+ * Flags passed to g_module_open().
+ * Note that these flags are not supported on all platforms.
+ */
 export var ModuleFlags;
 (function (ModuleFlags) {
+    /**
+     * specifies that symbols are only resolved when
+     * needed. The default action is to bind all symbols when the module
+     * is loaded.
+     */
     ModuleFlags[ModuleFlags["LAZY"] = 1] = "LAZY";
+    /**
+     * specifies that symbols in the module should
+     * not be added to the global name space. The default action on most
+     * platforms is to place symbols in the module in the global name space,
+     * which may cause conflicts with existing symbols.
+     */
     ModuleFlags[ModuleFlags["LOCAL"] = 2] = "LOCAL";
+    /** mask for all flags. */
     ModuleFlags[ModuleFlags["MASK"] = 3] = "MASK";
 })(ModuleFlags || (ModuleFlags = {}));

package/dist/generated/gmodule/functions.d.ts

@@ -1,4 +1,27 @@
+/**
+ * A portable way to build the filename of a module. The platform-specific
+ * prefix and suffix are added to the filename, if needed, and the result
+ * is added to the directory, using the correct separator character.
+ *
+ * The directory should specify the directory where the module can be found.
+ * It can be %NULL or an empty string to indicate that the module is in a
+ * standard platform-specific directory, though this is not recommended
+ * since the wrong module may be found.
+ *
+ * For example, calling g_module_build_path() on a Linux system with a
+ * `directory` of `/lib` and a `module_name` of "mylibrary" will return
+ * `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+ * directory it will return `\Windows\mylibrary.dll`.
+ * @param directory - the directory where the module is. This can be
+ * @param moduleName - the name of the module
+ */
 export declare const moduleBuildPath: (moduleName: string, directory?: string | null) => string;
+/**
+ * Gets a string describing the last module error.
+ */
 export declare const moduleError: () => string;
 export declare const moduleErrorQuark: () => number;
+/**
+ * Checks if modules are supported on the current platform.
+ */
 export declare const moduleSupported: () => boolean;

package/dist/generated/gmodule/functions.js

@@ -1,4 +1,21 @@
 import { call } from "@gtkx/native";
+/**
+ * A portable way to build the filename of a module. The platform-specific
+ * prefix and suffix are added to the filename, if needed, and the result
+ * is added to the directory, using the correct separator character.
+ *
+ * The directory should specify the directory where the module can be found.
+ * It can be %NULL or an empty string to indicate that the module is in a
+ * standard platform-specific directory, though this is not recommended
+ * since the wrong module may be found.
+ *
+ * For example, calling g_module_build_path() on a Linux system with a
+ * `directory` of `/lib` and a `module_name` of "mylibrary" will return
+ * `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+ * directory it will return `\Windows\mylibrary.dll`.
+ * @param directory - the directory where the module is. This can be
+ * @param moduleName - the name of the module
+ */
 export const moduleBuildPath = (moduleName, directory) => {
     return call("libgmodule-2.0.so.0", "g_module_build_path", [
         {
@@ -12,6 +29,9 @@ export const moduleBuildPath = (moduleName, directory) => {
         },
     ], { type: "string" });
 };
+/**
+ * Gets a string describing the last module error.
+ */
 export const moduleError = () => {
     return call("libgmodule-2.0.so.0", "g_module_error", [], {
         type: "string",
@@ -25,6 +45,9 @@ export const moduleErrorQuark = () => {
         unsigned: true,
     });
 };
+/**
+ * Checks if modules are supported on the current platform.
+ */
 export const moduleSupported = () => {
     return call("libgmodule-2.0.so.0", "g_module_supported", [], {
         type: "boolean",

package/dist/generated/gobject/binding-group.d.ts

@@ -3,12 +3,71 @@ import { Closure } from "./closure.js";
 import { ParamSpec } from "./param-spec.js";
 import { GObject } from "./object.js";
 export declare class BindingGroup extends GObject {
+    /**
+     * Creates a new #GBindingGroup.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Creates a binding between `source_property` on the source object
+     * and `target_property` on @target. Whenever the `source_property` is changed the `target_property` is updated using the same value.
+     * The binding flag %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * See g_object_bind_property() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     */
     bind(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags): void;
+    /**
+     * Creates a binding between `source_property` on the source object and
+     * `target_property` on @target, allowing you to set the transformation
+     * functions to be used by the binding. The binding flag
+     * %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * See g_object_bind_property_full() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     * @param transformTo - the transformation function
+     * @param transformFrom - the transformation function
+     * @param userData - custom data to be passed to the transformation
+     * @param userDataDestroy - function to be called when disposing the binding,
+     */
     bindFull(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags, userDataDestroy: () => void, transformTo?: (...args: unknown[]) => unknown | null, transformFrom?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Creates a binding between `source_property` on the source object and
+     * `target_property` on @target, allowing you to set the transformation
+     * functions to be used by the binding. The binding flag
+     * %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * This function is the language bindings friendly version of
+     * g_binding_group_bind_property_full(), using #GClosures
+     * instead of function pointers.
+     *
+     * See g_object_bind_property_with_closures() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     * @param transformTo - a #GClosure wrapping the
+     * @param transformFrom - a #GClosure wrapping the
+     */
     bindWithClosures(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags, transformTo?: Closure | null, transformFrom?: Closure | null): void;
+    /**
+     * Gets the source object used for binding properties.
+     */
     dupSource(): GObject | null;
+    /**
+     * Sets `source` as the source object used for creating property
+     * bindings. If there is already a source object all bindings from it
+     * will be removed.
+     *
+     * Note that all properties that have been bound must exist on @source.
+     * @param source - the source #GObject,
+     */
     setSource(source?: GObject | null): void;
     connect(signal: "notify", handler: (self: BindingGroup, pspec: ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gobject/binding-group.js

@@ -2,6 +2,15 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { ParamSpec } from "./param-spec.js";
 import { GObject } from "./object.js";
+/**
+ * `GBindingGroup` can be used to bind multiple properties
+ * from an object collectively.
+ *
+ * Use the various methods to bind properties from a single source
+ * object to multiple destination objects. Properties can be bound
+ * bidirectionally and are connected when the source object is set
+ * with [method@GObject.BindingGroup.set_source].
+ */
 const SIGNAL_META = {
     notify: {
         params: [
@@ -11,6 +20,9 @@ const SIGNAL_META = {
     },
 };
 export class BindingGroup extends GObject {
+    /**
+     * Creates a new #GBindingGroup.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -20,6 +32,17 @@ export class BindingGroup extends GObject {
             borrowed: false,
         });
     }
+    /**
+     * Creates a binding between `source_property` on the source object
+     * and `target_property` on @target. Whenever the `source_property` is changed the `target_property` is updated using the same value.
+     * The binding flag %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * See g_object_bind_property() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     */
     bind(sourceProperty, target, targetProperty, flags) {
         call("libgobject-2.0.so.0", "g_binding_group_bind", [
             {
@@ -44,6 +67,22 @@ export class BindingGroup extends GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a binding between `source_property` on the source object and
+     * `target_property` on @target, allowing you to set the transformation
+     * functions to be used by the binding. The binding flag
+     * %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * See g_object_bind_property_full() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     * @param transformTo - the transformation function
+     * @param transformFrom - the transformation function
+     * @param userData - custom data to be passed to the transformation
+     * @param userDataDestroy - function to be called when disposing the binding,
+     */
     bindFull(sourceProperty, target, targetProperty, flags, userDataDestroy, transformTo, transformFrom, userData) {
         call("libgobject-2.0.so.0", "g_binding_group_bind_full", [
             {
@@ -87,6 +126,24 @@ export class BindingGroup extends GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a binding between `source_property` on the source object and
+     * `target_property` on @target, allowing you to set the transformation
+     * functions to be used by the binding. The binding flag
+     * %G_BINDING_SYNC_CREATE is automatically specified.
+     *
+     * This function is the language bindings friendly version of
+     * g_binding_group_bind_property_full(), using #GClosures
+     * instead of function pointers.
+     *
+     * See g_object_bind_property_with_closures() for more information.
+     * @param sourceProperty - the property on the source to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - the flags used to create the #GBinding
+     * @param transformTo - a #GClosure wrapping the
+     * @param transformFrom - a #GClosure wrapping the
+     */
     bindWithClosures(sourceProperty, target, targetProperty, flags, transformTo, transformFrom) {
         call("libgobject-2.0.so.0", "g_binding_group_bind_with_closures", [
             {
@@ -131,6 +188,9 @@ export class BindingGroup extends GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the source object used for binding properties.
+     */
     dupSource() {
         const ptr = call("libgobject-2.0.so.0", "g_binding_group_dup_source", [
             {
@@ -142,6 +202,14 @@ export class BindingGroup extends GObject {
             return null;
         return getObject(ptr, GObject);
     }
+    /**
+     * Sets `source` as the source object used for creating property
+     * bindings. If there is already a source object all bindings from it
+     * will be removed.
+     *
+     * Note that all properties that have been bound must exist on @source.
+     * @param source - the source #GObject,
+     */
     setSource(source) {
         call("libgobject-2.0.so.0", "g_binding_group_set_source", [
             {

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

@@ -4,13 +4,73 @@ import { GObject } from "./object.js";
 export declare class Binding extends GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Retrieves the #GObject instance used as the source of the binding.
+     *
+     * A #GBinding can outlive the source #GObject as the binding does not hold a
+     * strong reference to the source. If the source is destroyed before the
+     * binding then this function will return %NULL.
+     */
     dupSource(): GObject | null;
+    /**
+     * Retrieves the #GObject instance used as the target of the binding.
+     *
+     * A #GBinding can outlive the target #GObject as the binding does not hold a
+     * strong reference to the target. If the target is destroyed before the
+     * binding then this function will return %NULL.
+     */
     dupTarget(): GObject | null;
+    /**
+     * Retrieves the flags passed when constructing the #GBinding.
+     */
     getFlags(): BindingFlags;
+    /**
+     * Retrieves the #GObject instance used as the source of the binding.
+     *
+     * A #GBinding can outlive the source #GObject as the binding does not hold a
+     * strong reference to the source. If the source is destroyed before the
+     * binding then this function will return %NULL.
+     *
+     * Use g_binding_dup_source() if the source or binding are used from different
+     * threads as otherwise the pointer returned from this function might become
+     * invalid if the source is finalized from another thread in the meantime.
+     */
     getSource(): GObject | null;
+    /**
+     * Retrieves the name of the property of #GBinding:source used as the source
+     * of the binding.
+     */
     getSourceProperty(): string;
+    /**
+     * Retrieves the #GObject instance used as the target of the binding.
+     *
+     * A #GBinding can outlive the target #GObject as the binding does not hold a
+     * strong reference to the target. If the target is destroyed before the
+     * binding then this function will return %NULL.
+     *
+     * Use g_binding_dup_target() if the target or binding are used from different
+     * threads as otherwise the pointer returned from this function might become
+     * invalid if the target is finalized from another thread in the meantime.
+     */
     getTarget(): GObject | null;
+    /**
+     * Retrieves the name of the property of #GBinding:target used as the target
+     * of the binding.
+     */
     getTargetProperty(): string;
+    /**
+     * Explicitly releases the binding between the source and the target
+     * property expressed by @binding.
+     *
+     * This function will release the reference that is being held on
+     * the `binding` instance if the binding is still bound; if you want to hold on
+     * to the #GBinding instance after calling g_binding_unbind(), you will need
+     * to hold a reference to it.
+     *
+     * Note however that this function does not take ownership of @binding, it
+     * only unrefs the reference that was initially created by
+     * g_object_bind_property() and is owned by the binding.
+     */
     unbind(): void;
     connect(signal: "notify", handler: (self: Binding, pspec: ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gobject/binding.js

@@ -2,6 +2,83 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { ParamSpec } from "./param-spec.js";
 import { GObject } from "./object.js";
+/**
+ * `GObject` instance (or source) and another property on another `GObject`
+ * instance (or target).
+ *
+ * Whenever the source property changes, the same value is applied to the
+ * target property; for instance, the following binding:
+ *
+ * ```c
+ * g_object_bind_property (object1, "property-a",
+ * object2, "property-b",
+ * G_BINDING_DEFAULT);
+ * ```
+ *
+ * will cause the property named "property-b" of `object2` to be updated
+ * every time [method@GObject.set] or the specific accessor changes the value of
+ * the property "property-a" of @object1.
+ *
+ * It is possible to create a bidirectional binding between two properties
+ * of two `GObject` instances, so that if either property changes, the
+ * other is updated as well, for instance:
+ *
+ * ```c
+ * g_object_bind_property (object1, "property-a",
+ * object2, "property-b",
+ * G_BINDING_BIDIRECTIONAL);
+ * ```
+ *
+ * will keep the two properties in sync.
+ *
+ * It is also possible to set a custom transformation function (in both
+ * directions, in case of a bidirectional binding) to apply a custom
+ * transformation from the source value to the target value before
+ * applying it; for instance, the following binding:
+ *
+ * ```c
+ * g_object_bind_property_full (adjustment1, "value",
+ * adjustment2, "value",
+ * G_BINDING_BIDIRECTIONAL,
+ * celsius_to_fahrenheit,
+ * fahrenheit_to_celsius,
+ * NULL, NULL);
+ * ```
+ *
+ * will keep the "value" property of the two adjustments in sync; the
+ * `celsius_to_fahrenheit` function will be called whenever the "value"
+ * property of `adjustment1` changes and will transform the current value
+ * of the property before applying it to the "value" property of @adjustment2.
+ *
+ * Vice versa, the `fahrenheit_to_celsius` function will be called whenever
+ * the "value" property of `adjustment2` changes, and will transform the
+ * current value of the property before applying it to the "value" property
+ * of @adjustment1.
+ *
+ * Note that #GBinding does not resolve cycles by itself; a cycle like
+ *
+ * ```
+ * object1:propertyA -> object2:propertyB
+ * object2:propertyB -> object3:propertyC
+ * object3:propertyC -> object1:propertyA
+ * ```
+ *
+ * might lead to an infinite loop. The loop, in this particular case,
+ * can be avoided if the objects emit the `GObject::notify` signal only
+ * if the value has effectively been changed. A binding is implemented
+ * using the `GObject::notify` signal, so it is susceptible to all the
+ * various ways of blocking a signal emission, like [func@GObject.signal_stop_emission]
+ * or [func@GObject.signal_handler_block].
+ *
+ * A binding will be severed, and the resources it allocates freed, whenever
+ * either one of the `GObject` instances it refers to are finalized, or when
+ * the #GBinding instance loses its last reference.
+ *
+ * Bindings for languages with garbage collection can use
+ * [method@GObject.Binding.unbind] to explicitly release a binding between the source
+ * and target properties, instead of relying on the last reference on the
+ * binding, source, and target instances to drop.
+ */
 const SIGNAL_META = {
     notify: {
         params: [
@@ -25,6 +102,13 @@ export class Binding extends GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Retrieves the #GObject instance used as the source of the binding.
+     *
+     * A #GBinding can outlive the source #GObject as the binding does not hold a
+     * strong reference to the source. If the source is destroyed before the
+     * binding then this function will return %NULL.
+     */
     dupSource() {
         const ptr = call("libgobject-2.0.so.0", "g_binding_dup_source", [
             {
@@ -36,6 +120,13 @@ export class Binding extends GObject {
             return null;
         return getObject(ptr, GObject);
     }
+    /**
+     * Retrieves the #GObject instance used as the target of the binding.
+     *
+     * A #GBinding can outlive the target #GObject as the binding does not hold a
+     * strong reference to the target. If the target is destroyed before the
+     * binding then this function will return %NULL.
+     */
     dupTarget() {
         const ptr = call("libgobject-2.0.so.0", "g_binding_dup_target", [
             {
@@ -47,6 +138,9 @@ export class Binding extends GObject {
             return null;
         return getObject(ptr, GObject);
     }
+    /**
+     * Retrieves the flags passed when constructing the #GBinding.
+     */
     getFlags() {
         return call("libgobject-2.0.so.0", "g_binding_get_flags", [
             {
@@ -55,6 +149,17 @@ export class Binding extends GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the #GObject instance used as the source of the binding.
+     *
+     * A #GBinding can outlive the source #GObject as the binding does not hold a
+     * strong reference to the source. If the source is destroyed before the
+     * binding then this function will return %NULL.
+     *
+     * Use g_binding_dup_source() if the source or binding are used from different
+     * threads as otherwise the pointer returned from this function might become
+     * invalid if the source is finalized from another thread in the meantime.
+     */
     getSource() {
         const ptr = call("libgobject-2.0.so.0", "g_binding_get_source", [
             {
@@ -66,6 +171,10 @@ export class Binding extends GObject {
             return null;
         return getObject(ptr, GObject);
     }
+    /**
+     * Retrieves the name of the property of #GBinding:source used as the source
+     * of the binding.
+     */
     getSourceProperty() {
         return call("libgobject-2.0.so.0", "g_binding_get_source_property", [
             {
@@ -74,6 +183,17 @@ export class Binding extends GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Retrieves the #GObject instance used as the target of the binding.
+     *
+     * A #GBinding can outlive the target #GObject as the binding does not hold a
+     * strong reference to the target. If the target is destroyed before the
+     * binding then this function will return %NULL.
+     *
+     * Use g_binding_dup_target() if the target or binding are used from different
+     * threads as otherwise the pointer returned from this function might become
+     * invalid if the target is finalized from another thread in the meantime.
+     */
     getTarget() {
         const ptr = call("libgobject-2.0.so.0", "g_binding_get_target", [
             {
@@ -85,6 +205,10 @@ export class Binding extends GObject {
             return null;
         return getObject(ptr, GObject);
     }
+    /**
+     * Retrieves the name of the property of #GBinding:target used as the target
+     * of the binding.
+     */
     getTargetProperty() {
         return call("libgobject-2.0.so.0", "g_binding_get_target_property", [
             {
@@ -93,6 +217,19 @@ export class Binding extends GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Explicitly releases the binding between the source and the target
+     * property expressed by @binding.
+     *
+     * This function will release the reference that is being held on
+     * the `binding` instance if the binding is still bound; if you want to hold on
+     * to the #GBinding instance after calling g_binding_unbind(), you will need
+     * to hold a reference to it.
+     *
+     * Note however that this function does not take ownership of @binding, it
+     * only unrefs the reference that was initially created by
+     * g_object_bind_property() and is owned by the binding.
+     */
     unbind() {
         call("libgobject-2.0.so.0", "g_binding_unbind", [
             {