2008-06-21 Stefan Kost <ensonic@users.sf.net>
+ * docs/reference/gobject/tmpl/gtype.sgml:
+ * gobject/gtype.c:
+ * gobject/gtype.h:
+ * gobject/gvaluetypes.h:
+ Migrating docs.
+
+2008-06-21 Stefan Kost <ensonic@users.sf.net>
+
* gobject/gclosure.h:
* gobject/gparam.h:
Add one missing ':' and reformate GParamFlags docs.
+++ /dev/null
-<!-- ##### 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 instantiatable 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 instantiatable 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->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->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->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
- g_free (value->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->data[0].v_pointer = g_strdup (src_value->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->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 & G_VALUE_NOCOPY_CONTENTS)
- {
- value->data[0].v_pointer = collect_values[0].v_pointer;
- /* keep a flag for the value_free() implementation to not free this string */
- value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
- }
- else
- value->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->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->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 & G_VALUE_NOCOPY_CONTENTS)
- *string_p = value->data[0].v_pointer;
- else
- *string_p = g_strdup (value->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->data[0].v_pointer)
- *object_p = NULL;
- else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */
- *object_p = value->data[0].v_pointer;
- else
- *object_p = g_object_ref (value->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>
-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 #GType of the class to be returned.
-@c_type: The C type of the class structure.
-
-
-<!-- ##### 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 #GType of the interface to be returned.
-@c_type: The C type of the interface structure.
-
-
-<!-- ##### 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 issues 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 issues 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 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 issues 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 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 an instantiatable type;
-when an object is allocated, the private structures for
-the type 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;
-};
-
-#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>
-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 @interface_data supplied via the #GInterfaceInfo 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 @interface_data supplied via the #GInterfaceInfo 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 type identifier.
-@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
-implementing a fundamental type. Also language bindings should <emphasis>not</emphasis>
-use this function but g_object_new() instead.
-</para>
-
-@type: An instantiatable type to create an instance for.
-@Returns: An allocated and initialized instance, subject to further
- treatment by the fundamental type implementation.
-
-
-<!-- ##### FUNCTION g_type_free_instance ##### -->
-<para>
-Frees an instance of a type, returning it to the instance pool for the type,
-if there is one.
-</para>
-<para>
-Like g_type_create_instance(), this function is reserved for implementors of
-fundamental types.
-</para>
-
-@instance: an instance of a type.
-
-
-<!-- ##### FUNCTION g_type_add_class_cache_func ##### -->
-<para>
-Adds a #GTypeClassCacheFunc to be called before the reference count of a class
-goes from one to zero. This can be used to prevent premature class destruction.
-All installed #GTypeClassCacheFunc functions will be chained until one of them
-returns %TRUE. 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 to be passed to @cache_func
-@cache_func: a #GTypeClassCacheFunc
-
-
-<!-- ##### FUNCTION g_type_remove_class_cache_func ##### -->
-<para>
-Removes a previously installed #GTypeClassCacheFunc. The cache maintained
-by @cache_func has to be empty when calling g_type_remove_class_cache_func()
-to avoid leaks.
-</para>
-
-@cache_data: data that was given when adding @cache_func
-@cache_func: a #GTypeClassCacheFunc
-
-
-<!-- ##### FUNCTION g_type_class_unref_uncached ##### -->
-<para>
-A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
-implementations. It unreferences a class without consulting the chain
-of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur
-otherwise.
-</para>
-
-@g_class: The #GTypeClass structure to unreference.
-
-
-<!-- ##### FUNCTION g_type_add_interface_check ##### -->
-<para>
-Adds a function to be called after an interface vtable is
-initialized for any class (i.e. after the @interface_init
-member of #GInterfaceInfo has been called).
-</para>
-<para>
-This function is useful when you want to check an invariant
-that depends on the interfaces of a class. For instance,
-the implementation of #GObject uses this facility to check
-that an object implements all of the properties that are
-defined on its interfaces.
-</para>
-
-@check_data: data to pass to @check_func
-@check_func: function to be called after each interface
- is initialized.
-@Since: 2.4
-
-
-<!-- ##### FUNCTION g_type_remove_interface_check ##### -->
-<para>
-Removes an interface check function added with
-g_type_add_interface_check().
-</para>
-
-@check_data: callback data passed to g_type_add_interface_check()
-@check_func: callback function passed to g_type_add_interface_check()
-@Since: 2.4
-
-
-<!-- ##### USER_FUNCTION GTypeInterfaceCheckFunc ##### -->
-<para>
-A callback called after an interface vtable is initialized.
-See g_type_add_interface_check().
-</para>
-
-@check_data: data passed to g_type_add_interface_check().
-@g_iface: the interface that has been initialized
-@Since: 2.4
-
-
-<!-- ##### FUNCTION g_type_value_table_peek ##### -->
-<para>
-Returns the location of the #GTypeValueTable associated with @type.
-<emphasis>Note that this function should only be used from source code
-that implements or has internal knowledge of the implementation of
-@type.</emphasis>
-</para>
-
-@type: A #GType value.
-@Returns: Location of the #GTypeValueTable associated with @type or
- %NULL if there is no #GTypeValueTable associated with @type.
-
-
-<!-- ##### MACRO G_DEFINE_TYPE ##### -->
-<para>
-A convenience macro for type implementations, which declares a
-class initialization function, an instance initialization function (see #GTypeInfo for information about
-these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
-a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
-</para>
-
-@TN: The name of the new type, in Camel case.
-@t_n: The name of the new type, in lowercase, with words
- separated by '_'.
-@T_P: The #GType of the parent type.
-@Since: 2.4
-
-
-<!-- ##### MACRO G_DEFINE_TYPE_WITH_CODE ##### -->
-<para>
-A convenience macro for type implementations.
-Similar to G_DEFINE_TYPE(), but allows to insert custom code into the
-*_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
-See G_DEFINE_TYPE_EXTENDED() for an example.
-</para>
-
-@TN: The name of the new type, in Camel case.
-@t_n: The name of the new type in lowercase, with words separated by '_'.
-@T_P: The #GType of the parent type.
-@_C_: Custom code that gets inserted in the *_get_type() function.
-@Since: 2.4
-
-
-<!-- ##### MACRO G_DEFINE_ABSTRACT_TYPE ##### -->
-<para>
-A convenience macro for type implementations.
-Similar to G_DEFINE_TYPE(), but defines an abstract type.
-See G_DEFINE_TYPE_EXTENDED() for an example.
-</para>
-
-@TN: The name of the new type, in Camel case.
-@t_n: The name of the new type, in lowercase, with words
- separated by '_'.
-@T_P: The #GType of the parent type.
-@Since: 2.4
-
-
-<!-- ##### MACRO G_DEFINE_ABSTRACT_TYPE_WITH_CODE ##### -->
-<para>
-A convenience macro for type implementations.
-Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows to
-insert custom code into the *_get_type() function, e.g. interface implementations
-via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
-</para>
-
-@TN: The name of the new type, in Camel case.
-@t_n: The name of the new type, in lowercase, with words
- separated by '_'.
-@T_P: The #GType of the parent type.
-@_C_: Custom code that gets inserted in the @type_name_get_type() function.
-@Since: 2.4
-
-
-<!-- ##### MACRO G_IMPLEMENT_INTERFACE ##### -->
-<para>
-A convenience macro to ease interface addition in the @_C_ section
-of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
-See G_DEFINE_TYPE_EXTENDED() for an example.
-</para>
-<para>
-Note that this macro can only be used together with the G_DEFINE_TYPE_*
-macros, since it depends on variable names from those macros.
-</para>
-
-@TYPE_IFACE: The #GType of the interface to add
-@iface_init: The interface init function
-@Since: 2.4
-
-
-<!-- ##### MACRO G_DEFINE_TYPE_EXTENDED ##### -->
-<para>
-The most general convenience macro for type implementations, on which
-G_DEFINE_TYPE(), etc are based.
-</para>
-<informalexample><programlisting>
-G_DEFINE_TYPE_EXTENDED (GtkGadget,
- gtk_gadget,
- GTK_TYPE_WIDGET,
- 0,
- G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- gtk_gadget_gizmo_init));
-</programlisting>
-expands to
-<programlisting>
-static void gtk_gadget_init (GtkGadget *self);
-static void gtk_gadget_class_init (GtkGadgetClass *klass);
-static gpointer gtk_gadget_parent_class = NULL;
-static void gtk_gadget_class_intern_init (gpointer klass)
-{
- gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- gtk_gadget_class_init ((GtkGadgetClass*) klass);
-}
-<!-- -->
-GType
-gtk_gadget_get_type (void)
-{
- static GType g_define_type_id = 0;
- if (G_UNLIKELY (g_define_type_id == 0))
- {
- static const GTypeInfo g_define_type_info = {
- sizeof (GtkGadgetClass),
- (GBaseInitFunc) NULL,
- (GBaseFinalizeFunc) NULL,
- (GClassInitFunc) gtk_gadget_class_intern_init,
- (GClassFinalizeFunc) NULL,
- NULL, /* class_data */
- sizeof (GtkGadget),
- 0, /* n_preallocs */
- (GInstanceInitFunc) gtk_gadget_init,
- };
- g_define_type_id = g_type_register_static (GTK_TYPE_WIDGET, "GtkGadget", &g_define_type_info, 0);
- {
- static const GInterfaceInfo g_implement_interface_info = {
- (GInterfaceInitFunc) gtk_gadget_gizmo_init
- };
- g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- }
- }
- return g_define_type_id;
-}
-</programlisting>
-The only pieces which have to be manually provided are the definitions of the
-instance and class structure and the definitions of the instance and class
-init functions.
-</informalexample>
-
-@TN: The name of the new type, in Camel case.
-@t_n: The name of the new type, in lowercase, with words
- separated by '_'.
-@T_P: The #GType of the parent type.
-@_f_: #GTypeFlags to pass to g_type_register_static()
-@_C_: Custom code that gets inserted in the *_get_type() function.
-@Since: 2.4
-
-
-<!-- ##### MACRO G_TYPE_INVALID ##### -->
-<para>
-An invalid #GType used as error return value in some functions which return
-a #GType.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_NONE ##### -->
-<para>
-A fundamental type which is used as a replacement for the C
-<literal>void</literal> return type.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_INTERFACE ##### -->
-<para>
-The fundamental type from which all interfaces are derived.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_CHAR ##### -->
- <para>
- The fundamental type corresponding to #gchar.
- The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
- This may or may not be the same type a the C type "gchar".
- </para>
-
-
-
-<!-- ##### MACRO G_TYPE_UCHAR ##### -->
-<para>
-The fundamental type corresponding to #guchar.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_BOOLEAN ##### -->
-<para>
-The fundamental type corresponding to #gboolean.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_INT ##### -->
-<para>
-The fundamental type corresponding to #gint.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_UINT ##### -->
-<para>
-The fundamental type corresponding to #guint.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_LONG ##### -->
-<para>
-The fundamental type corresponding to #glong.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_ULONG ##### -->
-<para>
-The fundamental type corresponding to #gulong.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_INT64 ##### -->
-<para>
-The fundamental type corresponding to #gint64.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_UINT64 ##### -->
-<para>
-The fundamental type corresponding to #guint64.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_ENUM ##### -->
-<para>
-The fundamental type from which all enumeration types are derived.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_FLAGS ##### -->
-<para>
-The fundamental type from which all flags types are derived.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_FLOAT ##### -->
-<para>
-The fundamental type corresponding to #gfloat.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_DOUBLE ##### -->
-<para>
-The fundamental type corresponding to #gdouble.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_STRING ##### -->
-<para>
-The fundamental type corresponding to nul-terminated C strings.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_POINTER ##### -->
-<para>
-The fundamental type corresponding to #gpointer.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_BOXED ##### -->
-<para>
-The fundamental type from which all boxed types are derived.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_PARAM ##### -->
-<para>
-The fundamental type from which all #GParamSpec types are derived.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_OBJECT ##### -->
-<para>
-The fundamental type for #GObject.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_GTYPE ##### -->
-<para>
-The type for #GType.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_RESERVED_GLIB_FIRST ##### -->
-<para>
-First fundamental type number to create a new fundamental type id with
-G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_RESERVED_GLIB_LAST ##### -->
-<para>
-Last fundamental type number reserved for GLib.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_RESERVED_BSE_FIRST ##### -->
-<para>
-First fundamental type number to create a new fundamental type id with
-G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_RESERVED_BSE_LAST ##### -->
-<para>
-Last fundamental type number reserved for BSE.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_RESERVED_USER_FIRST ##### -->
-<para>
-First available fundamental type number to create new fundamental
-type id with G_TYPE_MAKE_FUNDAMENTAL().
-</para>
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gobject-docs.sgml" "book" "refsect2" "")
-End:
--->
-
-
-
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gtype
+ * @Short_description: The GLib Runtime type identification and management system
+ * @Title:Type Information
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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 '-_+'.
+ */
#include <config.h>
#include "gtype.h"
type_iface_add_prerequisite_W (lookup_type_node_I (dependants[i]), prerequisite_node);
}
+/**
+ * g_type_interface_add_prerequisite:
+ * @interface_type: #GType value of an interface type.
+ * @prerequisite_type: #GType value of an interface or instantiatable type.
+ *
+ * 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.
+ */
void
g_type_interface_add_prerequisite (GType interface_type,
GType prerequisite_type)
}
}
-GType* /* free result */
+/**
+ * g_type_interface_prerequisites:
+ * @interface_type: an interface type
+ * @n_prerequisites: location to return the number of prerequisites, or %NULL
+ *
+ * Returns the prerequisites of an interfaces type.
+ *
+ * Since: 2.2
+ * Returns: a newly-allocated zero-terminated array of #GType containing
+ * the prerequisites of @interface_type
+ */
+GType*
g_type_interface_prerequisites (GType interface_type,
guint *n_prerequisites)
{
return class;
}
+/**
+ * g_type_create_instance:
+ * @type: An instantiatable type to create an instance for.
+ *
+ * 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
+ * implementing a fundamental type. Also language bindings should <emphasis>not</emphasis>
+ * use this function but g_object_new() instead.
+ *
+ * Returns: An allocated and initialized instance, subject to further
+ * treatment by the fundamental type implementation.
+ */
GTypeInstance*
g_type_create_instance (GType type)
{
return instance;
}
+/**
+ * g_type_free_instance:
+ * @instance: an instance of a type.
+ *
+ * Frees an instance of a type, returning it to the instance pool for the type,
+ * if there is one.
+ *
+ * Like g_type_create_instance(), this function is reserved for implementors of
+ * fundamental types.
+ */
void
g_type_free_instance (GTypeInstance *instance)
{
}
}
+/**
+ * g_type_add_class_cache_func:
+ * @cache_data: data to be passed to @cache_func
+ * @cache_func: a #GTypeClassCacheFunc
+ *
+ * Adds a #GTypeClassCacheFunc to be called before the reference count of a
+ * class goes from one to zero. This can be used to prevent premature class
+ * destruction. All installed #GTypeClassCacheFunc functions will be chained
+ * until one of them returns %TRUE. 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.
+ */
void
g_type_add_class_cache_func (gpointer cache_data,
GTypeClassCacheFunc cache_func)
G_WRITE_UNLOCK (&type_rw_lock);
}
+/**
+ * g_type_remove_class_cache_func:
+ * @cache_data: data that was given when adding @cache_func
+ * @cache_func: a #GTypeClassCacheFunc
+ *
+ * Removes a previously installed #GTypeClassCacheFunc. The cache maintained
+ * by @cache_func has to be empty when calling g_type_remove_class_cache_func()
+ * to avoid leaks.
+ */
void
g_type_remove_class_cache_func (gpointer cache_data,
GTypeClassCacheFunc cache_func)
}
+/**
+ * g_type_add_interface_check:
+ * @check_data: data to pass to @check_func
+ * @check_func: function to be called after each interface
+ * is initialized.
+ *
+ * Adds a function to be called after an interface vtable is
+ * initialized for any class (i.e. after the @interface_init
+ * member of #GInterfaceInfo has been called).
+ *
+ * This function is useful when you want to check an invariant
+ * that depends on the interfaces of a class. For instance,
+ * the implementation of #GObject uses this facility to check
+ * that an object implements all of the properties that are
+ * defined on its interfaces.
+ *
+ * Since: 2.4
+ */
void
g_type_add_interface_check (gpointer check_data,
GTypeInterfaceCheckFunc check_func)
G_WRITE_UNLOCK (&type_rw_lock);
}
+/**
+ * g_type_remove_interface_check:
+ * @check_data: callback data passed to g_type_add_interface_check()
+ * @check_func: callback function passed to g_type_add_interface_check()
+ *
+ * Removes an interface check function added with
+ * g_type_add_interface_check().
+ *
+ * Since: 2.4
+ */
void
g_type_remove_interface_check (gpointer check_data,
GTypeInterfaceCheckFunc check_func)
}
/* --- type registration --- */
+/**
+ * g_type_register_fundamental:
+ * @type_id: A predefined type identifier.
+ * @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.
+ *
+ * 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.
+ *
+ * Returns: The predefined type identifier.
+ */
GType
g_type_register_fundamental (GType type_id,
const gchar *type_name,
return NODE_TYPE (node);
}
+/**
+ * g_type_register_static_simple:
+ * @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.
+ *
+ * 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().
+ *
+ * Since: 2.12
+ * Returns: The new type identifier.
+ */
GType
g_type_register_static_simple (GType parent_type,
const gchar *type_name,
return g_type_register_static (parent_type, type_name, &info, flags);
}
+/**
+ * g_type_register_static:
+ * @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.
+ *
+ * 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.
+ *
+ * Returns: The new type identifier.
+ */
GType
g_type_register_static (GType parent_type,
const gchar *type_name,
return type;
}
+/**
+ * g_type_register_dynamic:
+ * @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.
+ *
+ * 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.
+ *
+ * Returns: The new type identifier or #G_TYPE_INVALID if registration failed.
+ */
GType
g_type_register_dynamic (GType parent_type,
const gchar *type_name,
return type;
}
+/**
+ * g_type_add_interface_static:
+ * @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.
+ *
+ * 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.
+ */
void
g_type_add_interface_static (GType instance_type,
GType interface_type,
g_static_rec_mutex_unlock (&class_init_rec_mutex);
}
+/**
+ * g_type_add_interface_dynamic:
+ * @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.
+ *
+ * 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.
+ */
void
g_type_add_interface_dynamic (GType instance_type,
GType interface_type,
/* --- public API functions --- */
+/**
+ * g_type_class_ref:
+ * @type: Type ID of a classed type.
+ *
+ * Increments the reference count of the class structure belonging to
+ * @type. This function will demand-create the class if it doesn't
+ * exist already.
+ *
+ * Returns: The #GTypeClass structure for the given type ID.
+ */
gpointer
g_type_class_ref (GType type)
{
return node->data->class.class;
}
+/**
+ * g_type_class_unref:
+ * @g_class: The #GTypeClass structure to unreference.
+ *
+ * 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.
+ */
void
g_type_class_unref (gpointer g_class)
{
G_WRITE_UNLOCK (&type_rw_lock);
}
+/**
+ * g_type_class_unref_uncached:
+ * @g_class: The #GTypeClass structure to unreference.
+ *
+ * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
+ * implementations. It unreferences a class without consulting the chain
+ * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur
+ * otherwise.
+ */
void
g_type_class_unref_uncached (gpointer g_class)
{
G_WRITE_UNLOCK (&type_rw_lock);
}
+/**
+ * g_type_class_peek:
+ * @type: Type ID of a classed type.
+ *
+ * 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).
+ *
+ * Returns: The #GTypeClass structure for the given type ID or %NULL
+ * if the class does not currently exist.
+ */
gpointer
g_type_class_peek (GType type)
{
return class;
}
+/**
+ * g_type_class_peek_static:
+ * @type: Type ID of a classed type.
+ *
+ * A more efficient version of g_type_class_peek() which works only for
+ * static types.
+ *
+ * Since: 2.4
+ * Returns: The #GTypeClass structure for the given type ID or %NULL
+ * if the class does not currently exist or is dynamically loaded.
+ */
gpointer
g_type_class_peek_static (GType type)
{
return class;
}
+/**
+ * g_type_class_peek_parent:
+ * @g_class: The #GTypeClass structure to retrieve the parent class for.
+ *
+ * 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>
+ *
+ * Returns: The parent class of @g_class.
+ */
gpointer
g_type_class_peek_parent (gpointer g_class)
{
return class;
}
+/**
+ * g_type_interface_peek:
+ * @instance_class: A #GTypeClass structure.
+ * @iface_type: An interface ID which this class conforms to.
+ *
+ * Returns the #GTypeInterface structure of an interface to which the passed in
+ * class conforms.
+ *
+ * Returns: The GTypeInterface structure of iface_type if implemented
+ * by @instance_class, %NULL otherwise
+ */
gpointer
g_type_interface_peek (gpointer instance_class,
GType iface_type)
return vtable;
}
+/**
+ * g_type_interface_peek_parent:
+ * @g_iface: A #GTypeInterface structure.
+ *
+ * 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.
+ *
+ * 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.
+ */
gpointer
g_type_interface_peek_parent (gpointer g_iface)
{
return vtable;
}
+/**
+ * g_type_default_interface_ref:
+ * @g_type: an interface type
+ *
+ * Increments the reference count for the interface type @g_type,
+ * and returns the default interface vtable for the type.
+ *
+ * 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.
+ *
+ * Since: 2.4
+ * Returns: the default vtable for the interface; call
+ * g_type_default_interface_unref() when you are done using
+ * the interface.
+ */
gpointer
g_type_default_interface_ref (GType g_type)
{
return dflt_vtable;
}
+/**
+ * g_type_default_interface_peek:
+ * @g_type: an interface type
+ *
+ * If the interface type @g_type is currently in use, returns
+ * its default interface vtable.
+ *
+ * Since: 2.4
+ * Returns: the default vtable for the interface, or %NULL
+ * if the type is not currently in use.
+ */
gpointer
g_type_default_interface_peek (GType g_type)
{
return vtable;
}
+/**
+ * g_type_default_interface_unref:
+ * @g_iface: the default vtable structure for a interface, as
+ * returned by g_type_default_interface_ref()
+ *
+ * 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.
+ *
+ * Since: 2.4
+ */
void
g_type_default_interface_unref (gpointer g_iface)
{
G_WRITE_UNLOCK (&type_rw_lock);
}
+/**
+ * g_type_name:
+ * @type: Type to return name for.
+ *
+ * Get 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.
+ *
+ * Returns: Static type name or %NULL.
+ */
G_CONST_RETURN gchar*
g_type_name (GType type)
{
return node ? NODE_NAME (node) : NULL;
}
+/**
+ * g_type_qname:
+ * @type: Type to return quark of type name for.
+ *
+ * Get the corresponding quark of the type IDs name.
+ *
+ * Returns: The type names quark or 0.
+ */
GQuark
g_type_qname (GType type)
{
return node ? node->qname : 0;
}
+/**
+ * g_type_from_name:
+ * @name: Type name to lookup.
+ *
+ * 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).
+ *
+ * Returns: Corresponding type ID or 0.
+ */
GType
g_type_from_name (const gchar *name)
{
return type;
}
+/**
+ * g_type_parent:
+ * @type: The derived type.
+ *
+ * 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.
+ *
+ * Returns: The parent type.
+ */
GType
g_type_parent (GType type)
{
return node ? NODE_PARENT_TYPE (node) : 0;
}
+/**
+ * g_type_depth:
+ * @type: A #GType value.
+ *
+ * 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.
+ *
+ * Returns: The depth of @type.
+ */
guint
g_type_depth (GType type)
{
return node ? node->n_supers + 1 : 0;
}
+/**
+ * g_type_next_base:
+ * @leaf_type: Descendant of @root_type and the type to be returned.
+ * @root_type: Immediate parent of the returned type.
+ *
+ * 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.
+ *
+ * Returns: Immediate child of @root_type and anchestor of @leaf_type.
+ */
GType
g_type_next_base (GType type,
GType base_type)
return type_node_check_conformities_UorL (node, iface_node, support_interfaces, support_prerequisites, FALSE);
}
+/**
+ * g_type_is_a:
+ * @type: Type to check anchestry for.
+ * @is_a_type: Possible anchestor of @type or interface @type could conform to.
+ *
+ * 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.
+ *
+ * Returns: %TRUE if @type is_a @is_a_type holds true.
+ */
gboolean
g_type_is_a (GType type,
GType iface_type)
return is_a;
}
-GType* /* free result */
+/**
+ * g_type_children:
+ * @type: The parent type.
+ * @n_children: Optional #guint pointer to contain the number of child types.
+ *
+ * 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.
+ *
+ * Returns: Newly allocated and 0-terminated array of child types.
+ */
+GType*
g_type_children (GType type,
guint *n_children)
{
}
}
-GType* /* free result */
+/**
+ * g_type_interfaces:
+ * @type: The type to list interface types for.
+ * @n_interfaces: Optional #guint pointer to contain the number of interface types.
+ *
+ * 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.
+ *
+ * Returns: Newly allocated and 0-terminated array of interface types.
+ */
+GType*
g_type_interfaces (GType type,
guint *n_interfaces)
{
return NULL;
}
+/**
+ * g_type_get_qdata:
+ * @type: a #GType
+ * @quark: a #GQuark id to identify the data
+ *
+ * Obtains data which has previously been attached to @type
+ * with g_type_set_qdata().
+ *
+ * Returns: the data, or %NULL if no data was found
+ */
gpointer
g_type_get_qdata (GType type,
GQuark quark)
qdata[i].data = data;
}
+/**
+ * g_type_set_qdata:
+ * @type: a #GType
+ * @quark: a #GQuark id to identify the data
+ * @data: the data
+ *
+ * Attaches arbitrary data to a type.
+ */
void
g_type_set_qdata (GType type,
GQuark quark,
type_set_qdata_W (node, static_quark_type_flags, GUINT_TO_POINTER (dflags));
}
+/**
+ * g_type_query:
+ * @type: the #GType value of a static, classed type.
+ * @query: A user provided structure that is filled in with constant values
+ * upon success.
+ *
+ * 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.
+ */
void
g_type_query (GType type,
GTypeQuery *query)
return result;
}
+/**
+ * g_type_get_plugin:
+ * @type: The #GType to retrieve the plugin for.
+ *
+ * Returns the #GTypePlugin structure for @type or
+ * %NULL if @type does not have a #GTypePlugin structure.
+ *
+ * Returns: The corresponding plugin if @type is a dynamic type,
+ * %NULL otherwise.
+ */
GTypePlugin*
g_type_get_plugin (GType type)
{
return node ? node->plugin : NULL;
}
+/**
+ * g_type_interface_get_plugin:
+ * @instance_type: the #GType value of an instantiatable type.
+ * @interface_type: the #GType value of an interface type.
+ *
+ * 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().
+ *
+ * Returns: the #GTypePlugin for the dynamic interface @interface_type
+ * of @instance_type.
+ */
GTypePlugin*
g_type_interface_get_plugin (GType instance_type,
GType interface_type)
return NULL;
}
+/**
+ * g_type_fundamental_next:
+ *
+ * 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.
+ *
+ * Returns: The nextmost fundamental type ID to be registered,
+ * or 0 if the type system ran out of fundamental type IDs.
+ */
GType
g_type_fundamental_next (void)
{
return type <= G_TYPE_FUNDAMENTAL_MAX ? type : 0;
}
+/**
+ * g_type_fundamental:
+ * @type_id: valid type ID
+ *
+ * Internal function, used to extract the fundamental type ID portion.
+ * use G_TYPE_FUNDAMENTAL() instead.
+ *
+ * Returns: fundamental type ID
+ */
GType
g_type_fundamental (GType type_id)
{
return value && type_check_is_value_type_U (value->g_type) && g_type_is_a (value->g_type, type);
}
+/**
+ * g_type_value_table_peek:
+ * @type: A #GType value.
+ *
+ * Returns the location of the #GTypeValueTable associated with @type.
+ * <emphasis>Note that this function should only be used from source code
+ * that implements or has internal knowledge of the implementation of
+ * @type.</emphasis>
+ *
+ * Returns: Location of the #GTypeValueTable associated with @type or
+ * %NULL if there is no #GTypeValueTable associated with @type.
+ */
GTypeValueTable*
g_type_value_table_peek (GType type)
{
/* --- initialization --- */
+/**
+ * g_type_init_with_debug_flags:
+ * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes.
+ *
+ * Similar to g_type_init(), but additionally sets debug flags.
+ */
void
g_type_init_with_debug_flags (GTypeDebugFlags debug_flags)
{
G_UNLOCK (type_init_lock);
}
+/**
+ * g_type_init:
+ *
+ * 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).
+ */
void
g_type_init (void)
{
g_type_init_with_debug_flags (0);
}
+/**
+ * g_type_class_add_private:
+ * @g_class: class structure for an instantiatable type
+ * @private_size: size of private structure.
+ *
+ * Registers a private structure for an instantiatable type;
+ * when an object is allocated, the private structures for
+ * the type 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.
+ *
+ * |[
+ * typedef struct _MyObjectPrivate MyObjectPrivate;
+ *
+ * struct _MyObjectPrivate {
+ * int some_field;
+ * };
+ *
+ * #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;
+ * }
+ * ]|
+ *
+ * Since: 2.4
+ */
void
g_type_class_add_private (gpointer g_class,
gsize private_size)
/* Basic Type Macros
*/
+/**
+ * G_TYPE_FUNDAMENTAL:
+ * @type: A #GType value.
+ *
+ * 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.
+ */
#define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type))
+/**
+ * G_TYPE_FUNDAMENTAL_MAX:
+ *
+ * An integer constant that represents the number of identifiers reserved
+ * for types that are assigned at compile-time.
+ */
#define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT)
/* Constant fundamental types,
* introduced by g_type_init().
*/
+/**
+ * G_TYPE_INVALID:
+ *
+ * An invalid #GType used as error return value in some functions which return
+ * a #GType.
+ */
#define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0)
+/**
+ * G_TYPE_NONE:
+ *
+ * A fundamental type which is used as a replacement for the C
+ * <literal>void</literal> return type.
+ */
#define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1)
+/**
+ * G_TYPE_INTERFACE:
+ *
+ * The fundamental type from which all interfaces are derived.
+ */
#define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2)
+/**
+ * G_TYPE_CHAR:
+ *
+ * The fundamental type corresponding to #gchar.
+ * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
+ * This may or may not be the same type a the C type "gchar".
+ */
#define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3)
+/**
+ * G_TYPE_UCHAR:
+ *
+ * The fundamental type corresponding to #guchar.
+ */
#define G_TYPE_UCHAR G_TYPE_MAKE_FUNDAMENTAL (4)
+/**
+ * G_TYPE_BOOLEAN:
+ *
+ * The fundamental type corresponding to #gboolean.
+ */
#define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5)
+/**
+ * G_TYPE_INT:
+ *
+ * The fundamental type corresponding to #gint.
+ */
#define G_TYPE_INT G_TYPE_MAKE_FUNDAMENTAL (6)
+/**
+ * G_TYPE_UINT:
+ *
+ * The fundamental type corresponding to #guint.
+ */
#define G_TYPE_UINT G_TYPE_MAKE_FUNDAMENTAL (7)
+/**
+ * G_TYPE_LONG:
+ *
+ * The fundamental type corresponding to #glong.
+ */
#define G_TYPE_LONG G_TYPE_MAKE_FUNDAMENTAL (8)
+/**
+ * G_TYPE_ULONG:
+ *
+ * The fundamental type corresponding to #gulong.
+ */
#define G_TYPE_ULONG G_TYPE_MAKE_FUNDAMENTAL (9)
+/**
+ * G_TYPE_INT64:
+ *
+ * The fundamental type corresponding to #gint64.
+ */
#define G_TYPE_INT64 G_TYPE_MAKE_FUNDAMENTAL (10)
+/**
+ * G_TYPE_UINT64:
+ *
+ * The fundamental type corresponding to #guint64.
+ */
#define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11)
+/**
+ * G_TYPE_ENUM:
+ *
+ * The fundamental type from which all enumeration types are derived.
+ */
#define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12)
+/**
+ * G_TYPE_FLAGS:
+ *
+ * The fundamental type from which all flags types are derived.
+ */
#define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13)
+/**
+ * G_TYPE_FLOAT:
+ *
+ * The fundamental type corresponding to #gfloat.
+ */
#define G_TYPE_FLOAT G_TYPE_MAKE_FUNDAMENTAL (14)
+/**
+ * G_TYPE_DOUBLE:
+ *
+ * The fundamental type corresponding to #gdouble.
+ */
#define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15)
+/**
+ * G_TYPE_STRING:
+ *
+ * The fundamental type corresponding to nul-terminated C strings.
+ */
#define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16)
+/**
+ * G_TYPE_POINTER:
+ *
+ * The fundamental type corresponding to #gpointer.
+ */
#define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17)
+/**
+ * G_TYPE_BOXED:
+ *
+ * The fundamental type from which all boxed types are derived.
+ */
#define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18)
+/**
+ * G_TYPE_PARAM:
+ *
+ * The fundamental type from which all #GParamSpec types are derived.
+ */
#define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19)
+/**
+ * G_TYPE_OBJECT:
+ *
+ * The fundamental type for #GObject.
+ */
#define G_TYPE_OBJECT G_TYPE_MAKE_FUNDAMENTAL (20)
/* Reserved fundamental type numbers to create new fundamental
* type IDs with G_TYPE_MAKE_FUNDAMENTAL().
- * Send email to gtk-devel-list@redhat.com for reservations.
+ * Send email to gtk-devel-list@gnome.org for reservations.
*/
#define G_TYPE_FUNDAMENTAL_SHIFT (2)
+/**
+ * G_TYPE_MAKE_FUNDAMENTAL:
+ * @x: the fundamental type number.
+ *
+ * Get the type ID for the fundamental type number @x.
+ * Use g_type_fundamental_next() instead of this macro to create new fundamental
+ * types.
+ *
+ * Returns: the GType
+ */
#define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
+/**
+ * G_TYPE_RESERVED_GLIB_FIRST:
+ *
+ * First fundamental type number to create a new fundamental type id with
+ * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
+ */
#define G_TYPE_RESERVED_GLIB_FIRST (21)
+/**
+ * G_TYPE_RESERVED_GLIB_LAST:
+ *
+ * Last fundamental type number reserved for GLib.
+ */
#define G_TYPE_RESERVED_GLIB_LAST (31)
+/**
+ * G_TYPE_RESERVED_BSE_FIRST:
+ *
+ * First fundamental type number to create a new fundamental type id with
+ * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
+ */
#define G_TYPE_RESERVED_BSE_FIRST (32)
+/**
+ * G_TYPE_RESERVED_BSE_LAST:
+ *
+ * Last fundamental type number reserved for BSE.
+ */
#define G_TYPE_RESERVED_BSE_LAST (48)
+/**
+ * G_TYPE_RESERVED_USER_FIRST:
+ *
+ * First available fundamental type number to create new fundamental
+ * type id with G_TYPE_MAKE_FUNDAMENTAL().
+ */
#define G_TYPE_RESERVED_USER_FIRST (49)
/* Type Checking Macros
*/
+/**
+ * G_TYPE_IS_FUNDAMENTAL:
+ * @type: A #GType value.
+ *
+ * Checks if @type is a fundamental type.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX)
+/**
+ * G_TYPE_IS_DERIVED:
+ * @type: A #GType value.
+ *
+ * Checks if @type is derived (or in object-oriented terminology:
+ * inherited) from another type (this holds true for all non-fundamental
+ * types).
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX)
+/**
+ * G_TYPE_IS_INTERFACE:
+ * @type: A #GType value.
+ *
+ * Checks 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).
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
+/**
+ * G_TYPE_IS_CLASSED:
+ * @type: A #GType value.
+ *
+ * Checks if @type is a classed type.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
+/**
+ * G_TYPE_IS_INSTANTIATABLE:
+ * @type: A #GType value.
+ *
+ * Checks if @type can be instantiated. Instantiation is the
+ * process of creating an instance (object) of this type.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
+/**
+ * G_TYPE_IS_DERIVABLE:
+ * @type: A #GType value.
+ *
+ * Checks if @type is a derivable type. A derivable type can
+ * be used as the base class of a flat (single-level) class hierarchy.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
+/**
+ * G_TYPE_IS_DEEP_DERIVABLE:
+ * @type: A #GType value.
+ *
+ * Checks 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.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
+/**
+ * G_TYPE_IS_ABSTRACT:
+ * @type: A #GType value.
+ *
+ * Checks 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.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
/**
* G_TYPE_IS_VALUE_ABSTRACT:
* Returns: %TRUE on success.
*/
#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
+/**
+ * G_TYPE_IS_VALUE_TYPE:
+ * @type: A #GType value.
+ *
+ * Checks if @type is a value type and can be used with g_value_init().
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
+/**
+ * G_TYPE_HAS_VALUE_TABLE:
+ * @type: A #GType value.
+ *
+ * Checks if @type has a #GTypeValueTable.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
/* Typedefs
*/
+/**
+ * GType:
+ *
+ * A numerical value which represents the unique identifier of a registered
+ * type.
+ */
#if GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined __cplusplus
typedef gsize GType;
#else /* for historic reasons, C++ links against gulong GTypes */
/* Basic Type Structures
*/
+/**
+ * GTypeClass:
+ *
+ * An opaque structure used as the base of all classes.
+ */
struct _GTypeClass
{
/*< private >*/
GType g_type;
};
+/**
+ * GTypeInstance:
+ *
+ * An opaque structure used as the base of all type instances.
+ */
struct _GTypeInstance
{
/*< private >*/
GTypeClass *g_class;
};
+/**
+ * GTypeInterface:
+ *
+ * An opaque structure used as the base of all interface types.
+ */
struct _GTypeInterface
{
/*< private >*/
GType g_type; /* iface type */
GType g_instance_type;
};
+/**
+ * GTypeQuery:
+ * @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.
+ *
+ * A structure holding information for a specific type. It is
+ * filled in by the g_type_query() function.
+ */
struct _GTypeQuery
{
GType type;
* usage of these macros is reserved to type implementations only
*/
/*< protected >*/
+/**
+ * G_TYPE_CHECK_INSTANCE:
+ * @instance: Location of a #GTypeInstance structure.
+ *
+ * Checks if @instance is a valid #GTypeInstance structure,
+ * otherwise issues a warning and returns %FALSE.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
+/**
+ * G_TYPE_CHECK_INSTANCE_CAST:
+ * @instance: Location of a #GTypeInstance structure.
+ * @g_type: The type to be returned.
+ * @c_type: The corresponding C type of @g_type.
+ *
+ * Checks that @instance is an instance of the type identified by @g_type
+ * and issues a warning if this is not the case. Returns @instance casted
+ * to a pointer to @c_type.
+ *
+ * This macro should only be used in type implementations.
+ */
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
+/**
+ * G_TYPE_CHECK_INSTANCE_TYPE:
+ * @instance: Location of a #GTypeInstance structure.
+ * @g_type: The type to be checked
+ *
+ * Checks if @instance is an instance of the type identified by @g_type.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
+/**
+ * G_TYPE_INSTANCE_GET_CLASS:
+ * @instance: Location of the #GTypeInstance structure.
+ * @g_type: The #GType of the class to be returned.
+ * @c_type: The C type of the class structure.
+ *
+ * Get the class structure of a given @instance, casted
+ * to a specified ancestor type @g_type of the instance.
+ *
+ * that while calling a GInstanceInitFunc(), the class pointer gets
+ * modified, so it might not always return the expected pointer.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: a pointer to the class structure
+ */
#define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type))
+/**
+ * G_TYPE_INSTANCE_GET_INTERFACE:
+ * @instance: Location of the #GTypeInstance structure.
+ * @g_type: The #GType of the interface to be returned.
+ * @c_type: The C type of the interface structure.
+ *
+ * Get the interface structure for interface @g_type of a given @instance.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: a pointer to the interface structure
+ */
#define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
+/**
+ * G_TYPE_CHECK_CLASS_CAST:
+ * @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.
+ *
+ * Checks that @g_class is a class structure of the type identified by @g_type
+ * and issues a warning if this is not the case. Returns @g_class casted
+ * to a pointer to @c_type.
+ *
+ * This macro should only be used in type implementations.
+ */
#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
+/**
+ * G_TYPE_CHECK_CLASS_TYPE:
+ * @g_class: Location of a #GTypeClass structure.
+ * @g_type: The type to be checked.
+ *
+ * Checks if @g_class is a class structure of the type identified by
+ * @g_type.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type)))
+/**
+ * G_TYPE_CHECK_VALUE:
+ * @value: a #GValue
+ *
+ * Checks if @value has been initialized to hold values
+ * of a value type.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value)))
+/**
+ * G_TYPE_CHECK_VALUE_TYPE:
+ * @value: a #GValue
+ * @g_type: The type to be checked.
+ *
+ * Checks if @value has been initialized to hold values
+ * of type @g_type.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type)))
+/**
+ * G_TYPE_FROM_INSTANCE:
+ * @instance: Location of a valid #GTypeInstance structure.
+ *
+ * Get the type identifier from a given @instance structure.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: the #GType
+ */
#define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
+/**
+ * G_TYPE_FROM_CLASS:
+ * @g_class: Location of a valid #GTypeClass structure.
+ *
+ * Get the type identifier from a given @class structure.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: the #GType
+ */
#define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type)
+/**
+ * G_TYPE_FROM_INTERFACE:
+ * @g_iface: Location of a valid #GTypeInterface structure.
+ *
+ * Get the type identifier from a given @interface structure.
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Returns: the #GType
+ */
#define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type)
+/**
+ * G_TYPE_INSTANCE_GET_PRIVATE:
+ * @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.
+ *
+ * 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().
+ *
+ * This macro should only be used in type implementations.
+ *
+ * Since: 2.4
+ * Returns: a pointer to the private data structure.
+ */
#define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))
-/* debug flags for g_type_init_with_debug_flags() */
+/**
+ * GTypeDebugFlags:
+ * @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.
+ *
+ * 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".
+ */
typedef enum /*< skip >*/
{
G_TYPE_DEBUG_NONE = 0,
/* --- type registration --- */
+/**
+ * GBaseInitFunc:
+ * @g_class: The #GTypeClass structure to initialize.
+ *
+ * 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.
+ */
typedef void (*GBaseInitFunc) (gpointer g_class);
+/**
+ * GBaseFinalizeFunc:
+ * @g_class: The #GTypeClass structure to finalize.
+ *
+ * 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.
+ */
typedef void (*GBaseFinalizeFunc) (gpointer g_class);
+/**
+ * GClassInitFunc:
+ * @g_class: The #GTypeClass structure to initialize.
+ * @class_data: The @class_data member supplied via the #GTypeInfo structure.
+ *
+ * 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>
+ * <listitem><para>
+ * 1 - Copying common members from the parent class over to the
+ * derived class structure.
+ * </para></listitem>
+ * <listitem><para>
+ * 2 - Zero initialization of the remaining members not copied
+ * over from the parent class.
+ * </para></listitem>
+ * <listitem><para>
+ * 3 - Invocation of the GBaseInitFunc() initializers of all parent
+ * types and the class' type.
+ * </para></listitem>
+ * <listitem><para>
+ * 4 - Invocation of the class' GClassInitFunc() initializer.
+ * </para></listitem>
+ * </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:
+ *
+ * |[
+ * 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;
+ * }
+ * ]|
+ * 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.
+ */
typedef void (*GClassInitFunc) (gpointer g_class,
gpointer class_data);
+/**
+ * GClassFinalizeFunc:
+ * @g_class: The #GTypeClass structure to finalize.
+ * @class_data: The @class_data member supplied via the #GTypeInfo structure.
+ *
+ * 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).
+ */
typedef void (*GClassFinalizeFunc) (gpointer g_class,
gpointer class_data);
+/**
+ * GInstanceInitFunc:
+ * @instance: The instance to initialize.
+ * @g_class: The class of the type the instance is created for.
+ *
+ * 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.
+ */
typedef void (*GInstanceInitFunc) (GTypeInstance *instance,
gpointer g_class);
+/**
+ * GInterfaceInitFunc:
+ * @g_iface: The interface structure to initialize.
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ *
+ * 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.
+ */
typedef void (*GInterfaceInitFunc) (gpointer g_iface,
gpointer iface_data);
+/**
+ * GInterfaceFinalizeFunc:
+ * @g_iface: The interface structure to finalize.
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ *
+ * 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.
+ */
typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface,
gpointer iface_data);
+/**
+ * GTypeClassCacheFunc:
+ * @cache_data: data that was given to the g_type_add_class_cache_func() call
+ * @g_class: The #GTypeClass structure which is unreferenced
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
+ * called, %FALSE to continue.
+ */
typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data,
GTypeClass *g_class);
+/**
+ * GTypeInterfaceCheckFunc:
+ * @check_data: data passed to g_type_add_interface_check().
+ * @g_iface: the interface that has been initialized
+ *
+ * A callback called after an interface vtable is initialized.
+ * See g_type_add_interface_check().
+ *
+ * Since: 2.4
+ */
typedef void (*GTypeInterfaceCheckFunc) (gpointer check_data,
gpointer g_iface);
+/**
+ * GTypeFundamentalFlags:
+ * @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).
+ *
+ * Bit masks used to check or determine specific characteristics of a
+ * fundamental type.
+ */
typedef enum /*< skip >*/
{
G_TYPE_FLAG_CLASSED = (1 << 0),
G_TYPE_FLAG_DERIVABLE = (1 << 2),
G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3)
} GTypeFundamentalFlags;
+/**
+ * GTypeFlags:
+ * @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().
+ *
+ * Bit masks used to check or determine characteristics of a type.
+ */
typedef enum /*< skip >*/
{
G_TYPE_FLAG_ABSTRACT = (1 << 4),
G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5)
} GTypeFlags;
+/**
+ * GTypeInfo:
+ * @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 instantiatable 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 instantiatable 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).
+ *
+ * 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().
+ */
struct _GTypeInfo
{
/* interface types, classed types, instantiated types */
/* value handling */
const GTypeValueTable *value_table;
};
+/**
+ * GTypeFundamentalInfo:
+ * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
+ *
+ * A structure that provides information to the type system which is
+ * used specifically for managing fundamental types.
+ */
struct _GTypeFundamentalInfo
{
GTypeFundamentalFlags type_flags;
};
+/**
+ * GInterfaceInfo:
+ * @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
+ *
+ * A structure that provides information to the type system which is
+ * used specifically for managing interface types.
+ */
struct _GInterfaceInfo
{
GInterfaceInitFunc interface_init;
GInterfaceFinalizeFunc interface_finalize;
gpointer interface_data;
};
+/**
+ * GTypeValueTable:
+ * @value_init: Default initialize @values contents by poking values
+ * directly into the value->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:
+ * |[
+ * value->data[0].v_pointer = g_strdup ("");
+ * ]|
+ * @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:
+ * |[
+ * // only free strings without a specific flag for static storage
+ * if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
+ * g_free (value->data[0].v_pointer);
+ * ]|
+ * @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:
+ * |[
+ * dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
+ * ]|
+ * @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:
+ * |[
+ * return value->data[0].v_pointer;
+ * ]|
+ * @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:
+ * |[
+ * if (!collect_values[0].v_pointer)
+ * value->data[0].v_pointer = g_strdup ("");
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ * {
+ * value->data[0].v_pointer = collect_values[0].v_pointer;
+ * // keep a flag for the value_free() implementation to not free this string
+ * value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
+ * }
+ * else
+ * value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
+ * return NULL;
+ * ]|
+ * 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->data array.
+ * To deviate from our string example for a moment, and taking a look
+ * at an exemplary implementation for collect_value() of #GObject:
+ * |[
+ * 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->data[0].v_pointer = g_object_ref (object);
+ * return NULL;
+ * }
+ * else
+ * return g_strdup_printf ("Object passed as invalid NULL pointer");
+ * }
+ * ]|
+ * 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:
+ * |[
+ * gchar **string_p = collect_values[0].v_pointer;
+ * if (!string_p)
+ * return g_strdup_printf ("string location passed as NULL");
+ * if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
+ * *string_p = value->data[0].v_pointer;
+ * else
+ * *string_p = g_strdup (value->data[0].v_pointer);
+ * ]|
+ * And an illustrative version of lcopy_value() for
+ * reference-counted types:
+ * |[
+ * GObject **object_p = collect_values[0].v_pointer;
+ * if (!object_p)
+ * return g_strdup_printf ("object location passed as NULL");
+ * if (!value->data[0].v_pointer)
+ * *object_p = NULL;
+ * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
+ * *object_p = value->data[0].v_pointer;
+ * else
+ * *object_p = g_object_ref (value->data[0].v_pointer);
+ * return NULL;
+ * ]|
+ *
+ * The #GTypeValueTable provides the functions required by the #GValue implementation,
+ * to serve as a container for values of a type.
+ */
+
struct _GTypeValueTable
{
void (*value_init) (GValue *value);
/* --- GType boilerplate --- */
-/* convenience macros for type implementations, which for a type GtkGadget will:
- * - prototype: static void gtk_gadget_class_init (GtkGadgetClass *klass);
- * - prototype: static void gtk_gadget_init (GtkGadget *self);
- * - define: static gpointer gtk_gadget_parent_class = NULL;
- * gtk_gadget_parent_class is initialized prior to calling gtk_gadget_class_init()
- * - implement: GType gtk_gadget_get_type (void) { ... }
- * - support custom code in gtk_gadget_get_type() after the type is registered.
- *
- * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
- * example: G_DEFINE_TYPE_WITH_CODE (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET,
- * g_print ("GtkGadget-id: %lu\n", g_define_type_id));
+/**
+ * G_DEFINE_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words
+ * separated by '_'.
+ * @T_P: The #GType of the parent type.
+ *
+ * A convenience macro for type implementations, which declares a
+ * class initialization function, an instance initialization function (see #GTypeInfo for information about
+ * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
+ * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
*/
#define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
+/**
+ * G_DEFINE_TYPE_WITH_CODE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
+ *
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE(), but allows to insert custom code into the
+ * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
+ */
#define G_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
+/**
+ * G_DEFINE_ABSTRACT_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words
+ * separated by '_'.
+ * @T_P: The #GType of the parent type.
+ *
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE(), but defines an abstract type.
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
+ */
#define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
+/**
+ * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words
+ * separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
+ *
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows to
+ * insert custom code into the *_get_type() function, e.g. interface implementations
+ * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
+ */
#define G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
+/**
+ * G_DEFINE_TYPE_EXTENDED:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words
+ * separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_f_: #GTypeFlags to pass to g_type_register_static()
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
+ *
+ * The most general convenience macro for type implementations, on which
+ * G_DEFINE_TYPE(), etc are based.
+ *
+ * |[
+ * G_DEFINE_TYPE_EXTENDED (GtkGadget,
+ * gtk_gadget,
+ * GTK_TYPE_WIDGET,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
+ * ]|
+ * expands to
+ * |[
+ * static void gtk_gadget_init (GtkGadget *self);
+ * static void gtk_gadget_class_init (GtkGadgetClass *klass);
+ * static gpointer gtk_gadget_parent_class = NULL;
+ * static void gtk_gadget_class_intern_init (gpointer klass)
+ * {
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * }
+ *
+ * GType
+ * gtk_gadget_get_type (void)
+ * {
+ * static GType g_define_type_id = 0;
+ * if (G_UNLIKELY (g_define_type_id == 0))
+ * {
+ * static const GTypeInfo g_define_type_info = {
+ * sizeof (GtkGadgetClass),
+ * (GBaseInitFunc) NULL,
+ * (GBaseFinalizeFunc) NULL,
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * (GClassFinalizeFunc) NULL,
+ * NULL, // class_data
+ * sizeof (GtkGadget),
+ * 0, // n_preallocs
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * };
+ * g_define_type_id = g_type_register_static (GTK_TYPE_WIDGET, "GtkGadget", &g_define_type_info, 0);
+ * {
+ * static const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * }
+ * return g_define_type_id;
+ * }
+ * ]|
+ * The only pieces which have to be manually provided are the definitions of the
+ * instance and class structure and the definitions of the instance and class
+ * init functions.
+ *
+ * Since: 2.4
+ */
#define G_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
-/* convenience macro to ease interface addition in the CODE
- * section of G_DEFINE_TYPE_WITH_CODE() (this macro relies on
- * the g_define_type_id present within G_DEFINE_TYPE_WITH_CODE()).
- * usage example:
- * G_DEFINE_TYPE_WITH_CODE (GtkTreeStore, gtk_tree_store, G_TYPE_OBJECT,
- * G_IMPLEMENT_INTERFACE (GTK_TYPE_TREE_MODEL,
- * gtk_tree_store_tree_model_init));
+/**
+ * G_IMPLEMENT_INTERFACE:
+ * @TYPE_IFACE: The #GType of the interface to add
+ * @iface_init: The interface init function
+ *
+ * A convenience macro to ease interface addition in the @_C_ section
+ * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Note that this macro can only be used together with the G_DEFINE_TYPE_*
+ * macros, since it depends on variable names from those macros.
+ *
+ * Since: 2.4
*/
#define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) { \
const GInterfaceInfo g_implement_interface_info = { \
# define _G_TYPE_CCT(cp, gt) (g_type_check_class_is_a ((GTypeClass*) cp, gt))
# define _G_TYPE_CVH(vl, gt) (g_type_check_value_holds ((GValue*) vl, gt))
#endif /* !__GNUC__ */
+/**
+ * G_TYPE_FLAG_RESERVED_ID_BIT:
+ *
+ * A bit in the type number that's supposed to be left untouched.
+ */
#define G_TYPE_FLAG_RESERVED_ID_BIT ((GType) (1 << 0))
extern GTypeDebugFlags _g_type_debug_flags;
#define G_VALUE_HOLDS_DOUBLE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_DOUBLE))
#define G_VALUE_HOLDS_STRING(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_STRING))
#define G_VALUE_HOLDS_POINTER(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_POINTER))
+/**
+ * G_TYPE_GTYPE:
+ *
+ * The type for #GType.
+ */
#define G_TYPE_GTYPE (g_gtype_get_type())
#define G_VALUE_HOLDS_GTYPE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_GTYPE))
projects / platform / upstream / glib.git / commitdiff