@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -1,74 +1,427 @@
 import { GObject } from "./object.js";
 import { ParamSpec } from "./param-spec.js";
 import * as GLib from "../glib/index.js";
+/**
+ * An opaque structure used to hold different types of values.
+ *
+ * Before it can be used, a `GValue` has to be initialized to a specific type by
+ * calling [method@GObject.Value.init] on it.
+ *
+ * Many types which are stored within a `GValue` need to allocate data on the
+ * heap, so [method@GObject.Value.unset] must always be called on a `GValue` to
+ * free any such data once you’re finished with the `GValue`, even if the
+ * `GValue` itself is stored on the stack.
+ *
+ * The data within the structure has protected scope: it is accessible only
+ * to functions within a [struct@GObject.TypeValueTable] structure, or
+ * implementations of the `g_value_*()` API. That is, code which implements new
+ * fundamental types.
+ *
+ * `GValue` users cannot make any assumptions about how data is stored
+ * within the 2 element `data` union, and the `g_type` member should
+ * only be accessed through the [func@GObject.VALUE_TYPE] macro and related
+ * macros.
+ */
 export declare class Value {
     ptr: unknown;
     constructor();
     protected createPtr(_init: Record<string, unknown>): unknown;
+    /**
+     * Checks whether a [method@GObject.Value.copy] is able to copy values of type
+     * `src_type` into values of type @dest_type.
+     * @param srcType - source type to be copied
+     * @param destType - destination type for copying
+     */
     static typeCompatible(srcType: number, destType: number): boolean;
+    /**
+     * Checks whether [method@GObject.Value.transform] is able to transform values
+     * of type `src_type` into values of type @dest_type.
+     *
+     * Note that for the types to be transformable, they must be compatible or a
+     * transformation function must be registered using
+     * [func@GObject.Value.register_transform_func].
+     * @param srcType - source type
+     * @param destType - target type
+     */
     static typeTransformable(srcType: number, destType: number): boolean;
+    /**
+     * Copies the value of `src_value` into @dest_value.
+     * @param destValue - an initialized [struct@GObject.Value] structure of the same type
+     */
     copy(destValue: Value): void;
+    /**
+     * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
+     * its reference count. If the contents of the #GValue are %NULL, then
+     * %NULL will be returned.
+     */
     dupObject(): GObject | null;
+    /**
+     * Get a copy the contents of a %G_TYPE_STRING #GValue.
+     */
     dupString(): string | null;
+    /**
+     * Get the contents of a variant #GValue, increasing its refcount. The returned
+     * #GVariant is never floating.
+     */
     dupVariant(): GLib.Variant | null;
+    /**
+     * Determines if `value` will fit inside the size of a pointer value.
+     *
+     * This is an internal function introduced mainly for C marshallers.
+     */
     fitsPointer(): boolean;
+    /**
+     * Get the contents of a %G_TYPE_BOOLEAN #GValue.
+     */
     getBoolean(): boolean;
+    /**
+     * Get the contents of a %G_TYPE_BOXED derived #GValue.
+     */
     getBoxed(): number | null;
+    /**
+     * Do not use this function; it is broken on platforms where the %char
+     * type is unsigned, such as ARM and PowerPC.  See g_value_get_schar().
+     *
+     * Get the contents of a %G_TYPE_CHAR #GValue.
+     */
     getChar(): number;
+    /**
+     * Get the contents of a %G_TYPE_DOUBLE #GValue.
+     */
     getDouble(): number;
+    /**
+     * Get the contents of a %G_TYPE_ENUM #GValue.
+     */
     getEnum(): number;
+    /**
+     * Get the contents of a %G_TYPE_FLAGS #GValue.
+     */
     getFlags(): number;
+    /**
+     * Get the contents of a %G_TYPE_FLOAT #GValue.
+     */
     getFloat(): number;
+    /**
+     * Get the contents of a %G_TYPE_GTYPE #GValue.
+     */
     getGtype(): number;
+    /**
+     * Get the contents of a %G_TYPE_INT #GValue.
+     */
     getInt(): number;
+    /**
+     * Get the contents of a %G_TYPE_INT64 #GValue.
+     */
     getInt64(): number;
+    /**
+     * Get the contents of a %G_TYPE_LONG #GValue.
+     */
     getLong(): number;
+    /**
+     * Get the contents of a %G_TYPE_OBJECT derived #GValue.
+     */
     getObject(): GObject | null;
+    /**
+     * Get the contents of a %G_TYPE_PARAM #GValue.
+     */
     getParam(): ParamSpec;
+    /**
+     * Get the contents of a pointer #GValue.
+     */
     getPointer(): number | null;
+    /**
+     * Get the contents of a %G_TYPE_CHAR #GValue.
+     */
     getSchar(): number;
+    /**
+     * Get the contents of a %G_TYPE_STRING #GValue.
+     */
     getString(): string | null;
+    /**
+     * Get the contents of a %G_TYPE_UCHAR #GValue.
+     */
     getUchar(): number;
+    /**
+     * Get the contents of a %G_TYPE_UINT #GValue.
+     */
     getUint(): number;
+    /**
+     * Get the contents of a %G_TYPE_UINT64 #GValue.
+     */
     getUint64(): number;
+    /**
+     * Get the contents of a %G_TYPE_ULONG #GValue.
+     */
     getUlong(): number;
+    /**
+     * Get the contents of a variant #GValue.
+     */
     getVariant(): GLib.Variant | null;
+    /**
+     * Initializes `value` to store values of the given @type, and sets its value
+     * to the default for @type.
+     *
+     * This must be called before any other methods on a [struct@GObject.Value], so
+     * the value knows what type it’s meant to store.
+     *
+     * ```c
+     * GValue value = G_VALUE_INIT;
+     *
+     * g_value_init (&value, SOME_G_TYPE);
+     * …
+     * g_value_unset (&value);
+     * ```
+     * @param gType - type the [struct@GObject.Value] should hold values of
+     */
     init(gType: number): Value;
+    /**
+     * Initializes and sets `value` from an instantiatable type.
+     *
+     * This calls the [callback@GObject.TypeValueCollectFunc] function for the type
+     * the [struct@GObject.Value] contains.
+     *
+     * Note: The `value` will be initialised with the exact type of
+     * @instance.  If you wish to set the @value’s type to a different
+     * [type@GObject.Type] (such as a parent class type), you need to manually call
+     * [method@GObject.Value.init] and [method@GObject.Value.set_instance].
+     * @param instance - the instance
+     */
     initFromInstance(instance: number): void;
+    /**
+     * Returns the value contents as a pointer.
+     *
+     * This function asserts that [method@GObject.Value.fits_pointer] returned true
+     * for the passed in value.
+     *
+     * This is an internal function introduced mainly for C marshallers.
+     */
     peekPointer(): number | null;
+    /**
+     * Clears the current value in `value` and resets it to the default value
+     * (as if the value had just been initialized using
+     * [method@GObject.Value.init]).
+     */
     reset(): Value;
+    /**
+     * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean.
+     * @param vBoolean - boolean value to be set
+     */
     setBoolean(vBoolean: boolean): void;
+    /**
+     * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+     * @param vBoxed - caller-owned boxed object to be duplicated for the #GValue
+     */
     setBoxed(vBoxed?: number | null): void;
+    /**
+     * This is an internal function introduced mainly for C marshallers.
+     * @param vBoxed - duplicated unowned boxed value to be set
+     */
     setBoxedTakeOwnership(vBoxed?: number | null): void;
+    /**
+     * Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
+     * @param vChar - character value to be set
+     */
     setChar(vChar: number): void;
+    /**
+     * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double.
+     * @param vDouble - double value to be set
+     */
     setDouble(vDouble: number): void;
+    /**
+     * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
+     * @param vEnum - enum value to be set
+     */
     setEnum(vEnum: number): void;
+    /**
+     * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
+     * @param vFlags - flags value to be set
+     */
     setFlags(vFlags: number): void;
+    /**
+     * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float.
+     * @param vFloat - float value to be set
+     */
     setFloat(vFloat: number): void;
+    /**
+     * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype.
+     * @param vGtype - #GType to be set
+     */
     setGtype(vGtype: number): void;
+    /**
+     * Sets `value` from an instantiatable type.
+     *
+     * This calls the [callback@GObject.TypeValueCollectFunc] function for the type
+     * the [struct@GObject.Value] contains.
+     * @param instance - the instance
+     */
     setInstance(instance?: number | null): void;
+    /**
+     * Set the contents of a %G_TYPE_INT #GValue to @v_int.
+     * @param vInt - integer value to be set
+     */
     setInt(vInt: number): void;
+    /**
+     * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64.
+     * @param vInt64 - 64bit integer value to be set
+     */
     setInt64(vInt64: number): void;
+    /**
+     * Set the contents of a %G_TYPE_STRING #GValue to @v_string.  The string is
+     * assumed to be static and interned (canonical, for example from
+     * g_intern_string()), and is thus not duplicated when setting the #GValue.
+     * @param vString - static string to be set
+     */
     setInternedString(vString?: string | null): void;
+    /**
+     * Set the contents of a %G_TYPE_LONG #GValue to @v_long.
+     * @param vLong - long integer value to be set
+     */
     setLong(vLong: number): void;
+    /**
+     * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
+     *
+     * g_value_set_object() increases the reference count of `v_object` (the #GValue holds a reference to @v_object).  If you do not wish
+     * to increase the reference count of the object (i.e. you wish to
+     * pass your current reference to the #GValue because you no longer
+     * need it), use g_value_take_object() instead.
+     *
+     * It is important that your #GValue holds a reference to `v_object` (either its
+     * own, or one it has taken) to ensure that the object won't be destroyed while
+     * the #GValue still exists).
+     * @param vObject - object value to be set
+     */
     setObject(vObject?: GObject | null): void;
+    /**
+     * Set the contents of a %G_TYPE_PARAM #GValue to @param.
+     * @param param - the #GParamSpec to be set
+     */
     setParam(param?: ParamSpec | null): void;
+    /**
+     * Set the contents of a pointer #GValue to @v_pointer.
+     * @param vPointer - pointer value to be set
+     */
     setPointer(vPointer?: number | null): void;
+    /**
+     * Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
+     * @param vChar - signed 8 bit integer to be set
+     */
     setSchar(vChar: number): void;
+    /**
+     * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+     *
+     * The boxed value is assumed to be static, and is thus not duplicated
+     * when setting the #GValue.
+     * @param vBoxed - static boxed value to be set
+     */
     setStaticBoxed(vBoxed?: number | null): void;
+    /**
+     * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
+     * The string is assumed to be static, and is thus not duplicated
+     * when setting the #GValue.
+     *
+     * If the the string is a canonical string, using g_value_set_interned_string()
+     * is more appropriate.
+     * @param vString - static string to be set
+     */
     setStaticString(vString?: string | null): void;
+    /**
+     * Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string.
+     * @param vString - caller-owned string to be duplicated for the #GValue
+     */
     setString(vString?: string | null): void;
+    /**
+     * This is an internal function introduced mainly for C marshallers.
+     * @param vString - duplicated unowned string to be set
+     */
     setStringTakeOwnership(vString?: string | null): void;
+    /**
+     * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar.
+     * @param vUchar - unsigned character value to be set
+     */
     setUchar(vUchar: number): void;
+    /**
+     * Set the contents of a %G_TYPE_UINT #GValue to @v_uint.
+     * @param vUint - unsigned integer value to be set
+     */
     setUint(vUint: number): void;
+    /**
+     * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64.
+     * @param vUint64 - unsigned 64bit integer value to be set
+     */
     setUint64(vUint64: number): void;
+    /**
+     * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong.
+     * @param vUlong - unsigned long integer value to be set
+     */
     setUlong(vUlong: number): void;
+    /**
+     * Set the contents of a variant #GValue to @variant.
+     * If the variant is floating, it is consumed.
+     * @param variant - a #GVariant, or %NULL
+     */
     setVariant(variant?: GLib.Variant | null): void;
+    /**
+     * Steal ownership on contents of a %G_TYPE_STRING #GValue.
+     * As a result of this operation the value's contents will be reset to %NULL.
+     *
+     * The purpose of this call is to provide a way to avoid an extra copy
+     * when some object have been serialized into string through #GValue API.
+     *
+     * NOTE: for safety and compatibility purposes, if #GValue contains
+     * static string, or an interned one, this function will return a copy
+     * of the string. Otherwise the transfer notation would be ambiguous.
+     */
     stealString(): string | null;
+    /**
+     * Sets the contents of a %G_TYPE_BOXED derived #GValue to `v_boxed` and takes over the ownership of the caller’s reference to @v_boxed;
+     * the caller doesn’t have to unref it any more.
+     * @param vBoxed - duplicated unowned boxed value to be set
+     */
     takeBoxed(vBoxed?: number | null): void;
+    /**
+     * Sets the contents of a %G_TYPE_STRING #GValue to @v_string.
+     * @param vString - string to take ownership of
+     */
     takeString(vString?: string | null): void;
+    /**
+     * Set the contents of a variant #GValue to @variant, and takes over
+     * the ownership of the caller's reference to @variant;
+     * the caller doesn't have to unref it any more (i.e. the reference
+     * count of the variant is not increased).
+     *
+     * If `variant` was floating then its floating reference is converted to
+     * a hard reference.
+     *
+     * If you want the #GValue to hold its own reference to @variant, use
+     * g_value_set_variant() instead.
+     *
+     * This is an internal function introduced mainly for C marshallers.
+     * @param variant - a #GVariant, or %NULL
+     */
     takeVariant(variant?: GLib.Variant | null): void;
+    /**
+     * Tries to cast the contents of `src_value` into a type appropriate
+     * to store in @dest_value.
+     *
+     * If a transformation is not possible, `dest_value` is not modified.
+     *
+     * For example, this could transform a `G_TYPE_INT` value into a `G_TYPE_FLOAT`
+     * value.
+     *
+     * Performing transformations between value types might incur precision loss.
+     * Especially transformations into strings might reveal seemingly arbitrary
+     * results and the format of particular transformations to strings is not
+     * guaranteed over time.
+     * @param destValue - target value
+     */
     transform(destValue: Value): boolean;
+    /**
+     * Clears the current value in `value` (if any) and ‘unsets’ the type.
+     *
+     * This releases all resources associated with this [struct@GObject.Value]. An
+     * unset value is the same as a cleared (zero-filled)
+     * [struct@GObject.Value] structure set to `G_VALUE_INIT`.
+     */
     unset(): void;
     get data(): number[];
 }