Callbacks -

GObject 2.0 ([original](https://lazka.github.io/pgi-docs/GObject-2.0/callbacks.html)) ([raw](?raw))

Details¶

GObject.BaseFinalizeFunc(g_class)¶

Parameters:

g_class (GObject.TypeClass) – The GObject.TypeClass structure to finalize

A callback function used by the type system to finalize those portions of a derived types class structure that were setup from the correspondingGObject.BaseInitFunc() function.

Class finalization basically works the inverse way in which class initialization is performed.

See GObject.ClassInitFunc() for a discussion of the class initialization process.

GObject.BaseInitFunc(g_class)¶

Parameters:

g_class (GObject.TypeClass) – The GObject.TypeClass structure to initialize

A callback function used by the type system to do base initialization of the class structures of derived types.

This function is called as part of the initialization process of all derived classes and should reallocate or reset all dynamic class members copied over from the parent class.

For example, class members (such as strings) that are not sufficiently handled by a plain memory copy of the parent class into the derived class have to be altered. See GObject.ClassInitFunc() for a discussion of the class initialization process.

GObject.BindingTransformFunc(binding, from_value, to_value, *user_data)¶

Parameters:

• binding (GObject.Binding) – a GObject.Binding
• from_value (GObject.Value) – the GObject.Value containing the value to transform
• to_value (GObject.Value) – the GObject.Value in which to store the transformed value
• user_data (object or None) – data passed to the transform function

Returns:

True if the transformation was successful, and Falseotherwise

Return type:

bool

A function to be called to transform from_value to to_value.

If this is the transform_to function of a binding, then from_valueis the source_property on the source object, and to_value is thetarget_property on the target object. If this is thetransform_from function of a GObject.BindingFlags.BIDIRECTIONAL binding, then those roles are reversed.

New in version 2.26.

GObject.BoxedCopyFunc(boxed)¶

Parameters:

boxed (object) – The boxed structure to be copied.

Returns:

The newly created copy of the boxed structure.

Return type:

object

This function is provided by the user and should produce a copy of the passed in boxed structure.

GObject.BoxedFreeFunc(boxed)¶

Parameters:

boxed (object) – The boxed structure to be freed.

This function is provided by the user and should free the boxed structure passed.

GObject.Callback()¶

The type used for callback functions in structure definitions and function signatures.

This doesn’t mean that all callback functions must take no parameters and return void. The required signature of a callback function is determined by the context in which is used (e.g. the signal to which it is connected).

Use G_CALLBACK() to cast the callback function to a GObject.Callback.

GObject.ClassFinalizeFunc(g_class, class_data)¶

Parameters:

• g_class (GObject.TypeClass) – The GObject.TypeClass structure to finalize
• class_data (object or None) – The class_data member supplied via the GObject.TypeInfo structure

A callback function used by the type system to finalize a class.

This function is rarely needed, as dynamically allocated class resources should be handled by GObject.BaseInitFunc() and GObject.BaseFinalizeFunc().

Also, specification of a GObject.ClassFinalizeFunc() in the GObject.TypeInfostructure of a static type is invalid, because classes of static types will never be finalized (they are artificially kept alive when their reference count drops to zero).

GObject.ClassInitFunc(g_class, class_data)¶

Parameters:

• g_class (GObject.TypeClass) – The GObject.TypeClass structure to initialize.
• class_data (object or None) – The class_data member supplied via the GObject.TypeInfo structure.

A callback function used by the type system to initialize the class of a specific type.

This function should initialize all static class members.

The initialization process of a class involves:

• Copying common members from the parent class over to the derived class structure.
• Zero initialization of the remaining members not copied over from the parent class.
• Invocation of the GObject.BaseInitFunc() initializers of all parent types and the class’ type.
• Invocation of the class’ GObject.ClassInitFunc() initializer.

Since derived classes are partially initialized through a memory copy of the parent class, the general rule is that GObject.BaseInitFunc() andGObject.BaseFinalizeFunc() should take care of necessary reinitialization and release of those class members that were introduced by the type that specified these GObject.BaseInitFunc()/GObject.BaseFinalizeFunc().GObject.ClassInitFunc() should only care about initializing static class members, while dynamic class members (such as allocated strings or reference counted resources) are better handled by a GObject.BaseInitFunc() for this type, so proper initialization of the dynamic class members is performed for class initialization of derived types as well.

An example may help to correspond the intend of the different class initializers:

typedef struct { GObjectClass parent_class; gint static_integer; gchar *dynamic_string; } TypeAClass; static void type_a_base_class_init (TypeAClass *class) { class->dynamic_string = g_strdup ("some string"); } static void type_a_base_class_finalize (TypeAClass *class) { g_free (class->dynamic_string); } static void type_a_class_init (TypeAClass *class) { class->static_integer = 42; }

typedef struct { TypeAClass parent_class; gfloat static_float; GString *dynamic_gstring; } TypeBClass; static void type_b_base_class_init (TypeBClass *class) { class->dynamic_gstring = g_string_new ("some other string"); } static void type_b_base_class_finalize (TypeBClass *class) { g_string_free (class->dynamic_gstring); } static void type_b_class_init (TypeBClass *class) { class->static_float = 3.14159265358979323846; }

Initialization of TypeBClass will first cause initialization of TypeAClass (derived classes reference their parent classes, seeGObject.TypeClass.ref() on this).

Initialization of TypeAClass roughly involves zero-initializing its fields, then calling its GObject.BaseInitFunc() type_a_base_class_init() to allocate its dynamic members (dynamic_string), and finally calling its GObject.ClassInitFunc() type_a_class_init() to initialize its static members (static_integer). The first step in the initialization process of TypeBClass is then a plain memory copy of the contents of TypeAClass into TypeBClass and zero-initialization of the remaining fields in TypeBClass. The dynamic members of TypeAClass within TypeBClass now need reinitialization which is performed by calling type_a_base_class_init() with an argument of TypeBClass.

After that, the GObject.BaseInitFunc() of TypeBClass, type_b_base_class_init() is called to allocate the dynamic members of TypeBClass (dynamic_gstring), and finally the GObject.ClassInitFunc() of TypeBClass, type_b_class_init(), is called to complete the initialization process with the static members (static_float).

Corresponding finalization counter parts to the GObject.BaseInitFunc() functions have to be provided to release allocated resources at class finalization time.

GObject.ClosureMarshal(closure, return_value, param_values, invocation_hint, marshal_data)¶

Parameters:

• closure (GObject.Closure) – the GObject.Closure to which the marshaller belongs
• return_value (GObject.Value or None) – a GObject.Value to store the return value. May be None if the callback of closure doesn’t return a value.
• param_values ([GObject.Value]) – an array ofGObject.Values holding the arguments on which to invoke the callback of closure
• invocation_hint (object or None) – the invocation hint given as the last argument to GObject.Closure.invoke()
• marshal_data (object or None) – additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal()

The type used for marshaller functions.

GObject.ClosureNotify(data, closure)¶

Parameters:

• data (object or None) – data specified when registering the notification callback
• closure (GObject.Closure) – the GObject.Closure on which the notification is emitted

The type used for the various notification callbacks which can be registered on closures.

GObject.InstanceInitFunc(instance, g_class)¶

Parameters:

• instance (GObject.TypeInstance) – The instance to initialize
• g_class (GObject.TypeClass) – The class of the type the instance is created for

A callback function used by the type system to initialize a new instance of a type.

This function initializes all instance members and allocates any resources required by it.

Initialization of a derived instance involves calling all its parent types instance initializers, so the class member of the instance is altered during its initialization to always point to the class that belongs to the type the current initializer was introduced for.

The extended members of instance are guaranteed to have been filled with zeros before this function is called.

GObject.InterfaceFinalizeFunc(g_iface, iface_data)¶

Parameters:

• g_iface (GObject.TypeInterface) – The interface structure to finalize
• iface_data (object or None) – The interface_data supplied via the GObject.InterfaceInfo structure

A callback function used by the type system to finalize an interface.

This function should destroy any internal data and release any resources allocated by the corresponding GObject.InterfaceInitFunc() function.

GObject.InterfaceInitFunc(g_iface, iface_data)¶

Parameters:

• g_iface (GObject.TypeInterface) – The interface structure to initialize
• iface_data (object or None) – The interface_data supplied via the GObject.InterfaceInfo structure

A callback function used by the type system to initialize a new interface.

This function should initialize all internal data and* allocate any resources required by the interface.

The members of iface_data are guaranteed to have been filled with zeros before this function is called.

GObject.ObjectFinalizeFunc(object)¶

Parameters:

object (GObject.Object) – the GObject.Object being finalized

The type of the finalize function of GObject.ObjectClass.

GObject.ObjectGetPropertyFunc(object, property_id, value, pspec)¶

Parameters:

• object (GObject.Object) – a GObject.Object
• property_id (int) – the numeric id under which the property was registered withGObject.ObjectClass.install_property().
• value (GObject.Value) – a GObject.Value to return the property value in
• pspec (GObject.ParamSpec) – the GObject.ParamSpec describing the property

The type of the get_property function of GObject.ObjectClass.

GObject.ObjectSetPropertyFunc(object, property_id, value, pspec)¶

Parameters:

• object (GObject.Object) – a GObject.Object
• property_id (int) – the numeric id under which the property was registered withGObject.ObjectClass.install_property().
• value (GObject.Value) – the new value for the property
• pspec (GObject.ParamSpec) – the GObject.ParamSpec describing the property

The type of the set_property function of GObject.ObjectClass.

GObject.SignalAccumulator(ihint, return_accu, handler_return, data)¶

Parameters:

• ihint (GObject.SignalInvocationHint) – Signal invocation hint, see GObject.SignalInvocationHint.
• return_accu (GObject.Value) – Accumulator to collect callback return values in, this is the return value of the current signal emission.
• handler_return (GObject.Value) – A GObject.Value holding the return value of the signal handler.
• data (object or None) – Callback data that was specified when creating the signal.

Returns:

The accumulator function returns whether the signal emission should be aborted. Returning True will continue with the signal emission. Returning False will abort the current emission. Since 2.62, returning False will skip to the CLEANUP stage. In this case, emission will occur as normal in the CLEANUP stage and the handler’s return value will be accumulated.

Return type:

bool

The signal accumulator is a special callback function that can be used to collect return values of the various callbacks that are called during a signal emission.

The signal accumulator is specified at signal creation time, if it is left None, no accumulation of callback return values is performed. The return value of signal emissions is then the value returned by the last callback.

GObject.SignalEmissionHook(ihint, param_values, data)¶

Parameters:

• ihint (GObject.SignalInvocationHint) – Signal invocation hint, see GObject.SignalInvocationHint.
• param_values ([GObject.Value]) – the instance on which the signal was emitted, followed by the parameters of the emission.
• data (object or None) – user data associated with the hook.

Returns:

whether it wants to stay connected. If it returns False, the signal hook is disconnected (and destroyed).

Return type:

bool

A simple function pointer to get invoked when the signal is emitted.

Emission hooks allow you to tie a hook to the signal type, so that it will trap all emissions of that signal, from any object.

You may not attach these to signals created with the GObject.SignalFlags.NO_HOOKS flag.

GObject.ToggleNotify(data, object, is_last_ref)¶

Parameters:

• data (object or None) – Callback data passed to g_object_add_toggle_ref()
• object (GObject.Object) – The object on which g_object_add_toggle_ref() was called.
• is_last_ref (bool) – True if the toggle reference is now the last reference to the object. False if the toggle reference was the last reference and there are now other references.

A callback function used for notification when the state of a toggle reference changes.

See also: g_object_add_toggle_ref()

GObject.TypeClassCacheFunc(cache_data, g_class)¶

Parameters:

• cache_data (object or None) – data that was given to the g_type_add_class_cache_func() call
• g_class (GObject.TypeClass) – The GObject.TypeClass structure which is unreferenced

Returns:

True to stop further GObject.TypeClassCacheFuncs from being called, False to continue

Return type:

bool

A callback function which is called when the reference count of a class drops to zero.

It may use GObject.TypeClass.ref() to prevent the class from being freed. You should not call GObject.TypeClass.unref() from a GObject.TypeClassCacheFunc function to prevent infinite recursion, use g_type_class_unref_uncached() instead.

The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all classes are routed through the same GObject.TypeClassCacheFunc chain.

GObject.TypeInterfaceCheckFunc(check_data, g_iface)¶

Parameters:

• check_data (object or None) – data passed to g_type_add_interface_check()
• g_iface (GObject.TypeInterface) – the interface that has been initialized

A callback called after an interface vtable is initialized.

See g_type_add_interface_check().

New in version 2.4.

GObject.TypePluginCompleteInterfaceInfo(plugin, instance_type, interface_type, info)¶

Parameters:

• plugin (GObject.TypePlugin) – the GObject.TypePlugin
• instance_type (GObject.GType) – the GObject.GType of an instantiatable type to which the interface is added
• interface_type (GObject.GType) – the GObject.GType of the interface whose info is completed
• info (GObject.InterfaceInfo) – the GObject.InterfaceInfo to fill in

The type of the complete_interface_info function of GObject.TypePluginClass.

GObject.TypePluginCompleteTypeInfo(plugin, g_type, info, value_table)¶

Parameters:

• plugin (GObject.TypePlugin) – the GObject.TypePlugin
• g_type (GObject.GType) – the GObject.GType whose info is completed
• info (GObject.TypeInfo) – the GObject.TypeInfo struct to fill in
• value_table (GObject.TypeValueTable) – the GObject.TypeValueTable to fill in

The type of the complete_type_info function of GObject.TypePluginClass.

GObject.TypePluginUnuse(plugin)¶

Parameters:

plugin (GObject.TypePlugin) – the GObject.TypePlugin whose use count should be decreased

The type of the unuse_plugin function of GObject.TypePluginClass.

GObject.TypePluginUse(plugin)¶

Parameters:

plugin (GObject.TypePlugin) – the GObject.TypePlugin whose use count should be increased

The type of the use_plugin function of GObject.TypePluginClass, which gets called to increase the use count of plugin.

GObject.TypeValueCollectFunc(value, collect_values, collect_flags)¶

Parameters:

• value (GObject.Value) – the value to initialize
• collect_values ([GObject.TypeCValue]) – the collected values
• collect_flags (int) – optional flags

Returns:

NULL on success, otherwise a newly allocated error string on failure

Return type:

str or None

This function is responsible for converting the values collected from a variadic argument list into contents suitable for storage in a GObject.Value.

This function should setup value similar to GObject.TypeValueInitFunc; 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 GObject.TypeValueInitFunc 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_formatfield of GObject.TypeValueTable, and collect_values is an array of GObject.TypeCValuewith 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 GObject.VALUE_NOCOPY_CONTENTS indicating that the collected value contents may be considered ‘static’ for the duration of the valuelifetime. 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:

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 theGObject.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->dataarray. To deviate from our string example for a moment, and taking a look at an exemplary implementation for GTypeValueTable.collect_value()of GObject :

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.

New in version 2.78.

GObject.TypeValueCopyFunc(src_value)¶

Parameters:

src_value (GObject.Value) – the value to copy

Returns:

the location of the copy

Return type:

dest_value: GObject.Value

Copies the content of a GObject.Value into another.

The dest_value is a GObject.Value with zero-filled data section and src_valueis a properly initialized GObject.Value of same type, or derived type.

The purpose of this function is to copy the contents of src_valueinto dest_value in a way, that even after src_value has been freed, the contents of dest_value remain valid. String type example:

dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);

New in version 2.78.

GObject.TypeValueFreeFunc(value)¶

Parameters:

value (GObject.Value) – the value to free

Frees any old contents that might be left in the value->data array of the given value.

No resources may remain allocated through the GObject.Value contents after this function returns. E.g. for our above string type:

// 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);

New in version 2.78.

GObject.TypeValueInitFunc(value)¶

Parameters:

value (GObject.Value) – the value to initialize

Initializes the value contents by setting the fields of the value->dataarray.

The data array of the GObject.Value 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 None, the implementation might look like:

value->data[0].v_pointer = g_strdup ("");

New in version 2.78.

GObject.TypeValueLCopyFunc(value, collect_values, collect_flags)¶

Parameters:

• value (GObject.Value) – the value to lcopy
• collect_values ([GObject.TypeCValue]) – the collected locations for storage
• collect_flags (int) – optional flags

Returns:

NULL on success, otherwise a newly allocated error string on failure

Return type:

str or None

This function is responsible for storing the valuecontents 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 oflcopy_format, and collect_flags may contain GObject.VALUE_NOCOPY_CONTENTS.

In contrast to GObject.TypeValueCollectFunc, this function is obliged to always properly support GObject.VALUE_NOCOPY_CONTENTS.

Similar to GObject.TypeValueCollectFunc the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example:

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:

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;

New in version 2.78.

GObject.TypeValuePeekPointerFunc(value)¶

Parameters:

value (GObject.Value) – the value to peek

Returns:

a pointer to the value contents

Return type:

object or None

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:

return value->data[0].v_pointer;

New in version 2.78.

GObject.ValueTransform(src_value, dest_value)¶

Parameters:

• src_value (GObject.Value) – Source value.
• dest_value (GObject.Value) – Target value.

The type of value transformation functions which can be registered with g_value_register_transform_func().

dest_value will be initialized to the correct destination type.

GObject.WeakNotify(data, where_the_object_was)¶

Parameters:

• data (object or None) – data that was provided when the weak reference was established
• where_the_object_was (GObject.Object) – the object being disposed

A GObject.WeakNotify function can be added to an object as a callback that gets triggered when the object is finalized.

Since the object is already being disposed when the GObject.WeakNotify is called, there’s not much you could do with the object, apart from e.g. using its address as hash-index or the like.

In particular, this means it’s invalid to call GObject.Object.ref(), g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(), g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls them on the object from this callback.