Package gobject

The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined objects and interface types.

For type creation and registration purposes, all types fall into one of two categories: static or dynamic. Static types are never loaded or unloaded at run-time as dynamic types may be. Static types are created with the function g_type_register_static() that gets type specific information passed in via a GTypeInfo structure. Dynamic types are created with the function g_type_register_dynamic() which takes a GTypePlugin structure instead. The remaining type information (the GTypeInfo structure) is retrieved during runtime through the GTypePlugin structure and the g_type_plugin_*() API. These registration functions are usually called only once from a function whose only purpose is to return the type identifier for a specific class. Once the type (or class or interface) is registered, it may be instantiated, inherited, or implemented depending on exactly what sort of type it is. There is also a third registration function for registering fundamental types called g_type_register_fundamental() which requires both a GTypeInfo structure and a GTypeFundamentalInfo structure but it is seldom used since most fundamental types are predefined rather than user-defined.

Type instance and class structures are limited to a total of 64 KiB, including all parent types. Similarly, type instances' private data (as created by the function g_type_class_add_private()) are limited to a total of 64 KiB. If a type instance needs a large static buffer, allocate it separately (typically by using a GArray or GPtrArray structure) and put a pointer to the buffer in the structure.

A final word about type names. Such an identifier needs to be at least three characters long. There is no upper length limit. The first character needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent characters can be letters, numbers or any of '-_+'.

The GLib type system provides fundamental types for enumeration and flags types. Flags types are like enumerations, but allow their values to be combined by bitwise OR. A registered enumeration or flags type associates a name and a nickname with each allowed value. When an enumeration or flags type is registered with the GLib type system, it can be used as value type for object properties, using the g:param-spec-enum or g:param-spec-flags functions.

A mechanism to wrap opaque C structures registered by the type system

GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.

Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries. They allow arbitrary structures to be handled in a uniform way, allowing uniform copying (or referencing) and freeing (or unreferencing) of them, and uniform representation of the type of the contained structure. In turn, this allows any type which can be boxed to be set as the data in a GValue, which allows for polymorphic handling of a much wider range of data types, and hence usage of such types as GObject property values.

GBoxed is designed so that reference counted types can be boxed. Use the type’s ‘ref’ function as the GBoxedCopyFunc, and its ‘unref’ function as the GBoxedFreeFunc. For example, for GBytes, the GBoxedCopyFunc is g_bytes_ref(), and the GBoxedFreeFunc is g_bytes_unref().

Standard Parameter and Value Types

GValue provides an abstract container structure which can be copied, transformed and compared while holding a value of any (derived) type, which is registered as a GType with a GTypeValueTable in its GTypeInfo structure. Parameter specifications for most value types can be created as GParamSpec derived instances, to implement, for example, GObject properties which operate on GValue containers.

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. All other characters are replaced by a '-' during construction.

The basic concept of the signal system is that of the emission of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are available in derived types as well, so basically they are a per-type facility that is inherited.

A signal emission mainly involves invocation of a certain set of callbacks in precisely defined manner. There are two main categories of such callbacks, per-object ones and user provided ones. The per-object callbacks are most often referred to as "object method handler" or "default (signal) handler", while user provided callbacks are usually just called "signal handler".

The object method handler is provided at signal creation time, this most frequently happens at the end of an object class' creation, while user provided handlers are frequently connected and disconnected to/from a certain signal on certain object instances.

A signal emission consists of five stages, unless prematurely stopped:

1. Invocation of the object method handler for :run-first signals.
2. Invocation of normal user-provided signal handlers (where the after flag is not set).
3. Invocation of the object method handler for :run-last signals.
4. Invocation of user provided signal handlers (where the after flag is set).
5. Invocation of the object method handler for :run-cleanup signals.

The user-provided signal handlers are called in the order they were connected in.

All handlers may prematurely stop a signal emission, and any number of handlers may be connected, disconnected, blocked or unblocked during a signal emission.

There are certain criteria for skipping user handlers in stages 2 and 4 of a signal emission. First, user handlers may be blocked. Blocked handlers are omitted during callback invocation, to return from the blocked state, a handler has to get unblocked exactly the same amount of times it has been blocked before. Second, upon emission of a :detailed signal, an additional detail argument passed in to the g:signal-emit function has to match the detail argument of the signal handler currently subject to invocation. Specification of no detail argument for signal handlers (omission of the detail part of the signal specification upon connection) serves as a wildcard and matches any detail argument passed in to emission.

While the detail argument is typically used to pass an object property name, as with "notify", no specific format is mandated for the detail string, other than that it must be non-empty.