gtype.sgml

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

This macro should only be used in type implementations.
</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 ancestor type @g_type of the instance.
</para>
<warning><para>Note
that while calling a GInstanceInitFunc(), the class pointer gets
modified, so it might not always return the expected pointer.
</para></warning>
<para>
This macro should only be used in type implementations.
</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>
Returns the interface structure for interface @g_type of a given @instance.
<para>
</para>
This macro should only be used in type implementations.
</para>

@instance: Location of the #GTypeInstance structure.
@g_type: The interface type to be returned.
@c_type: The corresponding C type of @g_type.


<!-- ##### MACRO G_TYPE_INSTANCE_GET_PRIVATE ##### -->
<para>
Gets the private structure for a particular type.
The private structure must have been registered in the
class_init function with g_type_class_add_private().
</para>
<para>
This macro should only be used in type implementations.
</para>

@instance: the instance of a type deriving from @private_type.
@g_type: the type identifying which private data to retrieve.
@c_type: The C type for the private structure.
@Since: 2.4


<!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### -->
<para>
Returns %TRUE if @instance is a valid #GTypeInstance structure,
otherwise emits a warning and returns %FALSE.
<para>
</para>
This macro should only be used in type implementations.
</para>

@instance: Location of a #GTypeInstance structure.


<!-- ##### MACRO G_TYPE_CHECK_INSTANCE_CAST ##### -->
<para>
Checks that @instance is an instance of the type identified by @g_type
and emits a warning if this is not the case. Returns @instance casted 
to a pointer to @c_type.
</para>
<para>
This macro should only be used in type implementations.
</para>

@instance: Location of a #GTypeInstance structure.
@g_type: The type to be returned.
@c_type: The corresponding C type of @g_type.


<!-- ##### MACRO G_TYPE_CHECK_INSTANCE_TYPE ##### -->
<para>
Returns %TRUE if @instance is an instance of the type identified by @g_type.
Otherwise emits a warning and returns %FALSE.
</para>
<para>
This macro should only be used in type implementations.
</para>

@instance: Location of a #GTypeInstance structure.
@g_type: The type to be checked


<!-- ##### MACRO G_TYPE_CHECK_CLASS_CAST ##### -->
<para>
Checks that @g_class is a class structure of the type identified by @g_type
and emits a warning if this is not the case. Returns @g_class casted 
to a pointer to @c_type.
</para>
<para>
This macro should only be used in type implementations.
</para>

@g_class: Location of a #GTypeClass structure.
@g_type: The type to be returned.
@c_type: The corresponding C type of class structure of @g_type.


<!-- ##### MACRO G_TYPE_CHECK_CLASS_TYPE ##### -->
<para>
Returns %TRUE if @g_class is a class structure of the type identified by 
@g_type. Otherwise emits a warning and returns %FALSE.
</para>
<para>
This macro should only be used in type implementations.
</para>

@g_class: Location of a #GTypeClass structure.
@g_type: The type to be checked.


<!-- ##### MACRO G_TYPE_CHECK_VALUE ##### -->
<para>
Returns %TRUE if @value has been initialized to hold values
of a value type.
</para>
<para>
This macro should only be used in type implementations.
</para>

@value: a #GValue


<!-- ##### MACRO G_TYPE_CHECK_VALUE_TYPE ##### -->
<para>
Returns %TRUE if @value has been initialized to hold values
of type @g_type. 
</para>
<para>
This macro should only be used in type implementations.
</para>

@value: a #GValue
@g_type: The type to be checked.


<!-- ##### MACRO G_TYPE_FLAG_RESERVED_ID_BIT ##### -->
<para>
A bit in the type number that's supposed to be left untouched.
</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>



<!-- ##### ENUM GTypeDebugFlags ##### -->
<para>
The <type>GTypeDebugFlags</type> enumeration values can be passed to
g_type_init_with_debug_flags() to trigger debugging messages during runtime.
Note that the messages can also be triggered by setting the
<envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of 
"objects" and "signals".

</para>

@G_TYPE_DEBUG_NONE: Print no messages.
@G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
@G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
@G_TYPE_DEBUG_MASK: Mask covering all debug flags.

<!-- ##### FUNCTION g_type_init_with_debug_flags ##### -->
<para>
Similar to g_type_init(), but additionally sets debug flags.
</para>

@debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes.


<!-- ##### FUNCTION g_type_name ##### -->
<para>
    Returns the unique name that is assigned to a type ID.
    Note that this function (like all other GType API) cannot cope with invalid
    type IDs. %G_TYPE_INVALID may be passed to this function, as may be any other
    validly registered type ID, but randomized type IDs should not be passed in and
    will most likely lead to a crash.
</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, returning 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>
Returns the length of the ancestry of the passed in type. This includes the
type itself, so that e.g. a fundamental type has depth 1.
</para>

@type:    A #GType value.
@Returns: The depth of @type.


<!-- ##### 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>
If @is_a_type is a derivable type, check whether @type is a descendant of @is_a_type.
If @is_a_type is an interface, check whether @type conforms to it.
</para>

@type:      Type to check anchestry for.
@is_a_type: Possible anchestor of @type or interface @type could conform to.
@Returns:   %TRUE if @type is_a @is_a_type holds true.


<!-- ##### 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. As a consequence, 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_peek_static ##### -->
<para>
A more efficient version of g_type_class_peek() which works only for
static types.
</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 or is dynamically loaded.
@Since: 2.4


<!-- ##### 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 initializers.
It returns the class structure of the immediate parent type of the class passed in.
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:

<programlisting>
g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
</programlisting>

</para>

@g_class: The #GTypeClass structure to retrieve the parent class for.
@Returns: The parent class of @g_class.


<!-- ##### FUNCTION g_type_class_add_private ##### -->
<para>
Registers a private structure for a instantiatable type;
when an object is allocated, the private structures for
the type and and all of its parent types are allocated
sequentially in the same memory block as the public
structures. This function should be called in the
type's class_init() function. The private structure can
be retrieved using the G_TYPE_INSTANCE_GET_PRIVATE() macro.
The following example shows attaching a private structure
<structname>MyObjectPrivate</structname> to an object
<structname>MyObject</structname> defined in the standard GObject
fashion.
</para>
<programlisting>
typedef struct _MyObjectPrivate MyObjectPrivate;

struct _MyObjectPrivate {
  int some_field;
};

&num;define MY_OBJECT_GET_PRIVATE(o)  \
   (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate))

static void
my_object_class_init (MyObjectClass *klass)
{
  g_type_class_add_private (klass, sizeof (MyObjectPrivate));
}

static int
my_object_get_some_field (MyObject *my_object)
{
  MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object);

  return priv->some_field;
}
</programlisting>

@g_class: class structure for an instantiatable type
@private_size: size of private structure.
@Since: 2.4


<!-- ##### FUNCTION g_type_interface_peek ##### -->
<para>
Returns the #GTypeInterface structure of an interface to which the passed in 
class conforms.
</para>

@instance_class: A #GTypeClass structure.
@iface_type:     An interface ID which this class conforms to.
@Returns:        The GTypeInterface structure of iface_type if implemented 
                 by @instance_class, %NULL otherwise


<!-- ##### FUNCTION g_type_interface_peek_parent ##### -->
<para>
Returns the corresponding #GTypeInterface structure of the parent type
of the instance type to which @g_iface belongs. This is useful when 
deriving the implementation of an interface from the parent type and 
then possibly overriding some methods. 
</para>

@g_iface: A #GTypeInterface structure.
@Returns: The corresponding #GTypeInterface structure of the parent type
   of the instance type to which @g_iface belongs, or %NULL if the parent type
   doesn't conform to the interface.


<!-- ##### FUNCTION g_type_default_interface_ref ##### -->
<para>
Increments the reference count for the interface type @g_type,
and returns the default interface vtable for the type.
</para>
<para>  
If the type is not currently in use, then the default vtable
for the type will be created and initalized by calling
the base interface init and default vtable init functions for
the type (the @<structfield>base_init</structfield>
and <structfield>class_init</structfield> members of #GTypeInfo).
Calling g_type_default_interface_ref() is useful when you
want to make sure that signals and properties for an interface
have been installed.
</para>

@g_type: an interface type
@Returns: the default vtable for the interface; call 
 g_type_default_interface_unref() when you are done using
 the interface.
@Since: 2.4


<!-- ##### FUNCTION g_type_default_interface_peek ##### -->
<para>
If the interface type @g_type is currently in use, returns
its default interface vtable.    
</para>

@g_type: an interface type
@Returns: the default vtable for the interface, or %NULL
 if the type is not currently in use.
@Since: 2.4


<!-- ##### FUNCTION g_type_default_interface_unref ##### -->
<para>
Decrements the reference count for the type corresponding to the
interface default vtable @g_iface. If the type is dynamic, then
when no one is using the interface and all references have
been released, the finalize function for the interface's default
vtable (the <structfield>class_finalize</structfield> member of
#GTypeInfo) will be called.
</para>

@g_iface: the default vtable structure for a interface, as
  returned by g_type_default_interface_ref()
@Since: 2.4


<!-- ##### 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>