@girs/gobject-2.0 2.76.1-3.2.0 → 2.77.0-3.2.2

package/README.md

@@ -5,7 +5,7 @@
 ![downloads/week](https://img.shields.io/npm/dw/@girs/gobject-2.0)
 
 
-GJS TypeScript type definitions for GObject-2.0, generated from library version 2.76.1 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v3.2.0.
+GJS TypeScript type definitions for GObject-2.0, generated from library version 2.77.0 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v3.2.2.
 
 GObject provides the object system used for Pango and GTK+.
 

package/gobject-2.0.d.cts

@@ -238,7 +238,7 @@ export enum SignalMatchType {
  * 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
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  * @bitfield 
  */
@@ -1329,12 +1329,18 @@ export function signal_handler_is_connected(instance: Object, handler_id: number
 export function signal_handler_unblock(instance: Object, handler_id: number): void
 /**
  * Blocks all handlers on an instance that match a certain selection criteria.
- * The criteria mask is passed as an OR-ed combination of #GSignalMatchType
- * flags, and the criteria values are passed as arguments.
- * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be blocked (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC
  * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
  * If no handlers were found, 0 is returned, the number of blocked handlers
  * otherwise.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to block handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1353,13 +1359,19 @@ export function signal_handlers_block_matched(instance: Object, mask: SignalMatc
 export function signal_handlers_destroy(instance: Object): void
 /**
  * Disconnects all handlers on an instance that match a certain
- * selection criteria. The criteria mask is passed as an OR-ed
- * combination of #GSignalMatchType flags, and the criteria values are
- * passed as arguments.  Passing at least one of the
- * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
+ * selection criteria.
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be disconnected (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC or
  * %G_SIGNAL_MATCH_DATA match flags is required for successful
  * matches.  If no handlers were found, 0 is returned, the number of
  * disconnected handlers otherwise.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to remove handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1371,13 +1383,20 @@ export function signal_handlers_destroy(instance: Object): void
 export function signal_handlers_disconnect_matched(instance: Object, mask: SignalMatchType, signal_id: number, detail: GLib.Quark, func: any | null, data: any | null): number
 /**
  * Unblocks all handlers on an instance that match a certain selection
- * criteria. The criteria mask is passed as an OR-ed combination of
- * #GSignalMatchType flags, and the criteria values are passed as arguments.
- * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+ * criteria.
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be unblocked (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC
  * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
  * If no handlers were found, 0 is returned, the number of unblocked handlers
  * otherwise. The match criteria should not apply to any handlers that are
  * not currently blocked.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to unblock handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1737,8 +1756,8 @@ export function type_fundamental_next(): GType
 /**
  * Returns the number of instances allocated of the particular type;
  * this is only available if GLib is built with debugging support and
- * the instance_count debug flag is set (by setting the GOBJECT_DEBUG
- * variable to include instance-count).
+ * the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG`
+ * variable to include `instance-count`).
  * @param type a #GType
  * @returns the number of instances allocated of the given type;   if instance counts are not available, returns 0.
  */
@@ -1781,7 +1800,7 @@ export function type_init(): void
  * flags.  Since GLib 2.36, the type system is initialised automatically
  * and this function does nothing.
  * 
- * If you need to enable debugging features, use the GOBJECT_DEBUG
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  * @param debug_flags bitwise combination of #GTypeDebugFlags values for     debugging purposes
  */
@@ -2388,6 +2407,226 @@ export interface TypePluginUnuse {
 export interface TypePluginUse {
     (plugin: TypePlugin): void
 }
+/**
+ * This function is responsible for converting the values collected from
+ * a variadic argument list into contents suitable for storage in a #GValue.
+ * 
+ * This function should setup `value` similar to #GTypeValueInitFunc; e.g.
+ * for a string value that does not allow `NULL` pointers, it needs to either
+ * emit an error, or do an implicit conversion by storing an empty string.
+ * 
+ * The `value` passed in to this function has a zero-filled data array, so
+ * just like for #GTypeValueInitFunc it is guaranteed to not contain any old
+ * contents that might need freeing.
+ * 
+ * The `n_collect_values` argument is the string length of the `collect_format`
+ * field of #GTypeValueTable, and `collect_values` is an array of #GTypeCValue
+ * with length of `n_collect_values,` containing the collected values according
+ * to `collect_format`.
+ * 
+ * The `collect_flags` argument provided as a hint by the caller. It may
+ * contain the flag %G_VALUE_NOCOPY_CONTENTS indicating that the collected
+ * value contents may be considered ‘static’ for the duration of the `value`
+ * lifetime. Thus an extra copy of the contents stored in `collect_values` is
+ * not required for assignment to `value`.
+ * 
+ * For our above string example, we continue with:
+ * 
+ * 
+ * ```c
+ * if (!collect_values[0].v_pointer)
+ *   value->data[0].v_pointer = g_strdup ("");
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ *   {
+ *     value->data[0].v_pointer = collect_values[0].v_pointer;
+ *     // keep a flag for the value_free() implementation to not free this string
+ *     value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
+ *   }
+ * else
+ *   value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
+ * return NULL;
+ * ```
+ * 
+ * 
+ * It should be noted, that it is generally a bad idea to follow the
+ * %G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
+ * reentrancy requirements and reference count assertions performed
+ * by the signal emission code, reference counts should always be
+ * incremented for reference counted contents stored in the `value->data`
+ * array. To deviate from our string example for a moment, and taking
+ * a look at an exemplary implementation for `GTypeValueTable.collect_value()`
+ * of `GObject`:
+ * 
+ * 
+ * ```c
+ * GObject *object = G_OBJECT (collect_values[0].v_pointer);
+ * g_return_val_if_fail (object != NULL,
+ *    g_strdup_printf ("Object %p passed as invalid NULL pointer", object));
+ * // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
+ * value->data[0].v_pointer = g_object_ref (object);
+ * return NULL;
+ * ```
+ * 
+ * 
+ * The reference count for valid objects is always incremented, regardless
+ * of `collect_flags`. For invalid objects, the example returns a newly
+ * allocated string without altering `value`.
+ * 
+ * Upon success, `collect_value()` needs to return `NULL`. If, however,
+ * an error condition occurred, `collect_value()` should return a newly
+ * allocated string containing an error diagnostic.
+ * 
+ * The calling code makes no assumptions about the `value` contents being
+ * valid upon error returns, `value` is simply thrown away without further
+ * freeing. As such, it is a good idea to not allocate `GValue` contents
+ * prior to returning an error; however, `collect_values()` is not obliged
+ * to return a correctly setup `value` for error returns, simply because
+ * any non-`NULL` return is considered a fatal programming error, and
+ * further program behaviour is undefined.
+ * @callback 
+ * @param value the value to initialize
+ * @param collect_values the collected values
+ * @param collect_flags optional flags
+ * @returns `NULL` on success, otherwise a   newly allocated error string on failure
+ */
+export interface TypeValueCollectFunc {
+    (value: any, collect_values: TypeCValue[], collect_flags: number): string | null
+}
+/**
+ * Copies the content of a #GValue into another.
+ * 
+ * The `dest_value` is a #GValue with zero-filled data section and `src_value`
+ * is a properly initialized #GValue of same type, or derived type.
+ * 
+ * The purpose of this function is to copy the contents of `src_value`
+ * into `dest_value` in a way, that even after `src_value` has been freed, the
+ * contents of `dest_value` remain valid. String type example:
+ * 
+ * 
+ * ```c
+ * dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
+ * ```
+ * 
+ * @callback 
+ * @param src_value the value to copy
+ */
+export interface TypeValueCopyFunc {
+    (src_value: any): void
+}
+/**
+ * Frees any old contents that might be left in the `value->data` array of
+ * the given value.
+ * 
+ * No resources may remain allocated through the #GValue contents after this
+ * function returns. E.g. for our above string type:
+ * 
+ * 
+ * ```c
+ * // only free strings without a specific flag for static storage
+ * if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
+ *   g_free (value->data[0].v_pointer);
+ * ```
+ * 
+ * @callback 
+ * @param value the value to free
+ */
+export interface TypeValueFreeFunc {
+    (value: any): void
+}
+/**
+ * Initializes the value contents by setting the fields of the `value->data`
+ * array.
+ * 
+ * The data array of the #GValue passed into this function was zero-filled
+ * with `memset()`, so no care has to be taken to free any old contents.
+ * For example, in the case of a string value that may never be %NULL, the
+ * implementation might look like:
+ * 
+ * 
+ * ```c
+ * value->data[0].v_pointer = g_strdup ("");
+ * ```
+ * 
+ * @callback 
+ * @param value the value to initialize
+ */
+export interface TypeValueInitFunc {
+    (value: any): void
+}
+/**
+ * This function is responsible for storing the `value`
+ * contents into arguments passed through a variadic argument list which
+ * got collected into `collect_values` according to `lcopy_format`.
+ * 
+ * The `n_collect_values` argument equals the string length of
+ * `lcopy_format`, and `collect_flags` may contain %G_VALUE_NOCOPY_CONTENTS.
+ * 
+ * In contrast to #GTypeValueCollectFunc, this function is obliged to always
+ * properly support %G_VALUE_NOCOPY_CONTENTS.
+ * 
+ * Similar to #GTypeValueCollectFunc the function may prematurely abort by
+ * returning a newly allocated string describing an error condition. To
+ * complete the string example:
+ * 
+ * 
+ * ```c
+ * gchar **string_p = collect_values[0].v_pointer;
+ * g_return_val_if_fail (string_p != NULL,
+ *   g_strdup ("string location passed as NULL"));
+ * 
+ * if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ *   *string_p = value->data[0].v_pointer;
+ * else
+ *   *string_p = g_strdup (value->data[0].v_pointer);
+ * ```
+ * 
+ * 
+ * And an illustrative version of this function for reference-counted
+ * types:
+ * 
+ * 
+ * ```c
+ * GObject **object_p = collect_values[0].v_pointer;
+ * g_return_val_if_fail (object_p != NULL,
+ *   g_strdup ("object location passed as NULL"));
+ * 
+ * if (value->data[0].v_pointer == NULL)
+ *   *object_p = NULL;
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
+ *   *object_p = value->data[0].v_pointer;
+ * else
+ *   *object_p = g_object_ref (value->data[0].v_pointer);
+ * 
+ * return NULL;
+ * ```
+ * 
+ * @callback 
+ * @param value the value to lcopy
+ * @param collect_values the collected   locations for storage
+ * @param collect_flags optional flags
+ * @returns `NULL` on success, otherwise   a newly allocated error string on failure
+ */
+export interface TypeValueLCopyFunc {
+    (value: any, collect_values: TypeCValue[], collect_flags: number): string | null
+}
+/**
+ * If the value contents fit into a pointer, such as objects or strings,
+ * return this pointer, so the caller can peek at the current contents.
+ * 
+ * To extend on our above string example:
+ * 
+ * 
+ * ```c
+ * return value->data[0].v_pointer;
+ * ```
+ * 
+ * @callback 
+ * @param value the value to peek
+ * @returns a pointer to the value contents
+ */
+export interface TypeValuePeekPointerFunc {
+    (value: any): any | null
+}
 /**
  * The type of value transformation functions which can be registered with
  * g_value_register_transform_func().
@@ -6647,35 +6886,62 @@ export interface TypeValueTable {
 
     // Own fields of GObject-2.0.GObject.TypeValueTable
 
-    value_init: (value: any) => void
-    value_free: (value: any) => void
-    value_copy: (src_value: any, dest_value: any) => void
-    value_peek_pointer: (value: any) => any
+    /**
+     * Function to initialize a GValue
+     * @field 
+     */
+    value_init: TypeValueInitFunc
+    /**
+     * Function to free a GValue
+     * @field 
+     */
+    value_free: TypeValueFreeFunc
+    /**
+     * Function to copy a GValue
+     * @field 
+     */
+    value_copy: TypeValueCopyFunc
+    /**
+     * Function to peek the contents of a GValue if they fit
+     *   into a pointer
+     * @field 
+     */
+    value_peek_pointer: TypeValuePeekPointerFunc
     /**
      * A string format describing how to collect the contents of
-     *  this value bit-by-bit. Each character in the format represents
-     *  an argument to be collected, and the characters themselves indicate
-     *  the type of the argument. Currently supported arguments are:
-     *  - 'i' - Integers. passed as collect_values[].v_int.
-     *  - 'l' - Longs. passed as collect_values[].v_long.
-     *  - 'd' - Doubles. passed as collect_values[].v_double.
-     *  - 'p' - Pointers. passed as collect_values[].v_pointer.
-     *  It should be noted that for variable argument list construction,
-     *  ANSI C promotes every type smaller than an integer to an int, and
-     *  floats to doubles. So for collection of short int or char, 'i'
-     *  needs to be used, and for collection of floats 'd'.
+     *   this value bit-by-bit. Each character in the format represents
+     *   an argument to be collected, and the characters themselves indicate
+     *   the type of the argument. Currently supported arguments are:
+     *    - `'i'`: Integers, passed as `collect_values[].v_int`
+     *    - `'l'`: Longs, passed as `collect_values[].v_long`
+     *    - `'d'`: Doubles, passed as `collect_values[].v_double`
+     *    - `'p'`: Pointers, passed as `collect_values[].v_pointer`
+     *   It should be noted that for variable argument list construction,
+     *   ANSI C promotes every type smaller than an integer to an int, and
+     *   floats to doubles. So for collection of short int or char, `'i'`
+     *   needs to be used, and for collection of floats `'d'`.
      * @field 
      */
     collect_format: string | null
-    collect_value: (value: any, n_collect_values: number, collect_values: TypeCValue, collect_flags: number) => string | null
+    /**
+     * Function to initialize a GValue from the values
+     *   collected from variadic arguments
+     * @field 
+     */
+    collect_value: TypeValueCollectFunc
     /**
      * Format description of the arguments to collect for `lcopy_value,`
-     *  analogous to `collect_format`. Usually, `lcopy_format` string consists
-     *  only of 'p's to provide lcopy_value() with pointers to storage locations.
+     *   analogous to `collect_format`. Usually, `lcopy_format` string consists
+     *   only of `'p'`s to provide lcopy_value() with pointers to storage locations.
      * @field 
      */
     lcopy_format: string | null
-    lcopy_value: (value: any, n_collect_values: number, collect_values: TypeCValue, collect_flags: number) => string | null
+    /**
+     * Function to store the contents of a value into the
+     *   locations collected from variadic arguments
+     * @field 
+     */
+    lcopy_value: TypeValueLCopyFunc
 }
 
 /**

package/gobject-2.0.d.ts

@@ -240,7 +240,7 @@ enum SignalMatchType {
  * 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
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  * @bitfield 
  */
@@ -1331,12 +1331,18 @@ function signal_handler_is_connected(instance: Object, handler_id: number): bool
 function signal_handler_unblock(instance: Object, handler_id: number): void
 /**
  * Blocks all handlers on an instance that match a certain selection criteria.
- * The criteria mask is passed as an OR-ed combination of #GSignalMatchType
- * flags, and the criteria values are passed as arguments.
- * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be blocked (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC
  * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
  * If no handlers were found, 0 is returned, the number of blocked handlers
  * otherwise.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to block handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1355,13 +1361,19 @@ function signal_handlers_block_matched(instance: Object, mask: SignalMatchType,
 function signal_handlers_destroy(instance: Object): void
 /**
  * Disconnects all handlers on an instance that match a certain
- * selection criteria. The criteria mask is passed as an OR-ed
- * combination of #GSignalMatchType flags, and the criteria values are
- * passed as arguments.  Passing at least one of the
- * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
+ * selection criteria.
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be disconnected (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC or
  * %G_SIGNAL_MATCH_DATA match flags is required for successful
  * matches.  If no handlers were found, 0 is returned, the number of
  * disconnected handlers otherwise.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to remove handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1373,13 +1385,20 @@ function signal_handlers_destroy(instance: Object): void
 function signal_handlers_disconnect_matched(instance: Object, mask: SignalMatchType, signal_id: number, detail: GLib.Quark, func: any | null, data: any | null): number
 /**
  * Unblocks all handlers on an instance that match a certain selection
- * criteria. The criteria mask is passed as an OR-ed combination of
- * #GSignalMatchType flags, and the criteria values are passed as arguments.
- * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+ * criteria.
+ * 
+ * The criteria mask is passed as a combination of #GSignalMatchType flags, and
+ * the criteria values are passed as arguments. A handler must match on all
+ * flags set in `mask` to be unblocked (i.e. the match is conjunctive).
+ * 
+ * Passing at least one of the %G_SIGNAL_MATCH_ID, %G_SIGNAL_MATCH_CLOSURE,
+ * %G_SIGNAL_MATCH_FUNC
  * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
  * If no handlers were found, 0 is returned, the number of unblocked handlers
  * otherwise. The match criteria should not apply to any handlers that are
  * not currently blocked.
+ * 
+ * Support for %G_SIGNAL_MATCH_ID was added in GLib 2.78.
  * @param instance The instance to unblock handlers from.
  * @param mask Mask indicating which of `signal_id,` `detail,` `closure,` `func`  and/or `data` the handlers have to match.
  * @param signal_id Signal the handlers have to be connected to.
@@ -1739,8 +1758,8 @@ function type_fundamental_next(): GType
 /**
  * Returns the number of instances allocated of the particular type;
  * this is only available if GLib is built with debugging support and
- * the instance_count debug flag is set (by setting the GOBJECT_DEBUG
- * variable to include instance-count).
+ * the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG`
+ * variable to include `instance-count`).
  * @param type a #GType
  * @returns the number of instances allocated of the given type;   if instance counts are not available, returns 0.
  */
@@ -1783,7 +1802,7 @@ function type_init(): void
  * flags.  Since GLib 2.36, the type system is initialised automatically
  * and this function does nothing.
  * 
- * If you need to enable debugging features, use the GOBJECT_DEBUG
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  * @param debug_flags bitwise combination of #GTypeDebugFlags values for     debugging purposes
  */
@@ -2390,6 +2409,226 @@ interface TypePluginUnuse {
 interface TypePluginUse {
     (plugin: TypePlugin): void
 }
+/**
+ * This function is responsible for converting the values collected from
+ * a variadic argument list into contents suitable for storage in a #GValue.
+ * 
+ * This function should setup `value` similar to #GTypeValueInitFunc; e.g.
+ * for a string value that does not allow `NULL` pointers, it needs to either
+ * emit an error, or do an implicit conversion by storing an empty string.
+ * 
+ * The `value` passed in to this function has a zero-filled data array, so
+ * just like for #GTypeValueInitFunc it is guaranteed to not contain any old
+ * contents that might need freeing.
+ * 
+ * The `n_collect_values` argument is the string length of the `collect_format`
+ * field of #GTypeValueTable, and `collect_values` is an array of #GTypeCValue
+ * with length of `n_collect_values,` containing the collected values according
+ * to `collect_format`.
+ * 
+ * The `collect_flags` argument provided as a hint by the caller. It may
+ * contain the flag %G_VALUE_NOCOPY_CONTENTS indicating that the collected
+ * value contents may be considered ‘static’ for the duration of the `value`
+ * lifetime. Thus an extra copy of the contents stored in `collect_values` is
+ * not required for assignment to `value`.
+ * 
+ * For our above string example, we continue with:
+ * 
+ * 
+ * ```c
+ * if (!collect_values[0].v_pointer)
+ *   value->data[0].v_pointer = g_strdup ("");
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ *   {
+ *     value->data[0].v_pointer = collect_values[0].v_pointer;
+ *     // keep a flag for the value_free() implementation to not free this string
+ *     value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
+ *   }
+ * else
+ *   value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
+ * return NULL;
+ * ```
+ * 
+ * 
+ * It should be noted, that it is generally a bad idea to follow the
+ * %G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
+ * reentrancy requirements and reference count assertions performed
+ * by the signal emission code, reference counts should always be
+ * incremented for reference counted contents stored in the `value->data`
+ * array. To deviate from our string example for a moment, and taking
+ * a look at an exemplary implementation for `GTypeValueTable.collect_value()`
+ * of `GObject`:
+ * 
+ * 
+ * ```c
+ * GObject *object = G_OBJECT (collect_values[0].v_pointer);
+ * g_return_val_if_fail (object != NULL,
+ *    g_strdup_printf ("Object %p passed as invalid NULL pointer", object));
+ * // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
+ * value->data[0].v_pointer = g_object_ref (object);
+ * return NULL;
+ * ```
+ * 
+ * 
+ * The reference count for valid objects is always incremented, regardless
+ * of `collect_flags`. For invalid objects, the example returns a newly
+ * allocated string without altering `value`.
+ * 
+ * Upon success, `collect_value()` needs to return `NULL`. If, however,
+ * an error condition occurred, `collect_value()` should return a newly
+ * allocated string containing an error diagnostic.
+ * 
+ * The calling code makes no assumptions about the `value` contents being
+ * valid upon error returns, `value` is simply thrown away without further
+ * freeing. As such, it is a good idea to not allocate `GValue` contents
+ * prior to returning an error; however, `collect_values()` is not obliged
+ * to return a correctly setup `value` for error returns, simply because
+ * any non-`NULL` return is considered a fatal programming error, and
+ * further program behaviour is undefined.
+ * @callback 
+ * @param value the value to initialize
+ * @param collect_values the collected values
+ * @param collect_flags optional flags
+ * @returns `NULL` on success, otherwise a   newly allocated error string on failure
+ */
+interface TypeValueCollectFunc {
+    (value: any, collect_values: TypeCValue[], collect_flags: number): string | null
+}
+/**
+ * Copies the content of a #GValue into another.
+ * 
+ * The `dest_value` is a #GValue with zero-filled data section and `src_value`
+ * is a properly initialized #GValue of same type, or derived type.
+ * 
+ * The purpose of this function is to copy the contents of `src_value`
+ * into `dest_value` in a way, that even after `src_value` has been freed, the
+ * contents of `dest_value` remain valid. String type example:
+ * 
+ * 
+ * ```c
+ * dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
+ * ```
+ * 
+ * @callback 
+ * @param src_value the value to copy
+ */
+interface TypeValueCopyFunc {
+    (src_value: any): void
+}
+/**
+ * Frees any old contents that might be left in the `value->data` array of
+ * the given value.
+ * 
+ * No resources may remain allocated through the #GValue contents after this
+ * function returns. E.g. for our above string type:
+ * 
+ * 
+ * ```c
+ * // only free strings without a specific flag for static storage
+ * if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
+ *   g_free (value->data[0].v_pointer);
+ * ```
+ * 
+ * @callback 
+ * @param value the value to free
+ */
+interface TypeValueFreeFunc {
+    (value: any): void
+}
+/**
+ * Initializes the value contents by setting the fields of the `value->data`
+ * array.
+ * 
+ * The data array of the #GValue passed into this function was zero-filled
+ * with `memset()`, so no care has to be taken to free any old contents.
+ * For example, in the case of a string value that may never be %NULL, the
+ * implementation might look like:
+ * 
+ * 
+ * ```c
+ * value->data[0].v_pointer = g_strdup ("");
+ * ```
+ * 
+ * @callback 
+ * @param value the value to initialize
+ */
+interface TypeValueInitFunc {
+    (value: any): void
+}
+/**
+ * This function is responsible for storing the `value`
+ * contents into arguments passed through a variadic argument list which
+ * got collected into `collect_values` according to `lcopy_format`.
+ * 
+ * The `n_collect_values` argument equals the string length of
+ * `lcopy_format`, and `collect_flags` may contain %G_VALUE_NOCOPY_CONTENTS.
+ * 
+ * In contrast to #GTypeValueCollectFunc, this function is obliged to always
+ * properly support %G_VALUE_NOCOPY_CONTENTS.
+ * 
+ * Similar to #GTypeValueCollectFunc the function may prematurely abort by
+ * returning a newly allocated string describing an error condition. To
+ * complete the string example:
+ * 
+ * 
+ * ```c
+ * gchar **string_p = collect_values[0].v_pointer;
+ * g_return_val_if_fail (string_p != NULL,
+ *   g_strdup ("string location passed as NULL"));
+ * 
+ * if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ *   *string_p = value->data[0].v_pointer;
+ * else
+ *   *string_p = g_strdup (value->data[0].v_pointer);
+ * ```
+ * 
+ * 
+ * And an illustrative version of this function for reference-counted
+ * types:
+ * 
+ * 
+ * ```c
+ * GObject **object_p = collect_values[0].v_pointer;
+ * g_return_val_if_fail (object_p != NULL,
+ *   g_strdup ("object location passed as NULL"));
+ * 
+ * if (value->data[0].v_pointer == NULL)
+ *   *object_p = NULL;
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
+ *   *object_p = value->data[0].v_pointer;
+ * else
+ *   *object_p = g_object_ref (value->data[0].v_pointer);
+ * 
+ * return NULL;
+ * ```
+ * 
+ * @callback 
+ * @param value the value to lcopy
+ * @param collect_values the collected   locations for storage
+ * @param collect_flags optional flags
+ * @returns `NULL` on success, otherwise   a newly allocated error string on failure
+ */
+interface TypeValueLCopyFunc {
+    (value: any, collect_values: TypeCValue[], collect_flags: number): string | null
+}
+/**
+ * If the value contents fit into a pointer, such as objects or strings,
+ * return this pointer, so the caller can peek at the current contents.
+ * 
+ * To extend on our above string example:
+ * 
+ * 
+ * ```c
+ * return value->data[0].v_pointer;
+ * ```
+ * 
+ * @callback 
+ * @param value the value to peek
+ * @returns a pointer to the value contents
+ */
+interface TypeValuePeekPointerFunc {
+    (value: any): any | null
+}
 /**
  * The type of value transformation functions which can be registered with
  * g_value_register_transform_func().
@@ -6649,35 +6888,62 @@ interface TypeValueTable {
 
     // Own fields of GObject-2.0.GObject.TypeValueTable
 
-    value_init: (value: any) => void
-    value_free: (value: any) => void
-    value_copy: (src_value: any, dest_value: any) => void
-    value_peek_pointer: (value: any) => any
+    /**
+     * Function to initialize a GValue
+     * @field 
+     */
+    value_init: TypeValueInitFunc
+    /**
+     * Function to free a GValue
+     * @field 
+     */
+    value_free: TypeValueFreeFunc
+    /**
+     * Function to copy a GValue
+     * @field 
+     */
+    value_copy: TypeValueCopyFunc
+    /**
+     * Function to peek the contents of a GValue if they fit
+     *   into a pointer
+     * @field 
+     */
+    value_peek_pointer: TypeValuePeekPointerFunc
     /**
      * A string format describing how to collect the contents of
-     *  this value bit-by-bit. Each character in the format represents
-     *  an argument to be collected, and the characters themselves indicate
-     *  the type of the argument. Currently supported arguments are:
-     *  - 'i' - Integers. passed as collect_values[].v_int.
-     *  - 'l' - Longs. passed as collect_values[].v_long.
-     *  - 'd' - Doubles. passed as collect_values[].v_double.
-     *  - 'p' - Pointers. passed as collect_values[].v_pointer.
-     *  It should be noted that for variable argument list construction,
-     *  ANSI C promotes every type smaller than an integer to an int, and
-     *  floats to doubles. So for collection of short int or char, 'i'
-     *  needs to be used, and for collection of floats 'd'.
+     *   this value bit-by-bit. Each character in the format represents
+     *   an argument to be collected, and the characters themselves indicate
+     *   the type of the argument. Currently supported arguments are:
+     *    - `'i'`: Integers, passed as `collect_values[].v_int`
+     *    - `'l'`: Longs, passed as `collect_values[].v_long`
+     *    - `'d'`: Doubles, passed as `collect_values[].v_double`
+     *    - `'p'`: Pointers, passed as `collect_values[].v_pointer`
+     *   It should be noted that for variable argument list construction,
+     *   ANSI C promotes every type smaller than an integer to an int, and
+     *   floats to doubles. So for collection of short int or char, `'i'`
+     *   needs to be used, and for collection of floats `'d'`.
      * @field 
      */
     collect_format: string | null
-    collect_value: (value: any, n_collect_values: number, collect_values: TypeCValue, collect_flags: number) => string | null
+    /**
+     * Function to initialize a GValue from the values
+     *   collected from variadic arguments
+     * @field 
+     */
+    collect_value: TypeValueCollectFunc
     /**
      * Format description of the arguments to collect for `lcopy_value,`
-     *  analogous to `collect_format`. Usually, `lcopy_format` string consists
-     *  only of 'p's to provide lcopy_value() with pointers to storage locations.
+     *   analogous to `collect_format`. Usually, `lcopy_format` string consists
+     *   only of `'p'`s to provide lcopy_value() with pointers to storage locations.
      * @field 
      */
     lcopy_format: string | null
-    lcopy_value: (value: any, n_collect_values: number, collect_values: TypeCValue, collect_flags: number) => string | null
+    /**
+     * Function to store the contents of a value into the
+     *   locations collected from variadic arguments
+     * @field 
+     */
+    lcopy_value: TypeValueLCopyFunc
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@girs/gobject-2.0",
-  "version": "2.76.1-3.2.0",
-  "description": "GJS TypeScript type definitions for GObject-2.0, generated from library version 2.76.1",
+  "version": "2.77.0-3.2.2",
+  "description": "GJS TypeScript type definitions for GObject-2.0, generated from library version 2.77.0",
   "type": "module",
   "module": "gobject-2.0.js",
   "main": "gobject-2.0.js",
@@ -25,8 +25,8 @@
     "test:cjs": "NODE_OPTIONS=--max_old_space_size=9216 tsc --noEmit gobject-2.0.d.cts"
   },
   "dependencies": {
-    "@girs/gjs": "^3.2.0",
-    "@girs/glib-2.0": "^2.76.1-3.2.0"
+    "@girs/gjs": "^3.2.2",
+    "@girs/glib-2.0": "^2.77.0-3.2.2"
   },
   "devDependencies": {
     "typescript": "*"

package/typedoc.json

@@ -1,5 +1,5 @@
 {
-    "entryPoints": ["./gobject-2.0.d.ts","./gobject-2.0-ambient.d.ts","./gobject-2.0-import.d.ts"],
+    "entryPoints": ["./gobject-2.0.d.ts"],
     "readme": "./README.md",
     "name": "GObject-2.0",
     "tsconfig": "./tsconfig.json"