| <!-- ##### SECTION Title ##### --> |
| GType |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| The GLib Runtime type identification and management system |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| The GType API is the foundation of the GObject system. It provides the |
| facilities for registering and managing all fundamental data types, |
| user-defined object and interface types. Before using any GType |
| or GObject functions, g_type_init() must be called to initialize the |
| type system. |
| </para> |
| <para> |
| 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 g_type_register_static() that gets type specific information passed |
| in via a #GTypeInfo structure. |
| Dynamic types are created with g_type_register_dynamic() which takes a |
| #GTypePlugin structure instead. The remaining type information (the |
| #GTypeInfo structure) is retrived during runtime through #GTypePlugin |
| 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. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### TYPEDEF GType ##### --> |
| <para> |
| A numerical value which represents the unique identifier of a registered |
| type. |
| </para> |
| |
| |
| <!-- ##### MACRO G_TYPE_FUNDAMENTAL ##### --> |
| <para> |
| Returns #TRUE if @type is a fundamental data type such as #G_TYPE_INT or |
| #G_TYPE_POINTER. Fundamental types are types that serve as fundaments for |
| the derived types, thus they are the roots of distinct inheritance hierarchies. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_FUNDAMENTAL_MAX ##### --> |
| <para> |
| An integer constant that represents the number of identifiers reserved |
| for types that are assigned at compile-time. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_TYPE_DERIVE_ID ##### --> |
| <para> |
| |
| </para> |
| |
| @ptype: |
| @branch_seqno: |
| |
| |
| <!-- ##### MACRO G_TYPE_BRANCH_SEQNO ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| |
| |
| <!-- ##### MACRO G_TYPE_FUNDAMENTAL_LAST ##### --> |
| <para> |
| An integer that currently represents the highest value of all |
| fundamental type identifiers. This is of interest for dynamic |
| introduction of new fundamental types (a |
| <emphasis>rarely</emphasis> needed feature). |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_ABSTRACT ##### --> |
| <para> |
| Returns #TRUE if @type is an abstract type. An abstract type can not be |
| instantiated and is normally used as an abstract base class for |
| derived classes. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_DERIVED ##### --> |
| <para> |
| Returns #TRUE if @type is derived (or in object-oriented terminology: |
| inherited) from another type (this holds true for all non-fundamental |
| types). |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_FUNDAMENTAL ##### --> |
| <para> |
| Returns #TRUE if @type is a fundamental type. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_VALUE_TYPE ##### --> |
| <para> |
| |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_CLASSED ##### --> |
| <para> |
| Returns #TRUE if @type is a classed type. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_INSTANTIATABLE ##### --> |
| <para> |
| Returns #TRUE if @type can be instantiated. Instantiation is the |
| process of creating an instance (object) of this type. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_DERIVABLE ##### --> |
| <para> |
| Returns #TRUE if @type is a derivable type. A derivable type can |
| be used as the base class of a flat (single-level) class hierarchy. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_DEEP_DERIVABLE ##### --> |
| <para> |
| Returns #TRUE if @type is a deep derivable type. A deep derivable type |
| can be used as the base class of a deep (multi-level) class hierarchy. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_INTERFACE ##### --> |
| <para> |
| Returns #TRUE if @type is an interface type. |
| Interface types are types that provide pure APIs, the implementation |
| of which is provided by another type (which is then said to conform |
| to the interface). GLib interfaces are somewhat analogous to Java |
| interfaces and C++ classes containing only pure virtual functions. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### ENUM GTypeFundamentals ##### --> |
| <para> |
| The predefined identifiers of the reserved fundamental types. |
| </para> |
| |
| @G_TYPE_INVALID: Usually a return value indicating an error. |
| @G_TYPE_NONE: A synonym for the "void" type in C. |
| @G_TYPE_INTERFACE: Root type of all interface types. |
| @G_TYPE_CHAR: Identifier for the built-in type "gchar". |
| @G_TYPE_UCHAR: Identifier for the built-in type "guchar". |
| @G_TYPE_BOOLEAN: Identifier for the built-in type "gboolean". |
| @G_TYPE_INT: Identifier for the built-in type "gint". |
| @G_TYPE_UINT: Identifier for the built-in type "guint". |
| @G_TYPE_LONG: Identifier for the built-in type "glong". |
| @G_TYPE_ULONG: Identifier for the built-in type "gulong". |
| @G_TYPE_INT64: |
| @G_TYPE_UINT64: |
| @G_TYPE_ENUM: Identifier for the "#GEnum" type. |
| @G_TYPE_FLAGS: Identifier for the "#GFlags" type. |
| @G_TYPE_FLOAT: Identifier for the built-in type "gfloat". |
| @G_TYPE_DOUBLE: Identifier for the built-in type "gdouble". |
| @G_TYPE_STRING: Identifier for a pointer to a null-terminated string "gchar*". |
| @G_TYPE_POINTER: Identifier for anonymous pointers "void*". |
| @G_TYPE_BOXED: Identifier for the "#GBoxed" type. |
| @G_TYPE_PARAM: Identifier for the "#GParam" type. |
| @G_TYPE_OBJECT: Identifier for the "#GObject" type. |
| @G_TYPE_RESERVED_BSE_FIRST: First fundamental type ID reserved for BSE. |
| @G_TYPE_RESERVED_BSE_LAST: Last fundamental type ID reserved for BSE. |
| @G_TYPE_RESERVED_LAST_FUNDAMENTAL: Last reserved fundamental type ID. |
| |
| <!-- ##### STRUCT GTypeInterface ##### --> |
| <para> |
| An opaque structure used as the base of all interface types. |
| </para> |
| |
| |
| <!-- ##### STRUCT GTypeInstance ##### --> |
| <para> |
| An opaque structure used as the base of all type instances. |
| </para> |
| |
| |
| <!-- ##### STRUCT GTypeInfo ##### --> |
| <para> |
| This structure is used to provide the type system with the information |
| required to initialize and destruct (finalize) a type's class and |
| instances thereof. |
| The initialized structure is passed to the g_type_register_static() function |
| (or is copied into the provided #GTypeInfo structure in the |
| g_type_plugin_complete_type_info()). The type system will perform a deep |
| copy of this structure, so it's memory does not need to be persistent |
| across invocation of g_type_register_static(). |
| </para> |
| |
| @class_size: Size of the class structure (required for interface, classed and instantiatable types). |
| @base_init: Location of the base initialization function (optional). |
| @base_finalize: Location of the base finalization function (optional). |
| @class_init: Location of the class initialization function (optional, for classed and instantiatable types only). |
| @class_finalize: Location of the class finalization function (optional). |
| @class_data: User-supplied data passed to the class init/finalize functions. |
| @instance_size: Size of the instance (object) structure (required for instantiatable types only). |
| @n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). |
| @instance_init: Location of the instance initialization function (optional, for instantiatable types only). |
| @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usualy only |
| useful for fundamental types). |
| |
| <!-- ##### STRUCT GTypeFundamentalInfo ##### --> |
| <para> |
| A structure that provides information to the type system which is |
| used specifically for managing fundamental types. |
| </para> |
| |
| @type_flags: |
| |
| <!-- ##### STRUCT GInterfaceInfo ##### --> |
| <para> |
| A structure that provides information to the type system which is |
| used specifically for managing interface types. |
| </para> |
| |
| @interface_init: Location of the function that initializes the interface. |
| @interface_finalize: Location of the function that finalizes the interface. |
| @interface_data: Location of user data passed to the @interface_init and |
| @interface_finalize functions (optional). |
| |
| <!-- ##### STRUCT GTypeValueTable ##### --> |
| <para> |
| The #GTypeValueTable provides the functions required by the #GValue implementation, |
| to serve as a container for values of a type. |
| </para> |
| |
| @value_init: Default initialize @values contents by poking values |
| directly into 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. E.g. for the implementation of a string |
| value that may never be NULL, the implementation might |
| look like: |
| <msgtext><programlisting> |
| { |
| value->data[0].v_pointer = g_strdup (""); |
| } |
| </programlisting></msgtext> |
| @value_free: Free any old contents that might be left in the |
| data array of the passed in @value. No resources may |
| remain allocated through the #GValue contents after |
| this function returns. E.g. for our above string type: |
| <msgtext><programlisting> |
| { |
| /* 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); |
| } |
| </programlisting></msgtext> |
| @value_copy: @dest_value is a #GValue with zero-filled data section |
| and @src_value is a properly setup #GValue of same 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: |
| <msgtext><programlisting> |
| { |
| dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); |
| } |
| </programlisting></msgtext> |
| @value_peek_pointer: 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: |
| <msgtext><programlisting> |
| { |
| return value->data[0].v_pointer; |
| } |
| </programlisting></msgtext> |
| @collect_format: A string format describing how to collect the contents of |
| this value, bit-by-bit. Each character in the format represents |
| an argument to be collected, the characters themselves indicate |
| the type of the argument. Currently supported arguments are: |
| <msgtext><variablelist> |
| <varlistentry><term></term><listitem><para> |
| 'i' - Integers. passed as collect_values[].v_int. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 'l' - Longs. passed as collect_values[].v_long. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 'd' - Doubles. passed as collect_values[].v_double. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 'p' - Pointers. passed as collect_values[].v_pointer. |
| </para></listitem></varlistentry> |
| </variablelist></msgtext> |
| It should be noted, that for variable argument list construction, |
| ANSI C promotes every type smaller than an integer to an int, and |
| floats to doubles. So for collection of short int or char, 'i' |
| needs to be used, and for collection of floats 'd'. |
| @collect_value: The collect_value() function is responsible for converting the |
| values collected from a variable argument list into contents |
| suitable for storage in a GValue. This function should setup |
| @value similar to value_init(), e.g. for a string value that |
| does not allow NULL pointers, it needs to either spew 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 @value_init it is guaranteed to not |
| contain any old contents that might need freeing. |
| @n_collect_values is exactly the string length of @collect_format, |
| and @collect_values is an array of unions #GTypeCValue with |
| length @n_collect_values, containing the collected values |
| according to @collect_format. |
| @collect_flags is an argument provided as a hint by the caller, |
| which may contain the flag #G_VALUE_NOCOPY_CONTENTS indicating, |
| that the collected value contents may be considered "static" |
| for the duration of the #@value lifetime. |
| 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: |
| <msgtext><programlisting> |
| { |
| 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; |
| } |
| </programlisting></msgtext> |
| It should be noted, that it is generally a bad idea to follow the |
| #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to |
| reentrancy requirements and reference count assertions performed |
| by the GSignal code, reference counts should always be incremented |
| for reference counted contents stored in the value->data array. |
| To deviate from our string example for a moment, and taking a look |
| at an exemplary implementation for collect_value() of #GObject: |
| <msgtext><programlisting> |
| { |
| if (collect_values[0].v_pointer) |
| { |
| GObject *object = G_OBJECT (collect_values[0].v_pointer); |
| |
| /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */ |
| value->data[0].v_pointer = g_object_ref (object); |
| return NULL; |
| } |
| else |
| return g_strdup_printf ("Object passed as invalid NULL pointer"); |
| } |
| </programlisting></msgtext> |
| 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 |
| a malicious condition occurred, collect_value() may spew an |
| error by returning a newly allocated non-NULL string, giving |
| a suitable description of the error condition. |
| 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 condition so further |
| program behaviour is undefined. |
| @lcopy_format: Format description of the arguments to collect for @lcopy_value, |
| analogous to @collect_format. Usually, @lcopy_format string consists |
| only of 'p's to provide lcopy_value() with pointers to storage locations. |
| @lcopy_value: This function is responsible for storing the @value contents into |
| arguments passed through a variable argument list which got |
| collected into @collect_values according to @lcopy_format. |
| @n_collect_values equals the string length of @lcopy_format, |
| and @collect_flags may contain #G_VALUE_NOCOPY_CONTENTS. |
| In contrast to collect_value(), lcopy_value() is obliged to |
| always properly support #G_VALUE_NOCOPY_CONTENTS. |
| Similar to collect_value() the function may prematurely abort |
| by returning a newly allocated string describing an error condition. |
| To complete the string example: |
| <msgtext><programlisting> |
| { |
| gchar **string_p = collect_values[0].v_pointer; |
| |
| if (!string_p) |
| return g_strdup_printf ("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); |
| |
| } |
| </programlisting></msgtext> |
| And an exemplary version of lcopy_value() for |
| reference-counted types: |
| <msgtext><programlisting> |
| { |
| GObject **object_p = collect_values[0].v_pointer; |
| |
| if (!object_p) |
| return g_strdup_printf ("object location passed as NULL"); |
| if (!value->data[0].v_pointer) |
| *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; |
| } |
| </programlisting></msgtext> |
| |
| <!-- ##### MACRO G_TYPE_FROM_INSTANCE ##### --> |
| <para> |
| Returns the type identifier from a given @instance structure. |
| </para> |
| |
| @instance: Location of a valid #GTypeInstance structure. |
| |
| |
| <!-- ##### MACRO G_TYPE_FROM_CLASS ##### --> |
| <para> |
| Returns the type identifier from a given @class structure. |
| </para> |
| |
| @g_class: Location of a valid #GTypeClass structure. |
| |
| |
| <!-- ##### MACRO G_TYPE_FROM_INTERFACE ##### --> |
| <para> |
| Returns the type identifier from a given @interface structure. |
| </para> |
| |
| @g_iface: Location of a valid #GTypeInterface structure. |
| |
| |
| <!-- ##### MACRO G_TYPE_INSTANCE_GET_CLASS ##### --> |
| <para> |
| Returns the class structure of a given @instance, casted |
| to a specified anchestor type @g_type of the instance. |
| </para> |
| |
| @instance: Location of the #GTypeInstance structure. |
| @g_type: The anchestor type of the class to be returned. |
| @c_type: The corresponding C type of @g_Type. |
| |
| |
| <!-- ##### MACRO G_TYPE_INSTANCE_GET_INTERFACE ##### --> |
| <para> |
| |
| </para> |
| |
| @instance: |
| @g_type: |
| @c_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### --> |
| <para> |
| |
| </para> |
| |
| @instance: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_INSTANCE_CAST ##### --> |
| <para> |
| |
| </para> |
| |
| @instance: |
| @g_type: |
| @c_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_INSTANCE_TYPE ##### --> |
| <para> |
| |
| </para> |
| |
| @instance: |
| @g_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_CLASS_CAST ##### --> |
| <para> |
| |
| </para> |
| |
| @g_class: |
| @g_type: |
| @c_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_CLASS_TYPE ##### --> |
| <para> |
| |
| </para> |
| |
| @g_class: |
| @g_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_VALUE ##### --> |
| <para> |
| |
| </para> |
| |
| @value: |
| |
| |
| <!-- ##### MACRO G_TYPE_CHECK_VALUE_TYPE ##### --> |
| <para> |
| |
| </para> |
| |
| @value: |
| @g_type: |
| |
| |
| <!-- ##### MACRO G_TYPE_FLAG_RESERVED_ID_BIT ##### --> |
| <para> |
| |
| </para> |
| |
| |
| |
| <!-- ##### FUNCTION g_type_init ##### --> |
| <para> |
| Prior to any use of the type system, g_type_init() has to be called to initialize |
| the type system and assorted other code portions (such as the various fundamental |
| type implementations or the signal system). |
| </para> |
| |
| <!-- # Unused Parameters # --> |
| @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. |
| |
| |
| <!-- ##### FUNCTION g_type_init_with_debug_flags ##### --> |
| <para> |
| |
| </para> |
| |
| @debug_flags: |
| |
| |
| <!-- ##### FUNCTION g_type_name ##### --> |
| <para> |
| Return the unique name that is assigned to a type ID (this is the preferred method |
| to find out whether a specific type has been registered for the passed in ID yet). |
| </para> |
| |
| @type: Type to return name for. |
| @Returns: Static type name or NULL. |
| |
| |
| <!-- ##### FUNCTION g_type_qname ##### --> |
| <para> |
| Return the corresponding quark of the type IDs name. |
| </para> |
| |
| @type: Type to return quark of type name for. |
| @Returns: The type names quark or 0. |
| |
| |
| <!-- ##### FUNCTION g_type_from_name ##### --> |
| <para> |
| Lookup the type ID from a given type name, returns 0 if no type has been registered under this name |
| (this is the preferred method to find out by name whether a specific type has been registered yet). |
| </para> |
| |
| @name: Type name to lookup. |
| @Returns: Corresponding type ID or 0. |
| |
| |
| <!-- ##### FUNCTION g_type_parent ##### --> |
| <para> |
| Return the direct parent type of the passed in type. |
| If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. |
| </para> |
| |
| @type: The derived type. |
| @Returns: The parent type. |
| |
| |
| <!-- ##### FUNCTION g_type_depth ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_next_base ##### --> |
| <para> |
| Given a @leaf_type and a @root_type which is contained in its anchestry, return |
| the type that @root_type is the immediate parent of. |
| In other words, this function determines the type that is derived directly from |
| @root_type which is also a base class of @leaf_type. Given a root type and a |
| leaf type, this function can be used to determine the types and order in which |
| the leaf type is descended from the root type. |
| </para> |
| |
| @leaf_type: Descendant of @root_type and the type to be returned. |
| @root_type: Immediate parent of the returned type. |
| @Returns: Immediate child of @root_type and anchestor of @leaf_type. |
| |
| |
| <!-- ##### FUNCTION g_type_is_a ##### --> |
| <para> |
| Check whether @type is a descendant of @is_a_type. |
| </para> |
| |
| @type: Type to check anchestry for. |
| @is_a_type: Possible anchestor of @type. |
| @Returns: %TRUE if @type is_a @is_a_type holds true. |
| |
| |
| <!-- ##### FUNCTION g_type_fundamental_branch_last ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_class_ref ##### --> |
| <para> |
| Increments the reference count of the class structure belonging to |
| @type. This function will demand-create the class if it doesn't |
| exist already. |
| </para> |
| |
| @type: Type ID of a classed type. |
| @Returns: The #GTypeClass structure for the given type ID. |
| |
| |
| <!-- ##### FUNCTION g_type_class_peek ##### --> |
| <para> |
| This function is essentially the same as g_type_class_ref(), except that |
| the classes reference count isn't incremented. Therefore, this function |
| may return NULL if the class of the type passed in does not currently |
| exist (hasn't been referenced before). |
| </para> |
| |
| @type: Type ID of a classed type. |
| @Returns: The #GTypeClass structure for the given type ID or NULL |
| if the class does not currently exist. |
| |
| |
| <!-- ##### FUNCTION g_type_class_unref ##### --> |
| <para> |
| Decrements the reference count of the class structure being passed in. |
| Once the last reference count of a class has been released, classes |
| may be finalized by the type system, so further dereferencing of a |
| class pointer after g_type_class_unref() are invalid. |
| </para> |
| |
| @g_class: The #GTypeClass structure to unreference. |
| |
| |
| <!-- ##### FUNCTION g_type_class_peek_parent ##### --> |
| <para> |
| This is a convenience function, often needed in class intializers. |
| It essentially takes the immediate parent type of the class passed in, |
| and returns the class structure thereof. Since derived classes hold |
| a reference count on their parent classes as long as they are instantiated, |
| the returned class will always exist. This function is essentially |
| equivalent to: |
| |
| <msgtext><programlisting> |
| g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); |
| </programlisting></msgtext> |
| |
| </para> |
| |
| @g_class: The #GTypeClass structure to retrieve the parent class for. |
| @Returns: The parent class of @g_class. |
| |
| |
| <!-- ##### FUNCTION g_type_interface_peek ##### --> |
| <para> |
| |
| </para> |
| |
| @instance_class: |
| @iface_type: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_interface_peek_parent ##### --> |
| <para> |
| |
| </para> |
| |
| @g_iface: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_children ##### --> |
| <para> |
| Return a newly allocated and 0 terminated array of type IDs, listing the |
| child types of @type. The return value has to be g_free()ed after use. |
| </para> |
| |
| @type: The parent type. |
| @n_children: Optional #guint pointer to contain the number of child types. |
| @Returns: Newly allocated and 0 terminated array of child types. |
| |
| |
| <!-- ##### FUNCTION g_type_interfaces ##### --> |
| <para> |
| Return a newly allocated and 0 terminated array of type IDs, listing the |
| interface types that @type conforms to. The return value has to be |
| g_free()ed after use. |
| </para> |
| |
| @type: The type to list interface types for. |
| @n_interfaces: Optional #guint pointer to contain the number of interface types. |
| @Returns: Newly allocated and 0 terminated array of interface types. |
| |
| |
| <!-- ##### FUNCTION g_type_set_qdata ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| @quark: |
| @data: |
| |
| |
| <!-- ##### FUNCTION g_type_get_qdata ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| @quark: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_query ##### --> |
| <para> |
| |
| </para> |
| |
| @type: |
| @query: |
| |
| |
| <!-- ##### USER_FUNCTION GBaseInitFunc ##### --> |
| <para> |
| A callback function used by the type system to do base initialization |
| of the class structures of derived types. It 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. |
| Therefore class members, e.g. 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 |
| intialization process. |
| </para> |
| |
| @g_class: The #GTypeClass structure to initialize. |
| |
| |
| <!-- ##### USER_FUNCTION GBaseFinalizeFunc ##### --> |
| <para> |
| 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 intialization is performed. |
| See GClassInitFunc() for a discussion of the class intialization process. |
| </para> |
| |
| @g_class: The #GTypeClass structure to finalize. |
| |
| |
| <!-- ##### USER_FUNCTION GClassInitFunc ##### --> |
| <para> |
| 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: |
| <variablelist> |
| <varlistentry><term></term><listitem><para> |
| 1 - Copying common members from the parent class over to the |
| derived class structure. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 2 - Zero initialization of the remaining members not copied |
| over from the parent class. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 3 - Invocation of the GBaseInitFunc initializers of all parent |
| types and the class' type. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| 4 - Invocation of the class' GClassInitFunc initializer. |
| </para></listitem></varlistentry> |
| </variablelist> |
| 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 intializing 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 |
| are performed for class intialization of derived types as well. |
| An example may help to correspond the intend of the different class |
| initializers: |
| |
| <msgtext><programlisting> |
| 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; |
| } |
| </programlisting></msgtext> |
| Initialization of TypeBClass will first cause initialization of |
| TypeAClass (derived classes reference their parent classes, see |
| g_type_class_ref() on this). |
| Initialization of TypeAClass roughly involves zero-initializing its fields, |
| then calling its GBaseInitFunc() type_a_base_class_init() that allocates |
| 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. |
| </para> |
| |
| @g_class: The #GTypeClass structure to initialize. |
| @class_data: The @class_data member supplied via the #GTypeInfo structure. |
| |
| |
| <!-- ##### USER_FUNCTION GClassFinalizeFunc ##### --> |
| <para> |
| 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). |
| </para> |
| |
| @g_class: The #GTypeClass structure to finalize. |
| @class_data: The @class_data member supplied via the #GTypeInfo structure. |
| |
| |
| <!-- ##### USER_FUNCTION GInstanceInitFunc ##### --> |
| <para> |
| 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, therefore 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. |
| </para> |
| |
| @instance: The instance to initialize. |
| @g_class: The class of the type the instance is created for. |
| |
| |
| <!-- ##### USER_FUNCTION GInterfaceInitFunc ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @g_iface: The interface structure to initialize. |
| @iface_data: The @class_data supplied via the #GTypeInfo structure. |
| |
| |
| <!-- ##### USER_FUNCTION GInterfaceFinalizeFunc ##### --> |
| <para> |
| 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 GInterfaceInitFunc() function. |
| </para> |
| |
| @g_iface: The interface structure to finalize. |
| @iface_data: The @class_data supplied via the #GTypeInfo structure. |
| |
| |
| <!-- ##### USER_FUNCTION GTypeClassCacheFunc ##### --> |
| <para> |
| |
| </para> |
| |
| @cache_data: |
| @g_class: |
| @Returns: |
| |
| |
| <!-- ##### ENUM GTypeFlags ##### --> |
| <para> |
| Bit masks used to check or determine characteristics of a type. |
| </para> |
| |
| @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be |
| created for an abstract type. |
| @G_TYPE_FLAG_VALUE_ABSTRACT: |
| |
| <!-- ##### ENUM GTypeFundamentalFlags ##### --> |
| <para> |
| Bit masks used to check or determine specific characteristics of a |
| fundamental type. |
| </para> |
| |
| @G_TYPE_FLAG_CLASSED: Indicates a classed type. |
| @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). |
| @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. |
| @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). |
| |
| <!-- ##### FUNCTION g_type_register_static ##### --> |
| <para> |
| Registers @type_name as the name of a new static type derived from |
| @parent_type. The type system uses the information contained in the |
| #GTypeInfo structure pointed to by @info to manage the type and its |
| instances (if not abstract). The value of @flags determines the nature |
| (e.g. abstract or not) of the type. |
| </para> |
| |
| @parent_type: Type which this type will be derived from. |
| @type_name: Null-terminated string used as the name of the new type. |
| @info: The #GTypeInfo structure for this type. |
| @flags: Bitwise combination of #GTypeFlags values. |
| @Returns: The new type identifier. |
| |
| |
| <!-- ##### FUNCTION g_type_register_dynamic ##### --> |
| <para> |
| Registers @type_name as the name of a new dynamic type derived from |
| @parent_type. The type system uses the information contained in the |
| #GTypePlugin structure pointed to by @plugin to manage the type and its |
| instances (if not abstract). The value of @flags determines the nature |
| (e.g. abstract or not) of the type. |
| </para> |
| |
| @parent_type: Type which this type will be derived from. |
| @type_name: Null-terminated string used as the name of the new type. |
| @plugin: The #GTypePlugin structure to retrive the #GTypeInfo from. |
| @flags: Bitwise combination of #GTypeFlags values. |
| @Returns: The new type identifier. |
| <!-- # Unused Parameters # --> |
| @Returns: #G_TYPE_INVALID if registration failed or the new type identifier. |
| |
| |
| <!-- ##### FUNCTION g_type_register_fundamental ##### --> |
| <para> |
| Registers @type_id as the predefined identifier and @type_name as the |
| name of a fundamental type. The type system uses the information |
| contained in the #GTypeInfo structure pointed to by @info and the |
| #GTypeFundamentalInfo structure pointed to by @finfo to manage the |
| type and its instances. The value of @flags determines additional |
| characteristics of the fundamental type. |
| </para> |
| |
| @type_id: A predefined #GTypeFundamentals value. |
| @type_name: Null-terminated string used as the name of the new type. |
| @info: The #GTypeInfo structure for this type. |
| @finfo: The #GTypeFundamentalInfo structure for this type. |
| @flags: Bitwise combination of #GTypeFlags values. |
| @Returns: The predefined type identifier. |
| |
| |
| <!-- ##### FUNCTION g_type_add_interface_static ##### --> |
| <para> |
| Adds the static @interface_type to @instantiable_type. The information |
| contained in the #GTypeInterfaceInfo structure pointed to by @info |
| is used to manage the relationship. |
| </para> |
| |
| @instance_type: #GType value of an instantiable type. |
| @interface_type: #GType value of an interface type. |
| @info: The #GInterfaceInfo structure for this |
| (@instance_type, @interface_type) combination. |
| |
| |
| <!-- ##### FUNCTION g_type_add_interface_dynamic ##### --> |
| <para> |
| </para> |
| |
| @instance_type: |
| @interface_type: |
| @plugin: |
| |
| |
| <!-- ##### FUNCTION g_type_interface_add_prerequisite ##### --> |
| <para> |
| |
| </para> |
| |
| @interface_type: |
| @prerequisite_type: |
| |
| |
| <!-- ##### FUNCTION g_type_get_plugin ##### --> |
| <para> |
| Returns the the #GTypePlugin structure for @type or |
| #NULL if @type does not have a #GTypePlugin structure. |
| </para> |
| |
| @type: The #GType to retrive the plugin for. |
| @Returns: The corresponding plugin if @type is a dynamic type, |
| NULL otherwise. |
| |
| |
| <!-- ##### FUNCTION g_type_interface_get_plugin ##### --> |
| <para> |
| </para> |
| |
| @instance_type: |
| @implementation_type: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_type_fundamental_last ##### --> |
| <para> |
| Returns the last fundamental type which is registered plus one, |
| i.e. the next fundamental type ID that may be registered. |
| </para> |
| |
| @Returns: The nextmost not registered fundamental type ID. |
| |
| |
| <!-- ##### FUNCTION g_type_create_instance ##### --> |
| <para> |
| Creates and initializes an instance of @type if @type is valid and can |
| be instantiated. The type system only performs basic allocation and |
| structure setups for instances, actual instance creation should happen |
| through functions supplied by the types fundamental type implementation. |
| So use of g_type_create_instance() is reserved for implementators of |
| fundamental types only. E.g. instances of the #GObject hierarchy |
| should be created via g_object_new() and <emphasis>never</emphasis> |
| directly through g_type_create_instance() which doesn't handle |
| things like singleton objects or object construction. |
| Note: Do <emphasis>not</emphasis> use this function, unless you're |
| implementing a fundamental type. Also language bindings should <emphasis>not</emphasis> |
| use this function but g_object_new() instead. |
| </para> |
| |
| @type: An instantiabtable type to create an instance for. |
| @Returns: An allocated and initialized instance, subject to further |
| treatment by the fundamental type implementation. |
| |
| |
| <!-- ##### FUNCTION g_type_free_instance ##### --> |
| <para> |
| </para> |
| |
| @instance: |
| |
| |
| <!-- ##### FUNCTION g_type_add_class_cache_func ##### --> |
| <para> |
| |
| </para> |
| |
| @cache_data: |
| @cache_func: |
| |
| |
| <!-- ##### FUNCTION g_type_remove_class_cache_func ##### --> |
| <para> |
| |
| </para> |
| |
| @cache_data: |
| @cache_func: |
| |
| |
| <!-- ##### FUNCTION g_type_class_unref_uncached ##### --> |
| <para> |
| |
| </para> |
| |
| @g_class: |
| |
| |
| <!-- ##### FUNCTION g_type_value_table_peek ##### --> |
| <para> |
| Returns the location of the #GTypeValueTable associated with @type. |
| <emphasis>Note, this function should only be used from source code |
| that implements or has internal knowledge of the implementation of |
| @type.</emphasis> |
| </para> |
| |
| @type: A #GType value. |
| @Returns: Location of the #GTypeValueTable associated with @type or |
| #NULL if there is no #GTypeValueTable associated with @type. |
| |
| |