gobject.c.types

This is the signature of marshaller functions, required to marshall arrays of parameter values to signal emissions into C language callback invocations.

It is merely an alias to #GClosureMarshal since the #GClosure mechanism takes over responsibility of actual function invocation for the signal system.

This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues.

A numerical value which represents the unique identifier of a registered type.

Flags to be passed to [gobject.object.ObjectWrap.bindProperty] or [gobject.object.ObjectWrap.bindPropertyFull].

This enumeration can be extended at later date.

The connection flags are used to specify the behaviour of a signal's connection.

Through the #GParamFlags flag values, certain aspects of parameters can be configured.

See also: [gobject.types.PARAM_STATIC_STRINGS]

The signal flags are used to specify a signal's behaviour.

The match types specify what [gobject.global.signalHandlersBlockMatched], [gobject.global.signalHandlersUnblockMatched] and [gobject.global.signalHandlersDisconnectMatched] match signals by.

These flags used to be passed to [gobject.global.typeInitWithDebugFlags] which is now deprecated.

If you need to enable debugging features, use the GOBJECT_DEBUG environment variable.

Bit masks used to check or determine characteristics of a type.

Bit masks used to check or determine specific characteristics of a fundamental type.

[gobject.object.ObjectWrap] instance (or source) and another property on another [gobject.object.ObjectWrap] instance (or target).

Whenever the source property changes, the same value is applied to the target property; for instance, the following binding:

g_object_bind_property (object1, "property-a",
                         object2, "property-b",
                         G_BINDING_DEFAULT);

will cause the property named "property-b" of @object2 to be updated every time method@GObject.set or the specific accessor changes the value of the property "property-a" of @object1.

It is possible to create a bidirectional binding between two properties of two [gobject.object.ObjectWrap] instances, so that if either property changes, the other is updated as well, for instance:

g_object_bind_property (object1, "property-a",
                         object2, "property-b",
                         G_BINDING_BIDIRECTIONAL);

will keep the two properties in sync.

It is also possible to set a custom transformation function (in both directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding:

g_object_bind_property_full (adjustment1, "value",
                              adjustment2, "value",
                              G_BINDING_BIDIRECTIONAL,
                              celsius_to_fahrenheit,
                              fahrenheit_to_celsius,
                              NULL, NULL);

will keep the "value" property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the "value" property of @adjustment1 changes and will transform the current value of the property before applying it to the "value" property of @adjustment2.

Vice versa, the @fahrenheit_to_celsius function will be called whenever the "value" property of @adjustment2 changes, and will transform the current value of the property before applying it to the "value" property of @adjustment1.

Note that #GBinding does not resolve cycles by itself; a cycle like

object1:propertyA -> object2:propertyB
 object2:propertyB -> object3:propertyC
 object3:propertyC -> object1:propertyA

might lead to an infinite loop. The loop, in this particular case, can be avoided if the objects emit the GObject::notify signal only if the value has effectively been changed. A binding is implemented using the GObject::notify signal, so it is susceptible to all the various ways of blocking a signal emission, like func@GObject.signal_stop_emission or func@GObject.signal_handler_block.

A binding will be severed, and the resources it allocates freed, whenever either one of the [gobject.object.ObjectWrap] instances it refers to are finalized, or when the #GBinding instance loses its last reference.

Bindings for languages with garbage collection can use [gobject.binding.Binding.unbind] to explicitly release a binding between the source and target properties, instead of relying on the last reference on the binding, source, and target instances to drop.

[gobject.binding_group.BindingGroup] can be used to bind multiple properties from an object collectively.

Use the various methods to bind properties from a single source object to multiple destination objects. Properties can be bound bidirectionally and are connected when the source object is set with [gobject.binding_group.BindingGroup.setSource].

A #GCClosure is a specialization of #GClosure for C function callbacks.

A [gobject.closure.Closure] represents a callback supplied by the programmer.

It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from #GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a #GValue.

In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument, and the marshaller converts between #GValue and native C types. The GObject library provides the #GCClosure type for this purpose. Bindings for other languages need marshallers which convert between #GValues and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use [gobject.closure.Closure.setMarshal] to set the marshaller on such a custom closure implementation.

Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the @c_marshaller argument to [gobject.global.signalNew] specifies the default C marshaller for any closure which is connected to this signal. GObject provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the [glib-genmarshal][glib-genmarshal] utility. Closures can be explicitly connected to signals with [gobject.global.signalConnectClosure], but it usually more convenient to let GObject create a closure automatically by using one of the g_signal_connect_*() functions which take a callback function/user data pair.

Using closures has a number of important advantages over a simple callback function/data pointer combination:

• Closures allow the callee to get the types of the callback parameters,

which means that language bindings don't have to write individual glue for each callback type.

• The reference counting of #GClosure makes it easy to handle reentrancy

right; if a callback is removed while it is being invoked, the closure and its parameters won't be freed until the invocation finishes.

• [gobject.closure.Closure.invalidate] and invalidation notifiers allow callbacks to be

automatically removed when the objects they point to go away.

The class of an enumeration type holds information about its possible values.

A structure which contains a single enum value, its name, and its nickname.

The class of a flags type holds information about its possible values.

A structure which contains a single flags value, its name, and its nickname.

A type for objects that have an initially floating reference.

All the fields in the [gobject.initially_unowned.InitiallyUnowned] structure are private to the implementation and should never be accessed directly.

The class structure for the GInitiallyUnowned type.

A structure that provides information to the type system which is used specifically for managing interface types.

The class structure for the GObject type.

// Example of implementing a singleton using a constructor.
static MySingleton *the_singleton = NULL;

static GObject*
my_singleton_constructor (GType                  type,
                         guint                  n_construct_params,
                         GObjectConstructParam *construct_params)
{
 GObject *object;

 if (!the_singleton)
   {
     object = G_OBJECT_CLASS (parent_class)->constructor (type,
                                                          n_construct_params,
                                                          construct_params);
     the_singleton = MY_SINGLETON (object);
   }
 else
   object = g_object_ref (G_OBJECT (the_singleton));

 return object;
}

The GObjectConstructParam struct is an auxiliary structure used to hand #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass.

The base object type.

[gobject.object.ObjectWrap] is the fundamental type providing the common attributes and methods for all object types in GTK, Pango and other libraries based on GObject. The [gobject.object.ObjectWrap] class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail [here][gobject-Signals].

For a tutorial on implementing a new [gobject.object.ObjectWrap] class, see How to define and implement a new GObject. For a list of naming conventions for GObjects and their methods, see the

behind GObject, read

Since GLib 2.72, all [gobject.object.ObjectWrap]s are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is [gst.types.ulong] or gdouble). If you need larger alignment for an element in a [gobject.object.ObjectWrap], you should allocate it on the heap (aligned), or arrange for your [gobject.object.ObjectWrap] to be appropriately padded. This guarantee applies to the [gobject.object.ObjectWrap] (or derived) struct, the [gstpbutils.types.ObjectClass] (or derived) struct, and any private data allocated by G_ADD_PRIVATE().

[gobject.param_spec.ParamSpec] encapsulates the metadata required to specify parameters, such as [gobject.object.ObjectWrap] properties.

Parameter names

A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or _ character. The first character of a property name must be a letter. These are the same rules as for signal naming (see func@GObject.signal_new).

When creating and looking up a [gobject.param_spec.ParamSpec], either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using _ is discouraged.

A #GParamSpec derived structure that contains the meta data for boolean properties.

A #GParamSpec derived structure that contains the meta data for boxed properties.

A #GParamSpec derived structure that contains the meta data for character properties.

The class structure for the GParamSpec type. Normally, GParamSpec classes are filled by [gobject.global.paramTypeRegisterStatic].

A #GParamSpec derived structure that contains the meta data for double properties.

A #GParamSpec derived structure that contains the meta data for enum properties.

A #GParamSpec derived structure that contains the meta data for flags properties.

A #GParamSpec derived structure that contains the meta data for float properties.

A #GParamSpec derived structure that contains the meta data for #GType properties.

A #GParamSpec derived structure that contains the meta data for integer properties.

A #GParamSpec derived structure that contains the meta data for 64bit integer properties.

A #GParamSpec derived structure that contains the meta data for long integer properties.

A #GParamSpec derived structure that contains the meta data for object properties.

A #GParamSpec derived structure that redirects operations to other types of #GParamSpec.

All operations other than getting or setting the value are redirected, including accessing the nick and blurb, validating a value, and so forth.

See [gobject.param_spec.ParamSpec.getRedirectTarget] for retrieving the overridden property. #GParamSpecOverride is used in implementing [gobject.object_class.ObjectClass.overrideProperty], and will not be directly useful unless you are implementing a new base type similar to GObject.

A #GParamSpec derived structure that contains the meta data for G_TYPE_PARAM properties.

A #GParamSpec derived structure that contains the meta data for pointer properties.

A #GParamSpecPool maintains a collection of #GParamSpecs which can be quickly accessed by owner and name.

The implementation of the #GObject property system uses such a pool to store the #GParamSpecs of the properties all object types.

A #GParamSpec derived structure that contains the meta data for string properties.

This structure is used to provide the type system with the information required to initialize and destruct (finalize) a parameter's class and instances thereof.

The initialized structure is passed to the [gobject.global.paramTypeRegisterStatic] The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of [gobject.global.paramTypeRegisterStatic].

A #GParamSpec derived structure that contains the meta data for unsigned character properties.

A #GParamSpec derived structure that contains the meta data for unsigned integer properties.

A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.

A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.

A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.

A #GParamSpec derived structure that contains the meta data for #GValueArray properties.

A #GParamSpec derived structure that contains the meta data for #GVariant properties.

When comparing values with [gobject.global.paramValuesCmp], scalar values with the same type will be compared with [glib.variant.Variant.compare]. Other non-null variants will be checked for equality with [glib.variant.Variant.equal], and their sort order is otherwise undefined. null is ordered before non-null variants. Two null values compare equal.

The GParameter struct is an auxiliary structure used to hand parameter name/value pairs to [gobject.object.ObjectWrap.newv].

[gobject.signal_group.SignalGroup] manages a collection of signals on a [gobject.object.ObjectWrap].

[gobject.signal_group.SignalGroup] simplifies the process of connecting many signals to a [gobject.object.ObjectWrap] as a group. As such there is no API to disconnect a signal from the group.

In particular, this allows you to:

• Change the target instance, which automatically causes disconnection

of the signals from the old instance and connecting to the new instance.

• Block and unblock signals as a group
• Ensuring that blocked state transfers across target instances.

One place you might want to use such a structure is with [gtk.text_view.TextView] and [gtk.text_buffer.TextBuffer]. Often times, you'll need to connect to many signals on [gtk.text_buffer.TextBuffer] from a [gtk.text_view.TextView] subclass. This allows you to create a signal group during instance construction, simply bind the GtkTextView:buffer property to GSignalGroup:target and connect all the signals you need. When the GtkTextView:buffer property changes all of the signals will be transitioned correctly.

The #GSignalInvocationHint structure is used to pass on additional information to callbacks during a signal emission.

A structure holding in-depth information for a specific signal.

See also: [gobject.global.signalQuery]

A union holding one collected value.

An opaque structure used as the base of all classes.

A structure that provides information to the type system which is used specifically for managing fundamental types.

This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type's class and its instances.

The initialized structure is passed to the [gobject.global.typeRegisterStatic] function (or is copied into the provided #GTypeInfo structure in the [gobject.type_plugin.TypePlugin.completeTypeInfo]). The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of [gobject.global.typeRegisterStatic].

An opaque structure used as the base of all type instances.

An opaque structure used as the base of all interface types.

[gobject.type_module.TypeModule] provides a simple implementation of the [gobject.type_plugin.TypePlugin] interface.

The model of [gobject.type_module.TypeModule] is a dynamically loaded module which implements some number of types and interface implementations.

When the module is loaded, it registers its types and interfaces using [gobject.type_module.TypeModule.registerType] and [gobject.type_module.TypeModule.addInterface]. As long as any instances of these types and interface implementations are in use, the module is kept loaded. When the types and interfaces are gone, the module may be unloaded. If the types and interfaces become used again, the module will be reloaded. Note that the last reference cannot be released from within the module code, since that would lead to the caller's code being unloaded before [gobject.object.ObjectWrap.unref] returns to it.

Keeping track of whether the module should be loaded or not is done by using a use count - it starts at zero, and whenever it is greater than zero, the module is loaded. The use count is maintained internally by the type system, but also can be explicitly controlled by [gobject.type_module.TypeModule.use] and [gobject.type_module.TypeModule.unuse]. Typically, when loading a module for the first type, [gobject.type_module.TypeModule.use] will be used to load it so that it can initialize its types. At some later point, when the module no longer needs to be loaded except for the type implementations it contains, [gobject.type_module.TypeModule.unuse] is called.

[gobject.type_module.TypeModule] does not actually provide any implementation of module loading and unloading. To create a particular module type you must derive from [gobject.type_module.TypeModule] and implement the load and unload functions in [gobject.type_module_class.TypeModuleClass].

In order to implement dynamic loading of types based on #GTypeModule, the @load and @unload functions in #GTypeModuleClass must be implemented.

An interface that handles the lifecycle of dynamically loaded types.

The GObject type system supports dynamic loading of types. It goes as follows:

1. The type is initially introduced (usually upon loading the module

the first time, or by your main application that knows what modules introduces what types), like this:

new_type_id = g_type_register_dynamic (parent_type_id,
                                         "TypeName",
                                         new_type_plugin,
                                         type_flags);

1. The type's implementation is referenced, e.g. through

[gobject.type_class.TypeClass.ref_] or through func@GObject.type_create_instance (this is being called by [gobject.object.ObjectWrap.new_]) or through one of the above done on a type derived from new_type_id.

1. This causes the type system to load the type's implementation by calling

[gobject.type_plugin.TypePlugin.use] and [gobject.type_plugin.TypePlugin.completeTypeInfo] on new_type_plugin.

1. At some point the type's implementation isn't required anymore, e.g. after

[gobject.type_class.TypeClass.unref] or func@GObject.type_free_instance (called when the reference count of an instance drops to zero).

1. This causes the type system to throw away the information retrieved

from [gobject.type_plugin.TypePlugin.completeTypeInfo] and then it calls [gobject.type_plugin.TypePlugin.unuse] on new_type_plugin.

1. Things may repeat from the second step.

So basically, you need to implement a [gobject.type_plugin.TypePlugin] type that carries a use_count, once use_count goes from zero to one, you need to load the implementation to successfully handle the upcoming [gobject.type_plugin.TypePlugin.completeTypeInfo] call. Later, maybe after succeeding use/unuse calls, once use_count drops to zero, you can unload the implementation again. The type system makes sure to call [gobject.type_plugin.TypePlugin.use] and [gobject.type_plugin.TypePlugin.completeTypeInfo] again when the type is needed again.

[gobject.type_module.TypeModule] is an implementation of [gobject.type_plugin.TypePlugin] that already implements most of this except for the actual module loading and unloading. It even handles multiple registered types per module.

The #GTypePlugin interface is used by the type system in order to handle the lifecycle of dynamically loaded types.

A structure holding information for a specific type.

See also: [gobject.global.typeQuery]

The #GTypeValueTable provides the functions required by the #GValue implementation, to serve as a container for values of a type.

An opaque structure used to hold different types of values.

The data within the structure has protected scope: it is accessible only to functions within a #GTypeValueTable structure, or implementations of the g_value_*() API. That is, code portions which implement new fundamental types.

#GValue users cannot make any assumptions about how data is stored within the 2 element @data union, and the @g_type member should only be accessed through the G_VALUE_TYPE() macro.

A [gobject.value_array.ValueArray] is a container structure to hold an array of generic values.

The prime purpose of a [gobject.value_array.ValueArray] is for it to be used as an object property that holds an array of values. A [gobject.value_array.ValueArray] wraps an array of [gobject.value.Value] elements in order for it to be used as a boxed type through G_TYPE_VALUE_ARRAY.

[gobject.value_array.ValueArray] is deprecated in favour of [glib.array.Array] since GLib 2.32. It is possible to create a [glib.array.Array] that behaves like a [gobject.value_array.ValueArray] by using the size of [gobject.value.Value] as the element size, and by setting [gobject.value.Value.unset] as the clear function using [glib.array.Array.setClearFunc], for instance, the following code:

GValueArray *array = g_value_array_new (10);

can be replaced by:

GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
 g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);

A structure containing a weak reference to a #GObject.

A [gobject.weak_ref.WeakRef] can either be empty (i.e. point to null), or point to an object for as long as at least one "strong" reference to that object exists. Before the object's #GObjectClass.dispose method is called, every #GWeakRef associated with becomes empty (i.e. points to null).

Like #GValue, #GWeakRef can be statically allocated, stack- or heap-allocated, or embedded in larger structures.

Unlike [gobject.object.ObjectWrap.weakRef] and [gobject.object.ObjectWrap.addWeakPointer], this weak reference is thread-safe: converting a weak pointer to a reference is atomic with respect to invalidation of weak pointers to destroyed objects.

If the object's #GObjectClass.dispose method results in additional references to the object being held (‘re-referencing’), any #GWeakRefs taken before it was disposed will continue to point to null. Any #GWeakRefs taken during disposal and after re-referencing, or after disposal has returned due to the re-referencing, will continue to point to the object until its refcount goes back to zero, at which point they too will be invalidated.

It is invalid to take a #GWeakRef on an object during #GObjectClass.dispose without first having or creating a strong reference to the object.