diff options
| -rw-r--r-- | ChangeLog | 8 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/gtype.sgml | 1844 | ||||
| -rw-r--r-- | gobject/gtype.c | 602 | ||||
| -rw-r--r-- | gobject/gtype.h | 1044 | ||||
| -rw-r--r-- | gobject/gvaluetypes.h | 5 |
5 files changed, 1636 insertions, 1867 deletions
@@ -1,5 +1,13 @@ 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. diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml deleted file mode 100644 index 8de586cf8..000000000 --- a/docs/reference/gobject/tmpl/gtype.sgml +++ /dev/null @@ -1,1844 +0,0 @@ -<!-- ##### 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: ---> - - - diff --git a/gobject/gtype.c b/gobject/gtype.c index 9913212db..203c7fc92 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -16,6 +16,42 @@ * 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" @@ -1255,6 +1291,17 @@ type_iface_add_prerequisite_W (TypeNode *iface, 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) @@ -1330,7 +1377,18 @@ g_type_interface_add_prerequisite (GType interface_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) { @@ -1526,6 +1584,26 @@ instance_real_class_get (gpointer instance) 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) { @@ -1577,6 +1655,16 @@ 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) { @@ -2067,6 +2155,19 @@ type_data_last_unref_Wm (GType type, } } +/** + * 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) @@ -2083,6 +2184,15 @@ g_type_add_class_cache_func (gpointer cache_data, 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) @@ -2113,6 +2223,24 @@ g_type_remove_class_cache_func (gpointer cache_data, } +/** + * 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) @@ -2129,6 +2257,16 @@ g_type_add_interface_check (gpointer check_data, 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) @@ -2159,6 +2297,23 @@ g_type_remove_interface_check (gpointer check_data, } /* --- 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, @@ -2211,6 +2366,24 @@ g_type_register_fundamental (GType type_id, 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, @@ -2236,6 +2409,21 @@ g_type_register_static_simple (GType parent_type, 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, @@ -2276,6 +2464,21 @@ g_type_register_static (GType parent_type, 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, @@ -2305,6 +2508,17 @@ g_type_register_dynamic (GType parent_type, 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, @@ -2331,6 +2545,16 @@ g_type_add_interface_static (GType instance_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, @@ -2359,6 +2583,16 @@ g_type_add_interface_dynamic (GType instance_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) { @@ -2409,6 +2643,15 @@ 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) { @@ -2428,6 +2671,15 @@ 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) { @@ -2447,6 +2699,18 @@ 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) { @@ -2464,6 +2728,17 @@ 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) { @@ -2483,6 +2758,23 @@ 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) { @@ -2507,6 +2799,17 @@ 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) @@ -2538,6 +2841,19 @@ g_type_interface_peek (gpointer instance_class, 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) { @@ -2570,6 +2886,27 @@ 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) { @@ -2607,6 +2944,17 @@ 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) { @@ -2624,6 +2972,20 @@ 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) { @@ -2644,6 +3006,18 @@ 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) { @@ -2656,6 +3030,14 @@ 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) { @@ -2666,6 +3048,15 @@ 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) { @@ -2685,6 +3076,15 @@ 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) { @@ -2695,6 +3095,15 @@ 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) { @@ -2705,6 +3114,20 @@ 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) @@ -2776,6 +3199,16 @@ type_node_conforms_to_U (TypeNode *node, 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) @@ -2790,7 +3223,17 @@ g_type_is_a (GType 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) { @@ -2821,7 +3264,18 @@ g_type_children (GType type, } } -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) { @@ -2899,6 +3353,16 @@ type_get_qdata_L (TypeNode *node, 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) @@ -2956,6 +3420,14 @@ type_set_qdata_W (TypeNode *node, 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, @@ -2992,6 +3464,18 @@ type_add_flags_W (TypeNode *node, 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) @@ -3057,6 +3541,16 @@ g_type_test_flags (GType type, 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) { @@ -3067,6 +3561,19 @@ 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) @@ -3103,6 +3610,17 @@ g_type_interface_get_plugin (GType instance_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) { @@ -3115,6 +3633,15 @@ 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) { @@ -3310,6 +3837,18 @@ g_type_check_value_holds (GValue *value, 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) { @@ -3387,6 +3926,12 @@ g_type_name_from_class (GTypeClass *g_class) /* --- 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) { @@ -3492,12 +4037,63 @@ 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) diff --git a/gobject/gtype.h b/gobject/gtype.h index a80efc432..565df25c7 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -29,57 +29,295 @@ G_BEGIN_DECLS /* 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: @@ -92,12 +330,34 @@ G_BEGIN_DECLS * 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 */ @@ -118,22 +378,47 @@ typedef struct _GTypeQuery GTypeQuery; /* 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; @@ -147,23 +432,189 @@ struct _GTypeQuery * 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, @@ -215,22 +666,231 @@ void g_type_query (GType type, /* --- 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), @@ -238,11 +898,51 @@ typedef enum /*< skip >*/ 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 */ @@ -264,16 +964,200 @@ struct _GTypeInfo /* 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); @@ -331,31 +1215,146 @@ gpointer g_type_instance_get_private (GTypeInstance *instance, /* --- 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 = { \ @@ -501,6 +1500,11 @@ G_GNUC_INTERNAL void g_signal_init (void); /* sync with gsignal.c * # 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; diff --git a/gobject/gvaluetypes.h b/gobject/gvaluetypes.h index 2931cdaa6..258360873 100644 --- a/gobject/gvaluetypes.h +++ b/gobject/gvaluetypes.h @@ -43,6 +43,11 @@ G_BEGIN_DECLS #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)) |