gtype.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

@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.


<!-- ##### ENUM GTypeDebugFlags ##### -->
<para>

</para>

@G_TYPE_DEBUG_NONE: 
@G_TYPE_DEBUG_OBJECTS: 
@G_TYPE_DEBUG_SIGNALS: 
@G_TYPE_DEBUG_MASK: 

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


<!-- ##### STRUCT GTypeQuery ##### -->
<para>

</para>

@type: 
@type_name: 
@class_size: 
@instance_size: 

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