From 61f76fa4e594a009fa20eab3352d34a857bd5b1d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 23 Apr 2002 23:18:37 +0000 Subject: [PATCH] Updates. * gobject/gobject-sections.txt: * gobject/tmpl/gtype.sgml: Updates. --- docs/reference/ChangeLog | 5 + docs/reference/gobject/gobject-sections.txt | 2 +- docs/reference/gobject/tmpl/gtype.sgml | 148 +++++++++++++++------------- 3 files changed, 85 insertions(+), 70 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index d337b6e..25bd403 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2002-04-24 Matthias Clasen + + * gobject/gobject-sections.txt: + * gobject/tmpl/gtype.sgml: Updates. + 2002-04-21 Matthias Clasen * glib/tmpl/strings.sgml: Fix the description of g_string_assign. (#78728) diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt index 2b17b48..023a81c 100644 --- a/docs/reference/gobject/gobject-sections.txt +++ b/docs/reference/gobject/gobject-sections.txt @@ -6,7 +6,6 @@ GType G_TYPE_FUNDAMENTAL G_TYPE_FUNDAMENTAL_MAX -G_TYPE_FUNDAMENTAL_SHIFT G_TYPE_MAKE_FUNDAMENTAL G_TYPE_IS_ABSTRACT G_TYPE_IS_DERIVED @@ -87,6 +86,7 @@ g_type_remove_class_cache_func g_type_class_unref_uncached g_type_value_table_peek +G_TYPE_FUNDAMENTAL_SHIFT g_type_check_instance g_type_check_instance_cast g_type_check_instance_is_a diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml index 200b7f1..5c1cb7b 100644 --- a/docs/reference/gobject/tmpl/gtype.sgml +++ b/docs/reference/gobject/tmpl/gtype.sgml @@ -20,7 +20,7 @@ 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 retrived during runtime through #GTypePlugin +#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 @@ -47,7 +47,7 @@ type. -Returns #TRUE if @type is a fundamental data type such as #G_TYPE_INT or +Returns %TRUE if @type is a fundamental data type such as #G_TYPE_INT or #G_TYPE_POINTER. Fundamental types are types that serve as fundaments for the derived types, thus they are the roots of distinct inheritance hierarchies. @@ -65,22 +65,24 @@ for types that are assigned at compile-time. - +Shift value used in converting numbers to type IDs. - +Returns the type ID for the fundamental type number @x. +Use g_type_fundamental_next() instead of this macro to create new fundamental +types. -@x: +@x: the fundamental type number. -Returns #TRUE if @type is an abstract type. An abstract type can not be +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. @@ -90,7 +92,7 @@ derived classes. -Returns #TRUE if @type is derived (or in object-oriented terminology: +Returns %TRUE if @type is derived (or in object-oriented terminology: inherited) from another type (this holds true for all non-fundamental types). @@ -100,7 +102,7 @@ types). -Returns #TRUE if @type is a fundamental type. +Returns %TRUE if @type is a fundamental type. @type: A #GType value. @@ -116,15 +118,15 @@ Returns #TRUE if @type is a fundamental type. - +Returns %TRUE if @type has a #GTypeValueTable. -@type: +@type: A #GType value. -Returns #TRUE if @type is a classed type. +Returns %TRUE if @type is a classed type. @type: A #GType value. @@ -132,7 +134,7 @@ Returns #TRUE if @type is a classed type. -Returns #TRUE if @type can be instantiated. Instantiation is the +Returns %TRUE if @type can be instantiated. Instantiation is the process of creating an instance (object) of this type. @@ -141,7 +143,7 @@ process of creating an instance (object) of this type. -Returns #TRUE if @type is a derivable type. A derivable type can +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. @@ -150,7 +152,7 @@ be used as the base class of a flat (single-level) class hierarchy. -Returns #TRUE if @type is a deep derivable type. A deep derivable type +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. @@ -159,11 +161,13 @@ can be used as the base class of a deep (multi-level) class hierarchy. -Returns #TRUE if @type is an interface type. +Returns %TRUE if @type is an interface type. Interface types are types that provide pure APIs, 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. +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). @type: A #GType value. @@ -202,7 +206,7 @@ across invocation of g_type_register_static(). @instance_size: Size of the instance (object) structure (required for instantiatable types only). @n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). @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 (usualy only +@value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types). @@ -233,9 +237,10 @@ to serve as a container for values of a type. @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 memset, so no care has to be taken to free any + with memset(), 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 + value that may never be %NULL, the implementation might look like: { @@ -299,10 +304,10 @@ to serve as a container for values of a type. 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, + 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 + 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 @@ -311,7 +316,7 @@ to serve as a container for values of a type. @collect_flags is an argument provided as a hint by the caller, which 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. + 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: @@ -334,7 +339,7 @@ to serve as a container for values of a type. 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 + 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: @@ -355,9 +360,9 @@ to serve as a container for values of a type. 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 + Upon success, collect_value() needs to return %NULL, if however a malicious condition occurred, collect_value() may spew an - error by returning a newly allocated non-NULL string, giving + 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 @@ -365,7 +370,7 @@ to serve as a container for values of a type. 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 + 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 @@ -534,26 +539,28 @@ the type system and assorted other code portions (such as the various fundamenta type implementations or the signal system). - -@debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. - +The GTypeDebugFlags 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 +GOBJECT_DEBUG environment variable to a ':'-separated list of +"objects" and "signals". -@G_TYPE_DEBUG_NONE: -@G_TYPE_DEBUG_OBJECTS: -@G_TYPE_DEBUG_SIGNALS: +@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: - +Similar to g_type_init(), but additionally sets debug flags. -@debug_flags: +@debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. @@ -563,7 +570,7 @@ to find out whether a specific type has been registered for the passed in ID yet @type: Type to return name for. -@Returns: Static type name or NULL. +@Returns: Static type name or %NULL. @@ -597,11 +604,12 @@ If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. - +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. -@type: -@Returns: +@type: A #GType value. +@Returns: The depth of @type. @@ -621,11 +629,12 @@ the leaf type is descended from the root type. -Check whether @type is a descendant of @is_a_type. +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. @type: Type to check anchestry for. -@is_a_type: Possible anchestor of @type. +@is_a_type: Possible anchestor of @type or interface @type could conform to. @Returns: %TRUE if @type is_a @is_a_type holds true. @@ -644,12 +653,12 @@ exist already. This function is essentially the same as g_type_class_ref(), except that the classes reference count isn't incremented. Therefore, this function -may return NULL if the class of the type passed in does not currently +may return %NULL if the class of the type passed in does not currently exist (hasn't been referenced before). @type: Type ID of a classed type. -@Returns: The #GTypeClass structure for the given type ID or NULL +@Returns: The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist. @@ -666,7 +675,7 @@ class pointer after g_type_class_unref() are invalid. -This is a convenience function, often needed in class intializers. +This is a convenience function, often needed in class initializers. It essentially takes the immediate parent type of the class passed in, and returns the class structure thereof. Since derived classes hold a reference count on their parent classes as long as they are instantiated, @@ -685,12 +694,15 @@ g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - +Returns the #GTypeInterface structure of an interface to which the passed in +class conforms. -@instance_class: -@iface_type: -@Returns: +@instance_class: A #GTypeClass structure. +@iface_type: An interface ID which this class conforms to. +@Returns: The #GTypeInterface structure of @iface_type, or %NULL if the + class is not instantiated. + @@ -704,25 +716,25 @@ g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); -Return a newly allocated and 0 terminated array of type IDs, listing the +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. @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. +@Returns: Newly allocated and 0-terminated array of child types. -Return a newly allocated and 0 terminated array of type IDs, listing the +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. @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. +@Returns: Newly allocated and 0-terminated array of interface types. @@ -807,11 +819,11 @@ The initialization process of a class involves: over from the parent class. - 3 - Invocation of the GBaseInitFunc initializers of all parent + 3 - Invocation of the GBaseInitFunc() initializers of all parent types and the class' type. - 4 - Invocation of the class' GClassInitFunc initializer. + 4 - Invocation of the class' GClassInitFunc() initializer. Since derived classes are partially initialized through a memory copy @@ -819,11 +831,11 @@ of the parent class, the general rule is that GBaseInitFunc() and GBaseFinalizeFunc() should take care of necessary reinitialization and release of those class members that were introduced by the type that specified these GBaseInitFunc()/GBaseFinalizeFunc(). -GClassInitFunc() should only care about intializing static +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 -are performed for class intialization of derived types as well. +is performed for class initialization of derived types as well. An example may help to correspond the intend of the different class initializers: @@ -857,7 +869,7 @@ typedef struct { static void type_b_base_class_init (TypeBClass *class) { - class->dynamic_gstring = g_string_new ("some other string); + class->dynamic_gstring = g_string_new ("some other string"); } static void type_b_base_class_finalize (TypeBClass *class) @@ -902,7 +914,7 @@ time. 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 +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). @@ -989,7 +1001,7 @@ instances (if not abstract). The value of @flags determines the nature @parent_type: Type which this type will be derived from. -@type_name: Null-terminated string used as the name of the new type. +@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. @@ -1005,12 +1017,10 @@ instances (if not abstract). The value of @flags determines the nature @parent_type: Type which this type will be derived from. -@type_name: Null-terminated string used as the name of the new type. -@plugin: The #GTypePlugin structure to retrive the #GTypeInfo from. +@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. - -@Returns: #G_TYPE_INVALID if registration failed or the new type identifier. +@Returns: The new type identifier or #G_TYPE_INVALID if registration failed. @@ -1024,7 +1034,7 @@ characteristics of the fundamental type. @type_id: A predefined #GTypeFundamentals value. -@type_name: Null-terminated string used as the name of the new type. +@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. @@ -1064,13 +1074,13 @@ is used to manage the relationship. -Returns the the #GTypePlugin structure for @type or -#NULL if @type does not have a #GTypePlugin structure. +Returns the #GTypePlugin structure for @type or +%NULL if @type does not have a #GTypePlugin structure. -@type: The #GType to retrive the plugin for. +@type: The #GType to retrieve the plugin for. @Returns: The corresponding plugin if @type is a dynamic type, - NULL otherwise. + %NULL otherwise. @@ -1169,7 +1179,7 @@ that implements or has internal knowledge of the implementation of @type: A #GType value. @Returns: Location of the #GTypeValueTable associated with @type or - #NULL if there is no #GTypeValueTable associated with @type. + %NULL if there is no #GTypeValueTable associated with @type. -- 2.7.4