gtype.sgml

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

<!-- ##### 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 retrieved 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>
<para>
A final word about type names.
Such an identifier needs to be at least three characters long. There is no
upper length limit. The first character needs to be a letter (a-z or A-Z)
or an underscore '_'. Subsequent characters can be letters, numbers or
any of '-_+'.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### TYPEDEF GType ##### -->
<para>
A numerical value which represents the unique identifier of a registered
type.
</para>


<!-- ##### MACRO G_TYPE_FUNDAMENTAL ##### -->
<para>
Returns the fundamental type which is the ancestor of @type.
Fundamental types are types that serve as ultimate bases 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_MAKE_FUNDAMENTAL ##### -->
<para>
Returns the type ID for the fundamental type number @x.
Use g_type_fundamental_next() instead of this macro to create new fundamental 
types.
</para>

@x: the fundamental type number.


<!-- ##### 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>
Returns %TRUE if @type is a value type and can be used with
g_value_init(). 
</para>

@type: A #GType value.


<!-- ##### MACRO G_TYPE_HAS_VALUE_TABLE ##### -->
<para>
Returns %TRUE if @type has a #GTypeValueTable.
</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.
An interface type provides a pure API, 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, 
with the difference that GType interfaces are not derivable (but see
g_type_interface_add_prerequisite() for an alternative).
</para>

@type: A #GType value.


<!-- ##### 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 GTypeClass ##### -->
<para>
An opaque structure used as the base of all classes.
</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
its instances.
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 its 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 for
  classed and types. Location of the default vtable inititalization
  function for interface types. (optional) This function is used both
  to fill in virtual functions in the class or default vtable, and
  to do type-specific setup such as registering signals and object
  properties.
@class_finalize: Location of the class finalization function for
  classed and types. Location fo the default vtable finalization
  function for interface types. (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: 	 Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
@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 (usually 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: #GTypeFundamentalFlags describing the characteristics of the fundamental type

<!-- ##### 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 interface initialization function
@interface_finalize: location of the interface finalization function
@interface_data: user-supplied data passed to the interface init/finalize functions

<!-- ##### 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-&gt;data array. The data array of
			the #GValue passed into this function was zero-filled
			with <function>memset()</function>, 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:
<programlisting>
{
  value-&gt;data[0].v_pointer = g_strdup ("");
}
</programlisting>
@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:
<programlisting>
{
  /* only free strings without a specific flag for static storage */
  if (!(value-&gt;data[1].v_uint &amp; G_VALUE_NOCOPY_CONTENTS))
    g_free (value-&gt;data[0].v_pointer);
}
</programlisting>
@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:
<programlisting>
{
  dest_value-&gt;data[0].v_pointer = g_strdup (src_value-&gt;data[0].v_pointer);
}
</programlisting>
@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:
<programlisting>
{
  return value-&gt;data[0].v_pointer;
}
</programlisting>
@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, and the characters themselves indicate
			the type of the argument. Currently supported arguments are:
<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>
			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.
			It 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:
<programlisting>
{
  if (!collect_values[0].v_pointer)
    value->data[0].v_pointer = g_strdup ("");
  else if (collect_flags &amp; G_VALUE_NOCOPY_CONTENTS)
    {
      value-&gt;data[0].v_pointer = collect_values[0].v_pointer;
      /* keep a flag for the value_free() implementation to not free this string */
      value-&gt;data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
    }
  else
    value-&gt;data[0].v_pointer = g_strdup (collect_values[0].v_pointer);

  return NULL;
}
</programlisting>
			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-&gt;data array.
			To deviate from our string example for a moment, and taking a look
			at an exemplary implementation for collect_value() of #GObject:
<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-&gt;data[0].v_pointer = g_object_ref (object);
      return NULL;
    }
  else
    return g_strdup_printf ("Object passed as invalid NULL pointer");
}
</programlisting>
			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,
			an error 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:
<programlisting>
{
  gchar **string_p = collect_values[0].v_pointer;

  if (!string_p)
    return g_strdup_printf ("string location passed as NULL");

  if (collect_flags &amp; G_VALUE_NOCOPY_CONTENTS)
    *string_p = value-&gt;data[0].v_pointer;
  else
    *string_p = g_strdup (value-&gt;data[0].v_pointer);

}
</programlisting>
			And an illustrative version of lcopy_value() for
			reference-counted types:
<programlisting>
{
  GObject **object_p = collect_values[0].v_pointer;

  if (!object_p)
    return g_strdup_printf ("object location passed as NULL");
  if (!value-&gt;data[0].v_pointer)
    *object_p = NULL;
  else if (collect_flags &amp; G_VALUE_NOCOPY_CONTENTS) /* always honour */
    *object_p = value-&gt;data[0].v_pointer;
  else
    *object_p = g_object_ref (value-&gt;data[0].v_pointer);
  return NULL;
}
</programlisting>

<!-- ##### MACRO G_TYPE_FROM_INSTANCE ##### -->
<para>
Returns the type identifier from a given @instance structure. 
<para>
</para>
This macro should only be used in type implementations.
</para>

@instance: Location of a valid #GTypeInstance structure.


<!-- ##### MACRO G_TYPE_FROM_CLASS ##### -->
<para>
Returns the type identifier from a given @class structure.
<para>
</para>
This macro should only be used in type implementations.
</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>
</para>