gobject.types

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

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

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

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 GClassInitFunc() for a discussion of the class initialization process.

A function to be called to transform from_value to to_value.

If this is the transform_to function of a binding, then from_value is the source_property on the source object, and to_value is the target_property on the target object. If this is the transform_from function of a [gobject.types.BindingFlags.Bidirectional] binding, then those roles are reversed.

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

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

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 #GCallback.

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 GBaseInitFunc() and GBaseFinalizeFunc().

Also, specification of a GClassFinalizeFunc() in the #GTypeInfo structure 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).

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 GBaseInitFunc() initializers of all parent

types and the class' type.

• Invocation of the class' GClassInitFunc() initializer.

Since derived classes are partially initialized through a memory copy of the parent class, the general rule is that GBaseInitFunc() and GBaseFinalizeFunc() should take care of necessary reinitialization and release of those class members that were introduced by the type that specified these GBaseInitFunc()/GBaseFinalizeFunc(). GClassInitFunc() 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 GBaseInitFunc() 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, see [gobject.type_class.TypeClass.ref_] on this).

Initialization of TypeAClass roughly involves zero-initializing its fields, then calling its GBaseInitFunc() type_a_base_class_init() to allocate its dynamic members (dynamic_string), and finally calling its GClassInitFunc() 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 GBaseInitFunc() of TypeBClass, type_b_base_class_init() is called to allocate the dynamic members of TypeBClass (dynamic_gstring), and finally the GClassInitFunc() 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 GBaseInitFunc() functions have to be provided to release allocated resources at class finalization time.

The type used for marshaller functions.

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

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.

The type of the finalize function of #GObjectClass.

The type of the get_property function of #GObjectClass.

The type of the set_property function of #GObjectClass.

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 null, no accumulation of callback return values is performed. The return value of signal emissions is then the value returned by the last callback.

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 G_SIGNAL_NO_HOOKS flag.

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

See also: [gobject.object.ObjectWrap.addToggleRef]

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

It may use [gobject.type_class.TypeClass.ref_] to prevent the class from being freed. You should not call [gobject.type_class.TypeClass.unref] from a #GTypeClassCacheFunc function to prevent infinite recursion, use [gobject.type_class.TypeClass.unrefUncached] 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 #GTypeClassCacheFunc chain.

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:

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

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:

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

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:

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

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;

The type of value transformation functions which can be registered with [gobject.value.Value.registerTransformFunc].

dest_value will be initialized to the correct destination type.

A #GWeakNotify 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 #GWeakNotify 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.ObjectWrap.ref_], [gobject.weak_ref.WeakRef.init_], [gobject.weak_ref.WeakRef.set], [gobject.object.ObjectWrap.addToggleRef], [gobject.object.ObjectWrap.weakRef], [gobject.object.ObjectWrap.addWeakPointer] or any function which calls them on the object from this callback.

Fundamental GType values as an enum

Mask containing the bits of #GParamSpec.flags which are reserved for GLib.

#GParamFlags value alias for G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB.

It is recommended to use this for all properties by default, as it allows for internal performance improvements in GObject.

It is very rare that a property would have a dynamically constructed name, nickname or blurb.

Since 2.13.0

Minimum shift count to be used for user defined flags, to be stored in #GParamSpec.flags. The maximum allowed is 10.

A mask for all #GSignalFlags bits.

A mask for all #GSignalMatchType bits.

A bit in the type number that's supposed to be left untouched.

An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time.

Shift value used in converting numbers to type IDs.

First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.

Last fundamental type number reserved for BSE.

First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.

Last fundamental type number reserved for GLib.

First available fundamental type number to create new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL().

The maximal number of #GTypeCValues which can be collected for a single #GValue.

For string values, indicates that the string contained is canonical and will exist for the duration of the process. See [gobject.value.Value.setInternedString].

If passed to G_VALUE_COLLECT(), allocated data won't be copied but used verbatim. This does not affect ref-counted types like objects. This does not affect usage of [gobject.value.Value.copy], the data will be copied if it is not ref-counted.

Fundamental GType shift value (G_TYPE_FUNDAMENTAL_SHIFT)