gtype.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

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_interface_prerequisites ##### -->
<para>
Returns the prerequisites of an interfaces type.
</para>

@interface_type: an interface type
@n_prerequisites: location to return the number of prerequisites, or %NULL
@Returns: a newly-allocated zero-terminated array of #GType containing 
   the prerequisites of @interface_type
@Since: 2.2


<!-- ##### FUNCTION g_type_set_qdata ##### -->
<para>
Attaches arbitrary data to a type.
</para>

@type: a #GType
@quark: a #GQuark id to identify the data
@data: the data


<!-- ##### FUNCTION g_type_get_qdata ##### -->
<para>
Obtains data which has previously been attached to @type
with g_type_set_qdata().
</para>

@type: a #GType
@quark: a #GQuark id to identify the data
@Returns: the data, or %NULL if no data was found


<!-- ##### FUNCTION g_type_query ##### -->
<para>
Queries the type system for information about a specific type. 
This function will fill in a user-provided structure to hold type-specific 
information. If an invalid #GType is passed in, the @type member of the 
#GTypeQuery is 0. All members filled into the #GTypeQuery structure should
be considered constant and have to be left untouched.
</para>

@type: the #GType value of a static, classed type.
@query: A user provided structure that is filled in with constant values 
        upon success.


<!-- ##### STRUCT GTypeQuery ##### -->
<para>
A structure holding information for a specific type. It is
filled in by the g_type_query() function.
</para>

@type: the #GType value of the type.
@type_name: the name of the type.
@class_size: the size of the class structure.
@instance_size: the size of the instance structure.

<!-- ##### 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.
For example, class members (such as strings) that are not sufficiently
handled by a plain memory copy of the parent class into the derived class
have to be altered. See GClassInitFunc() for a discussion of the class
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 initializing static
class members, while dynamic class members (such as allocated strings
or reference counted resources) are better handled by a GBaseInitFunc()
for this type, so proper initialization of the dynamic class members
is performed for class initialization of derived types as well.
An example may help to correspond the intend of the different class
initializers:

<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>
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() to allocate
its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
type_a_class_init() to initialize its static members (static_integer).
The first step in the initialization process of TypeBClass is then
a plain memory copy of the contents of TypeAClass into TypeBClass and 
zero-initialization of the remaining fields in TypeBClass.
The dynamic members of TypeAClass within TypeBClass now need
reinitialization which is performed by calling type_a_base_class_init()
with an argument of TypeBClass.
After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
is called to complete the initialization process with the static members
(static_float).
Corresponding finalization counter parts to the GBaseInitFunc() functions
have to be provided to release allocated resources at class finalization
time.
</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, so the class member of the instance
is altered during its initialization to always point to the class that
belongs to the type the current initializer was introduced for.
</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>
A callback function which is called when the reference count of a class 
drops to zero. It may use g_type_class_ref() to prevent the class from
being freed. You should not call g_type_class_unref() from a 
#GTypeClassCacheFunc function to prevent infinite recursion, use 
g_type_class_unref_uncached() instead.
</para>
<para>
The functions have to check the class id passed in to figure 
whether they actually want to cache the class of this type, since all
classes are routed through the same #GTypeClassCacheFunc chain.
</para>

@cache_data: data that was given to the g_type_add_class_cache_func() call
@g_class: The #GTypeClass structure which is unreferenced
@Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being 
called, %FALSE to continue.


<!-- ##### 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: Indicates an abstract value type, i.e. a type
                        that introduces a value table, but can't be used for
                        g_value_init().

<!-- ##### 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 from which this type will be derived.
@type_name: 	0-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_static_simple ##### -->
<para>
Registers @type_name as the name of a new static type derived from
@parent_type.  The value of @flags determines the nature (e.g. 
abstract or not) of the type. It works by filling a #GTypeInfo 
struct and calling g_type_register_static().
</para>

@parent_type: 	Type from which this type will be derived.
@type_name: 	0-terminated string used as the name of the new type.
@class_size:    Size of the class structure (see #GTypeInfo)
@class_init: 	Location of the class initialization function (see #GTypeInfo)
@instance_size: Size of the instance structure (see #GTypeInfo)
@instance_init: Location of the instance initialization function (see #GTypeInfo)
@flags: 	Bitwise combination of #GTypeFlags values.
@Returns: 	The new type identifier.
@Since:         2.12


<!-- ##### 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 from which this type will be derived.
@type_name: 	0-terminated string used as the name of the new type.
@plugin: 	The #GTypePlugin structure to retrieve the #GTypeInfo from.
@flags: 		Bitwise combination of #GTypeFlags values.
@Returns: 	The new type identifier or #G_TYPE_INVALID if registration failed.


<!-- ##### 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: 	0-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>
Adds the dynamic @interface_type to @instantiable_type. The information
contained in the #GTypePlugin structure pointed to by @plugin
is used to manage the relationship.
</para>

@instance_type: the #GType value of an instantiable type.
@interface_type: the #GType value of an interface type.
@plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from.


<!-- ##### FUNCTION g_type_interface_add_prerequisite ##### -->
<para>
Adds @prerequisite_type to the list of prerequisites of @interface_type.
This means that any type implementing @interface_type must also implement
@prerequisite_type. Prerequisites can be thought of as an alternative to
interface derivation (which GType doesn't support). An interface can have
at most one instantiatable prerequisite type.
</para>

@interface_type: #GType value of an interface type.
@prerequisite_type: #GType value of an interface or instantiatable type.


<!-- ##### FUNCTION g_type_get_plugin ##### -->
<para>
Returns the #GTypePlugin structure for @type or
%NULL if @type does not have a #GTypePlugin structure.
</para>

@type: 		The #GType to retrieve the plugin for.
@Returns: 	The corresponding plugin if @type is a dynamic type,
		%NULL otherwise.


<!-- ##### FUNCTION g_type_interface_get_plugin ##### -->
<para>
Returns the #GTypePlugin structure for the dynamic interface 
@interface_type which has been added to @instance_type, or 
%NULL if @interface_type has not been added to @instance_type or does 
not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
</para>

@instance_type: the #GType value of an instantiatable type.
@interface_type: the #GType value of an interface type.
@Returns: the #GTypePlugin for the dynamic interface @interface_type
   of @instance_type.


<!-- ##### FUNCTION g_type_fundamental_next ##### -->
<para>
Returns the next free fundamental type id which can be used to
register a new fundamental type with g_type_register_fundamental().
The returned type ID represents the highest currently registered
fundamental type identifier.

</para>

@Returns: The nextmost fundamental type ID to be registered,
          or 0 if the type system ran out of fundamental type IDs.


<!-- ##### FUNCTION g_type_fundamental ##### -->
<para>
Internal function, used to extract the fundamental type ID portion.
use G_TYPE_FUNDAMENTAL() instead.
</para>

@type_id: valid type ID
@Returns: 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 type's 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