@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gobject/initially-unowned.js

@@ -2,6 +2,12 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { ParamSpec } from "./param-spec.js";
 import { GObject } from "./object.js";
+/**
+ * A type for objects that have an initially floating reference.
+ *
+ * All the fields in the `GInitiallyUnowned` structure are private to the
+ * implementation and should never be accessed directly.
+ */
 const SIGNAL_META = {
     notify: {
         params: [

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

@@ -6,34 +6,391 @@ import type { Binding } from "./binding.js";
 import { ParamSpec } from "./param-spec.js";
 export declare class GObject {
     ptr: unknown;
+    /**
+     * Creates a new instance of a #GObject subtype and sets its properties.
+     *
+     * Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+     * which are not explicitly specified are set to their default values.
+     * @param objectType - the type id of the #GObject subtype to instantiate
+     * @param nParameters - the length of the `parameters` array
+     * @param parameters - an array of #GParameter
+     */
     constructor(objectType: number, nParameters: number, parameters: number[]);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
     static compatControl(what: number, data?: number | null): number;
+    /**
+     * Find the #GParamSpec with the given name for an
+     * interface. Generally, the interface vtable passed in as `g_iface` will be the default vtable from g_type_default_interface_ref(), or,
+     * if you know the interface has already been loaded,
+     * g_type_default_interface_peek().
+     * @param gIface - any interface vtable for the
+     * @param propertyName - name of a property to look up.
+     */
     static interfaceFindProperty(gIface: number, propertyName: string): ParamSpec;
+    /**
+     * Add a property to an interface; this is only useful for interfaces
+     * that are added to GObject-derived types. Adding a property to an
+     * interface forces all objects classes with that interface to have a
+     * compatible property. The compatible property could be a newly
+     * created #GParamSpec, but normally
+     * g_object_class_override_property() will be used so that the object
+     * class only needs to provide an implementation and inherits the
+     * property description, default value, bounds, and so forth from the
+     * interface property.
+     *
+     * This function is meant to be called from the interface's default
+     * vtable initialization function (the `class_init` member of
+     * #GTypeInfo.) It must not be called after after `class_init` has
+     * been called for any object types implementing this interface.
+     *
+     * If `pspec` is a floating reference, it will be consumed.
+     * @param gIface - any interface vtable for the
+     * @param pspec - the #GParamSpec for the new property
+     */
     static interfaceInstallProperty(gIface: number, pspec: ParamSpec): void;
+    /**
+     * Lists the properties of an interface.Generally, the interface
+     * vtable passed in as `g_iface` will be the default vtable from
+     * g_type_default_interface_ref(), or, if you know the interface has
+     * already been loaded, g_type_default_interface_peek().
+     * @param gIface - any interface vtable for the
+     * @param nPropertiesP - location to store number of properties returned.
+     */
     static interfaceListProperties(gIface: number, nPropertiesP: Ref<number>): ParamSpec[];
+    /**
+     * Creates a binding between `source_property` on `source` and `target_property` on @target.
+     *
+     * Whenever the `source_property` is changed the `target_property` is
+     * updated using the same value. For instance:
+     *
+     * |[<!-- language="C" -->
+     * g_object_bind_property (action, "active", widget, "sensitive", 0);
+     * ]|
+     *
+     * Will result in the "sensitive" property of the widget #GObject instance to be
+     * updated with the same value of the "active" property of the action #GObject
+     * instance.
+     *
+     * If `flags` contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
+     * if `target_property` on `target` changes then the `source_property` on `source` will be updated as well.
+     *
+     * The binding will automatically be removed when either the `source` or the
+     * `target` instances are finalized. To remove the binding without affecting the
+     * `source` and the `target` you can just call g_object_unref() on the returned
+     * #GBinding instance.
+     *
+     * Removing the binding by calling g_object_unref() on it must only be done if
+     * the binding, `source` and `target` are only used from a single thread and it
+     * is clear that both `source` and `target` outlive the binding. Especially it
+     * is not safe to rely on this if the binding, `source` or `target` can be
+     * finalized from different threads. Keep another reference to the binding and
+     * use g_binding_unbind() instead to be on the safe side.
+     *
+     * A #GObject can have multiple bindings.
+     * @param sourceProperty - the property on `source` to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - flags to pass to #GBinding
+     */
     bindProperty(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags): Binding;
+    /**
+     * Complete version of g_object_bind_property().
+     *
+     * Creates a binding between `source_property` on `source` and `target_property` on @target, allowing you to set the transformation functions to be used by
+     * the binding.
+     *
+     * If `flags` contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
+     * if `target_property` on `target` changes then the `source_property` on `source` will be updated as well. The `transform_from` function is only used in case
+     * of bidirectional bindings, otherwise it will be ignored
+     *
+     * The binding will automatically be removed when either the `source` or the
+     * `target` instances are finalized. This will release the reference that is
+     * being held on the #GBinding instance; if you want to hold on to the
+     * #GBinding instance, you will need to hold a reference to it.
+     *
+     * To remove the binding, call g_binding_unbind().
+     *
+     * A #GObject can have multiple bindings.
+     *
+     * The same `user_data` parameter will be used for both `transform_to` and `transform_from` transformation functions; the `notify` function will
+     * be called once, when the binding is removed. If you need different data
+     * for each transformation function, please use
+     * g_object_bind_property_with_closures() instead.
+     * @param sourceProperty - the property on `source` to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - flags to pass to #GBinding
+     * @param transformTo - the transformation function
+     * @param transformFrom - the transformation function
+     * @param userData - custom data to be passed to the transformation functions,
+     * @param notify - a function to call when disposing the binding, to free
+     */
     bindPropertyFull(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags, transformTo?: (...args: unknown[]) => unknown | null, transformFrom?: (...args: unknown[]) => unknown | null, userData?: number | null, notify?: () => void | null): Binding;
+    /**
+     * Creates a binding between `source_property` on `source` and `target_property` on @target, allowing you to set the transformation functions to be used by
+     * the binding.
+     *
+     * This function is the language bindings friendly version of
+     * g_object_bind_property_full(), using #GClosures instead of
+     * function pointers.
+     * @param sourceProperty - the property on `source` to bind
+     * @param target - the target #GObject
+     * @param targetProperty - the property on `target` to bind
+     * @param flags - flags to pass to #GBinding
+     * @param transformTo - a #GClosure wrapping the transformation function
+     * @param transformFrom - a #GClosure wrapping the transformation function
+     */
     bindPropertyWithClosures(sourceProperty: string, target: GObject, targetProperty: string, flags: BindingFlags, transformTo: Closure, transformFrom: Closure): Binding;
+    /**
+     * This function is intended for #GObject implementations to re-enforce
+     * a [floating][floating-ref] object reference. Doing this is seldom
+     * required: all #GInitiallyUnowneds are created with a floating reference
+     * which usually just needs to be sunken by calling g_object_ref_sink().
+     */
     forceFloating(): void;
+    /**
+     * Increases the freeze count on @object. If the freeze count is
+     * non-zero, the emission of "notify" signals on `object` is
+     * stopped. The signals are queued until the freeze count is decreased
+     * to zero. Duplicate notifications are squashed so that at most one
+     * #GObject::notify signal is emitted for each property modified while the
+     * object is frozen.
+     *
+     * This is necessary for accessors that modify multiple properties to prevent
+     * premature notification while the object is still being modified.
+     */
     freezeNotify(): void;
+    /**
+     * Gets a named field from the objects table of associations (see g_object_set_data()).
+     * @param key - name of the key for that association
+     */
     getData(key: string): number | null;
+    /**
+     * Gets a property of an object.
+     *
+     * The `value` can be:
+     *
+     * - an empty #GValue initialized by %G_VALUE_INIT, which will be
+     * automatically initialized with the expected type of the property
+     * (since GLib 2.60)
+     * - a #GValue initialized with the expected type of the property
+     * - a #GValue initialized with a type to which the expected type
+     * of the property can be transformed
+     *
+     * In general, a copy is made of the property contents and the caller is
+     * responsible for freeing the memory by calling g_value_unset().
+     *
+     * Note that g_object_get_property() is really intended for language
+     * bindings, g_object_get() is much more convenient for C programming.
+     * @param propertyName - the name of the property to get
+     * @param value - return location for the property value
+     */
     getProperty(propertyName: string, value: Value): void;
+    /**
+     * This function gets back user data pointers stored via
+     * g_object_set_qdata().
+     * @param quark - A #GQuark, naming the user data pointer
+     */
     getQdata(quark: number): number | null;
+    /**
+     * Gets `n_properties` properties for an @object.
+     * Obtained properties will be set to @values. All properties must be valid.
+     * Warnings will be emitted and undefined behaviour may result if invalid
+     * properties are passed in.
+     * @param nProperties - the number of properties
+     * @param names - the names of each property to get
+     * @param values - the values of each property to get
+     */
     getv(nProperties: number, names: string[], values: Value[]): void;
+    /**
+     * Checks whether `object` has a [floating][floating-ref] reference.
+     */
     isFloating(): boolean;
+    /**
+     * Emits a "notify" signal for the property `property_name` on @object.
+     *
+     * When possible, eg. when signaling a property change from within the class
+     * that registered the property, you should use g_object_notify_by_pspec()
+     * instead.
+     *
+     * Note that emission of the notify signal may be blocked with
+     * g_object_freeze_notify(). In this case, the signal emissions are queued
+     * and will be emitted (in reverse order) when g_object_thaw_notify() is
+     * called.
+     * @param propertyName - the name of a property installed on the class of @object.
+     */
     notify(propertyName: string): void;
+    /**
+     * Emits a "notify" signal for the property specified by `pspec` on @object.
+     *
+     * This function omits the property name lookup, hence it is faster than
+     * g_object_notify().
+     *
+     * One way to avoid using g_object_notify() from within the
+     * class that registered the properties, and using g_object_notify_by_pspec()
+     * instead, is to store the GParamSpec used with
+     * g_object_class_install_property() inside a static array, e.g.:
+     *
+     * |[<!-- language="C" -->
+     * typedef enum
+     * {
+     * PROP_FOO = 1,
+     * PROP_LAST
+     * } MyObjectProperty;
+     *
+     * static GParamSpec *properties[PROP_LAST];
+     *
+     * static void
+     * my_object_class_init (MyObjectClass *klass)
+     * {
+     * properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
+     * 0, 100,
+     * 50,
+     * G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+     * g_object_class_install_property (gobject_class,
+     * PROP_FOO,
+     * properties[PROP_FOO]);
+     * }
+     * ]|
+     *
+     * and then notify a change on the "foo" property with:
+     *
+     * |[<!-- language="C" -->
+     * g_object_notify_by_pspec (self, properties[PROP_FOO]);
+     * ]|
+     * @param pspec - the #GParamSpec of a property installed on the class of @object.
+     */
     notifyByPspec(pspec: ParamSpec): void;
+    /**
+     * Increases the reference count of @object.
+     *
+     * Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type
+     * of `object` will be propagated to the return type (using the GCC typeof()
+     * extension), so any casting the caller needs to do on the return type must be
+     * explicit.
+     */
     ref(): GObject;
+    /**
+     * Increase the reference count of @object, and possibly remove the
+     * [floating][floating-ref] reference, if `object` has a floating reference.
+     *
+     * In other words, if the object is floating, then this call "assumes
+     * ownership" of the floating reference, converting it to a normal
+     * reference by clearing the floating flag while leaving the reference
+     * count unchanged.  If the object is not floating, then this call
+     * adds a new normal reference increasing the reference count by one.
+     *
+     * Since GLib 2.56, the type of `object` will be propagated to the return type
+     * under the same conditions as for g_object_ref().
+     */
     refSink(): GObject;
+    /**
+     * Releases all references to other objects. This can be used to break
+     * reference cycles.
+     *
+     * This function should only be called from object system implementations.
+     */
     runDispose(): void;
+    /**
+     * Each object carries around a table of associations from
+     * strings to pointers.  This function lets you set an association.
+     *
+     * If the object already had an association with that name,
+     * the old association will be destroyed.
+     *
+     * Internally, the `key` is converted to a #GQuark using g_quark_from_string().
+     * This means a copy of `key` is kept permanently (even after `object` has been
+     * finalized) — so it is recommended to only use a small, bounded set of values
+     * for `key` in your program, to avoid the #GQuark storage growing unbounded.
+     * @param key - name of the key
+     * @param data - data to associate with that key
+     */
     setData(key: string, data?: number | null): void;
+    /**
+     * Sets a property on an object.
+     * @param propertyName - the name of the property to set
+     * @param value - the value
+     */
     setProperty(propertyName: string, value: Value): void;
+    /**
+     * Remove a specified datum from the object's data associations,
+     * without invoking the association's destroy handler.
+     * @param key - name of the key
+     */
     stealData(key: string): number | null;
+    /**
+     * This function gets back user data pointers stored via
+     * g_object_set_qdata() and removes the `data` from object
+     * without invoking its destroy() function (if any was
+     * set).
+     * Usually, calling this function is only required to update
+     * user data pointers with a destroy notifier, for example:
+     * |[<!-- language="C" -->
+     * void
+     * object_add_to_user_list (GObject     *object,
+     * const gchar *new_string)
+     * {
+     * // the quark, naming the object data
+     * GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
+     * // retrieve the old string list
+     * GList *list = g_object_steal_qdata (object, quark_string_list);
+     *
+     * // prepend new string
+     * list = g_list_prepend (list, g_strdup (new_string));
+     * // this changed 'list', so we need to set it again
+     * g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
+     * }
+     * static void
+     * free_string_list (gpointer data)
+     * {
+     * GList *node, *list = data;
+     *
+     * for (node = list; node; node = node->next)
+     * g_free (node->data);
+     * g_list_free (list);
+     * }
+     * ]|
+     * Using g_object_get_qdata() in the above example, instead of
+     * g_object_steal_qdata() would have left the destroy function set,
+     * and thus the partial string list would have been freed upon
+     * g_object_set_qdata_full().
+     * @param quark - A #GQuark, naming the user data pointer
+     */
     stealQdata(quark: number): number | null;
+    /**
+     * Reverts the effect of a previous call to
+     * g_object_freeze_notify(). The freeze count is decreased on `object` and when it reaches zero, queued "notify" signals are emitted.
+     *
+     * Duplicate notifications for each property are squashed so that at most one
+     * #GObject::notify signal is emitted for each property, in the reverse order
+     * in which they have been queued.
+     *
+     * It is an error to call this function when the freeze count is zero.
+     */
     thawNotify(): void;
+    /**
+     * Decreases the reference count of @object. When its reference count
+     * drops to 0, the object is finalized (i.e. its memory is freed).
+     *
+     * If the pointer to the #GObject may be reused in future (for example, if it is
+     * an instance variable of another object), it is recommended to clear the
+     * pointer to %NULL rather than retain a dangling pointer to a potentially
+     * invalid #GObject instance. Use g_clear_object() for this.
+     */
     unref(): void;
+    /**
+     * This function essentially limits the life time of the `closure` to
+     * the life time of the object. That is, when the object is finalized,
+     * the `closure` is invalidated by calling g_closure_invalidate() on
+     * it, in order to prevent invocations of the closure with a finalized
+     * (nonexisting) object. Also, g_object_ref() and g_object_unref() are
+     * added as marshal guards to the @closure, to ensure that an extra
+     * reference count is held on `object` during invocation of the
+     * @closure.  Usually, this function will be called on closures that
+     * use this `object` as closure data.
+     * @param closure - #GClosure to watch
+     */
     watchClosure(closure: Closure): void;
     connect(signal: "notify", handler: (self: GObject, pspec: ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;