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 ##### -->
<!-- ##### 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 heirachies.
</para>
-@type:
+@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_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>
-<!-- ##### ENUM GTypeFundamentals ##### -->
+<!-- ##### 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>
-@G_TYPE_INVALID:
-@G_TYPE_NONE:
-@G_TYPE_INTERFACE:
-@G_TYPE_CHAR:
-@G_TYPE_UCHAR:
-@G_TYPE_BOOLEAN:
-@G_TYPE_INT:
-@G_TYPE_UINT:
-@G_TYPE_LONG:
-@G_TYPE_ULONG:
-@G_TYPE_ENUM:
-@G_TYPE_FLAGS:
-@G_TYPE_FLOAT:
-@G_TYPE_DOUBLE:
-@G_TYPE_STRING:
-@G_TYPE_PARAM:
-@G_TYPE_BOXED:
-@G_TYPE_POINTER:
-@G_TYPE_OBJECT:
-@G_TYPE_GTK_SIGNAL:
-@G_TYPE_BSE_PROCEDURE:
-@G_TYPE_BSE_TIME:
-@G_TYPE_BSE_NOTE:
-@G_TYPE_BSE_DOTS:
-@G_TYPE_GLE_GOBJECT:
-@G_TYPE_LAST_RESERVED_FUNDAMENTAL:
-@G_TYPE_PARAM_CHAR:
-@G_TYPE_PARAM_UCHAR:
-@G_TYPE_PARAM_BOOLEAN:
-@G_TYPE_PARAM_INT:
-@G_TYPE_PARAM_UINT:
-@G_TYPE_PARAM_LONG:
-@G_TYPE_PARAM_ULONG:
-@G_TYPE_PARAM_ENUM:
-@G_TYPE_PARAM_FLAGS:
-@G_TYPE_PARAM_FLOAT:
-@G_TYPE_PARAM_DOUBLE:
-@G_TYPE_PARAM_STRING:
-@G_TYPE_PARAM_OBJECT:
+@type: A #GType value.
-<!-- ##### MACRO G_TYPE_IS_CLASSED ##### -->
-<para>
+<!-- ##### MACRO G_TYPE_IS_DERIVED ##### -->
+<para>
+Returns #TRUE if @type is derived (or in object-oriented terminolgy:
+inherited) from another type (this holds true for all non-fundamental
+types).
</para>
-@type:
+@type: A #GType value.
-<!-- ##### MACRO G_TYPE_IS_INSTANTIATABLE ##### -->
+<!-- ##### MACRO G_TYPE_IS_FUNDAMENTAL ##### -->
<para>
-
+Returns #TRUE if @type is a fundamental type.
</para>
-@type:
+@type: A #GType value.
-<!-- ##### MACRO G_TYPE_IS_DERIVABLE ##### -->
+<!-- ##### MACRO G_TYPE_IS_VALUE_TYPE ##### -->
<para>
</para>
-@type:
+@type: A #GType value.
-<!-- ##### MACRO G_TYPE_IS_DEEP_DERIVABLE ##### -->
+<!-- ##### MACRO G_TYPE_IS_CLASSED ##### -->
<para>
-
+Returns #TRUE if @type is a classed type.
</para>
-@type:
+@type: A #GType value.
-<!-- ##### MACRO G_TYPE_IS_INTERFACE ##### -->
+<!-- ##### 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:
+@type: A #GType value.
-<!-- ##### STRUCT GTypePlugin ##### -->
+<!-- ##### 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>
-@vtable:
+@type: A #GType value.
+
-<!-- ##### STRUCT GTypePluginVTable ##### -->
+<!-- ##### 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>
-@plugin_ref:
-@plugin_unref:
-@complete_type_info:
-@complete_interface_info:
+@type: A #GType value.
-<!-- ##### STRUCT GTypeInterface ##### -->
+
+<!-- ##### 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_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_PARAM: Identifier for the "#GParam" type.
+@G_TYPE_BOXED: Identifier for the "#GBoxed" type.
+@G_TYPE_POINTER: Identifier for anonymous pointers "void*".
+@G_TYPE_CCALLBACK: Identifier for a pointer to a C function.
+@G_TYPE_OBJECT: Identifier for the "#GObject" type.
+@G_TYPE_GTK_SIGNAL: Reserved for use by the Gtk+ software package.
+@G_TYPE_BSE_PROCEDURE: Reserved for use by the BSE software package.
+@G_TYPE_BSE_TIME: Reserved for use by the BSE software package.
+@G_TYPE_BSE_NOTE: Reserved for use by the BSE software package.
+@G_TYPE_BSE_DOTS: Reserved for use by the BSE software package.
+@G_TYPE_GLE_GOBJECT: Reserved for use by the GLE software package.
+@G_TYPE_LAST_RESERVED_FUNDAMENTAL: New third-party fundamental types have to use IDs higher than this.
+@G_TYPE_PARAM_CHAR: Identifier for the "#GParamSpecChar" type.
+@G_TYPE_PARAM_UCHAR: Identifier for the "#GParamSpecUChar" type.
+@G_TYPE_PARAM_BOOLEAN: Identifier for the "#GParamSpecBoolean" type.
+@G_TYPE_PARAM_INT: Identifier for the "#GParamSpecInt" type.
+@G_TYPE_PARAM_UINT: Identifier for the "#GParamSpecUInt" type.
+@G_TYPE_PARAM_LONG: Identifier for the "#GParamSpecLong" type.
+@G_TYPE_PARAM_ULONG: Identifier for the "#GParamSpecULong" type.
+@G_TYPE_PARAM_ENUM: Identifier for the "#GParamSpecEnum" type.
+@G_TYPE_PARAM_FLAGS: Identifier for the "#GParamSpecFlags" type.
+@G_TYPE_PARAM_FLOAT: Identifier for the "#GParamSpecFloat" type.
+@G_TYPE_PARAM_DOUBLE: Identifier for the "#GParamSpecDouble" type.
+@G_TYPE_PARAM_STRING: Identifier for the "#GParamSpecString" type.
+@G_TYPE_PARAM_PARAM: Identifier for the "#GParamSpecParam" type.
+@G_TYPE_PARAM_POINTER: Identifier for the "#GParamSpecPointer" type.
+@G_TYPE_PARAM_CCALLBACK: Identifier for the "#GParamSpecCCallback" type.
+@G_TYPE_PARAM_BOXED: Identifier for the "#GParamSpecBoxed" type.
+@G_TYPE_PARAM_OBJECT: Identifier for the "#GParamSpecObject" type.
+<!-- ##### 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>
-
-</para>
-
-@class_size:
-@base_init:
-@base_finalize:
-@class_init:
-@class_finalize:
-@class_data:
-@instance_size:
-@n_preallocs:
-@instance_init:
-@value_table:
+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: Function table for generic handling of GValues of this type (usualy only usefull 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:
-@interface_finalize:
-@interface_data:
+@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>
@value_free:
@value_copy:
@value_peek_pointer:
-@collect_type:
+@collect_format:
@collect_value:
-@lcopy_type:
+@lcopy_format:
@lcopy_value:
-<!-- ##### MACRO G_TYPE_CHECK_INSTANCE_CAST ##### -->
+<!-- ##### 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>
@c_type:
-<!-- ##### MACRO G_TYPE_CHECK_CLASS_CAST ##### -->
+<!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### -->
<para>
</para>
-@g_class:
+@instance:
+
+
+<!-- ##### MACRO G_TYPE_CHECK_INSTANCE_CAST ##### -->
+<para>
+
+</para>
+
+@instance:
@g_type:
@c_type:
@g_type:
-<!-- ##### MACRO G_TYPE_CHECK_CLASS_TYPE ##### -->
+<!-- ##### MACRO G_TYPE_CHECK_CLASS_CAST ##### -->
<para>
</para>
@g_class:
@g_type:
+@c_type:
-<!-- ##### MACRO G_TYPE_INSTANCE_GET_CLASS ##### -->
+<!-- ##### MACRO G_TYPE_CHECK_CLASS_TYPE ##### -->
<para>
</para>
-@instance:
+@g_class:
@g_type:
-@c_type:
-<!-- ##### MACRO G_TYPE_FROM_INSTANCE ##### -->
+<!-- ##### MACRO G_TYPE_CHECK_VALUE ##### -->
<para>
</para>
-@instance:
+@value:
-<!-- ##### MACRO G_TYPE_FROM_CLASS ##### -->
+<!-- ##### MACRO G_TYPE_CHECK_VALUE_TYPE ##### -->
<para>
</para>
-@g_class:
+@value:
+@g_type:
-<!-- ##### MACRO G_TYPE_FROM_INTERFACE ##### -->
+<!-- ##### MACRO G_TYPE_FLAG_RESERVED_ID_BIT ##### -->
<para>
</para>
-@g_iface:
<!-- ##### 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>
+@debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes.
<!-- ##### 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:
-@Returns:
+@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:
-@Returns:
+@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:
-@Returns:
+@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:
-@Returns:
+@type: The derived type.
+@Returns: The parent type.
<!-- ##### FUNCTION g_type_next_base ##### -->
<para>
-
+Given a @type and a @base_type which is contained in its anchestry, return
+the type that @base_type is the direct parent type for.
+In other words, for a given type branch, e.g. Root-Derived1-Derived2-Leaf, specified
+through @type=Leaf, return the nextmost child of @base_type. In this example, for
+@base_type=Derived1, the returned value would be Derived2, for @base_type=Root, the
+returned value would be Derived1.
</para>
-@type:
-@base_type:
-@Returns:
+@type: Descendant of @base_type and the type to be returned.
+@base_type: Direct parent of the returned type.
+@Returns: Immediate child of @base_type and anchestor of @type.
<!-- ##### FUNCTION g_type_is_a ##### -->
<para>
-
+Check whether @type is a descendant of @is_a_type.
</para>
-@type:
-@is_a_type:
-@Returns:
-
-
-<!-- ##### FUNCTION g_type_conforms_to ##### -->
-<para>
-
-</para>
-
-@type:
-@iface_type:
-@Returns:
+@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 ##### -->
<!-- ##### 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:
-@Returns:
+@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:
-@Returns:
+@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:
+@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:
-@Returns:
+@g_class: The #GTypeClass structure to retrive the parent class for.
+@Returns: The parent class of @g_class.
<!-- ##### FUNCTION g_type_interface_peek ##### -->
<!-- ##### 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:
-@n_children:
-@Returns:
+@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:
-@n_interfaces:
-@Returns:
+@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 ##### -->
<!-- ##### 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:
+@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:
+@g_class: The #GTypeClass structure to finalize.
<!-- ##### USER_FUNCTION GClassInitFunc ##### -->
<para>
-
-</para>
-
-@g_class:
-@class_data:
+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 corrsepond 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-intializing 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 intialization 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:
-@class_data:
+@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 require 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:
-@g_class:
+@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:
-@iface_data:
+@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:
-@iface_data:
+@g_iface: The interface structure to finalize.
+@iface_data: The @class_data supplied via the #GTypeInfo structure.
-<!-- ##### USER_FUNCTION GTypePluginRef ##### -->
+<!-- ##### USER_FUNCTION GTypeClassCacheFunc ##### -->
<para>
</para>
-@plugin:
+@cache_data:
+@g_class:
+@Returns:
-<!-- ##### USER_FUNCTION GTypePluginUnRef ##### -->
+<!-- ##### ENUM GTypeFlags ##### -->
<para>
-
+Bit masks used to check or determine characteristics of a type.
</para>
-@plugin:
-
+@G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be
+ created for an abstract type.
-<!-- ##### USER_FUNCTION GTypePluginFillTypeInfo ##### -->
+<!-- ##### ENUM GTypeFundamentalFlags ##### -->
<para>
-
+Bit masks used to check or determine specific characteristics of a
+fundamental type.
</para>
-@plugin:
-@g_type:
-@info:
-@value_table:
+@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).
-
-<!-- ##### USER_FUNCTION GTypePluginFillInterfaceInfo ##### -->
+<!-- ##### 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>
-@plugin:
-@interface_type:
-@instance_type:
-@info:
+@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.
-<!-- ##### USER_FUNCTION GTypeClassCacheFunc ##### -->
+<!-- ##### 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>
-@cache_data:
-@g_class:
-@Returns:
+@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.
-<!-- ##### ENUM GTypeFlags ##### -->
+<!-- ##### 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 funamental type.
</para>
-@G_TYPE_FLAG_ABSTRACT:
+@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_register_static ##### -->
-<para>
+<!-- ##### 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>
-@parent_type:
-@type_name:
-@info:
-@flags:
-@Returns:
+@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_register_dynamic ##### -->
+<!-- ##### FUNCTION g_type_add_interface_dynamic ##### -->
<para>
-
</para>
-@parent_type:
-@type_name:
+@instance_type:
+@interface_type:
@plugin:
-@flags:
-@Returns:
-<!-- ##### FUNCTION g_type_register_fundamental ##### -->
+<!-- ##### 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_id:
-@type_name:
-@info:
-@finfo:
-@flags:
-@Returns:
+@type: The #GType to retrive the plugin for.
+@Returns: The corresponding plugin if @type is a dynamic type,
+ NULL otherwise.
-<!-- ##### FUNCTION g_type_add_interface_static ##### -->
+<!-- ##### FUNCTION g_type_interface_get_plugin ##### -->
<para>
-
</para>
@instance_type:
-@interface_type:
-@info:
+@implementation_type:
+@Returns:
-<!-- ##### FUNCTION g_type_add_interface_dynamic ##### -->
+<!-- ##### 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>
-@instance_type:
-@interface_type:
-@plugin:
+@Returns: The nextmost not registered fundamental type ID.
-<!-- ##### FUNCTION g_type_class_is_a ##### -->
+<!-- ##### FUNCTION g_type_check_flags ##### -->
<para>
-
+Determines whether a given set of #GTypeFlags and #GTypeFundamentalFlags
+are set for @type.
</para>
-@g_class:
-@is_a_type:
-@Returns:
+@type: The type to check for flags.
+@flags: Bitwise combination of #GTypeFlags and #GTypeFundamentalFlags.
+@Returns: #TRUE if all @flags are set for @type, #FALSE otherwise.
-<!-- ##### FUNCTION g_type_check_class_cast ##### -->
+<!-- ##### 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, actuall 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 heirachy
+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.
</para>
-@g_class:
-@is_a_type:
-@Returns:
+@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_check_instance_cast ##### -->
+<!-- ##### FUNCTION g_type_free_instance ##### -->
<para>
-
</para>
@instance:
-@iface_type:
-@Returns:
-<!-- ##### FUNCTION g_type_instance_conforms_to ##### -->
+<!-- ##### FUNCTION g_type_add_class_cache_func ##### -->
<para>
</para>
-@instance:
-@iface_type:
-@Returns:
+@cache_data:
+@cache_func:
-<!-- ##### FUNCTION g_type_check_flags ##### -->
+<!-- ##### FUNCTION g_type_remove_class_cache_func ##### -->
<para>
</para>
-@type:
-@flags:
-@Returns:
+@cache_data:
+@cache_func:
-<!-- ##### FUNCTION g_type_create_instance ##### -->
+<!-- ##### FUNCTION g_type_class_unref_uncached ##### -->
<para>
</para>
-@type:
-@Returns:
+@g_class:
-<!-- ##### FUNCTION g_type_free_instance ##### -->
+<!-- ##### FUNCTION g_type_check_instance ##### -->
<para>
-
+Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE()
+macro.
</para>
-@instance:
+@instance: A valid #GTypeInstance structure.
+@Returns: #TRUE if @instance is valid, #FALSE otherwise.
-<!-- ##### FUNCTION g_type_value_table_peek ##### -->
+<!-- ##### FUNCTION g_type_check_instance_cast ##### -->
<para>
-
</para>
-@type:
+@instance:
+@iface_type:
@Returns:
-<!-- ##### FUNCTION g_type_add_class_cache_func ##### -->
+<!-- ##### FUNCTION g_type_instance_is_a ##### -->
<para>
-
+Determines if @instance adhears to the interface exported
+by @iface_type. @iface_type is eitehr a type that @instance
+is derived from, or an interface type that is suppoted by
+the anchestry of @instance.
</para>
-@cache_data:
-@cache_func:
+@instance: A valid #GTypeInstance structure.
+@iface_type: A #GType value.
+@Returns: #TRUE if @instance conforms to @iface_type, #FALSE otherwise.
-<!-- ##### FUNCTION g_type_remove_class_cache_func ##### -->
+<!-- ##### FUNCTION g_type_check_class_cast ##### -->
<para>
-
</para>
-@cache_data:
-@cache_func:
+@g_class:
+@is_a_type:
+@Returns:
-<!-- ##### FUNCTION g_type_class_unref_uncached ##### -->
+<!-- ##### FUNCTION g_type_class_is_a ##### -->
<para>
-
</para>
@g_class:
+@is_a_type:
+@Returns:
-<!-- ##### FUNCTION g_type_get_plugin ##### -->
+<!-- ##### FUNCTION g_type_check_value ##### -->
<para>
-
</para>
-@type:
+@value:
@Returns:
-<!-- ##### FUNCTION g_type_fundamental_last ##### -->
+<!-- ##### FUNCTION g_type_value_is_a ##### -->
<para>
+Determines if @value is a #GValue whose type conforms to @type.
+</para>
+
+@value: A valid #GValue structure.
+@type: A #GType value.
+@Returns: #TRUE if @value is a #GValue of @type or #FALSE if not.
+
+<!-- ##### 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>
-@Returns:
+@type: A #GType value.
+@Returns: Location of the #GTypeValueTable associated with @type or
+ #NULL if there is no #GTypeValueTable associated with @type.
projects / platform / upstream / glib.git / blobdiff