From: Stefan Kost Date: Fri, 22 Apr 2005 10:27:37 +0000 (+0000) Subject: merged in docs form the gobject tutorial X-Git-Tag: GLIB_2_7_0~70 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9ce3590d4e40dbc4ff2a11cd175587c07cc16621;p=platform%2Fupstream%2Fglib.git merged in docs form the gobject tutorial --- diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index b43b7f2..41fbc45 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,15 @@ +2005-04-22 Stefan Kost + + * gobject/Makefile.am: + * gobject/gobject-docs.sgml: + * gobject/tut_gobject.xml: + * gobject/tut_gsignal.xml: + * gobject/tut_gtype.xml: + * gobject/tut_howto.xml: + * gobject/tut_intro.xml: + * gobject/tut_tools.xml: + merged in docs form the gobject tutorial + 2005-03-29 Matthias Clasen * glib/tmpl/arrays_pointer.sgml: Clarify the docs for diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am index 1505594..c1cc1f1 100644 --- a/docs/reference/gobject/Makefile.am +++ b/docs/reference/gobject/Makefile.am @@ -34,14 +34,21 @@ GTKDOC_LIBS = \ # Extra options to supply to gtkdoc-mkdb MKDB_OPTIONS= -# Images to copy into HTML directory -HTML_IMAGES = - # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) content_files = version.xml \ glib-mkenums.xml \ glib-genmarshal.xml \ - gobject-query.xml + gobject-query.xml \ + tut_gobject.xml \ + tut_gsignal.xml \ + tut_gtype.xml \ + tut_howto.xml \ + tut_intro.xml \ + tut_tools.xml + +# Images to copy into HTML directory +HTML_IMAGES = \ + $(srcdir)/images/glue.png # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=$(srcdir)/../glib/html diff --git a/docs/reference/gobject/gobject-docs.sgml b/docs/reference/gobject/gobject-docs.sgml index 1fb97ef..2a5d940 100644 --- a/docs/reference/gobject/gobject-docs.sgml +++ b/docs/reference/gobject/gobject-docs.sgml @@ -18,6 +18,14 @@ + + + + + + + + ]> @@ -28,48 +36,56 @@ Introduction - Most modern programming languages come with their own native object - systems and additional fundamental algorithmic language constructs. - Just as GLib serves as an implementation of such fundamental - types and algorithms (linked lists, hash tables and so forth), the - GLib Object System provides the required implementations of a - flexible extensible and intentionally easy to map (into other - languages) object oriented framework for C. - The substantial elements that are provided can be summarized as: - - - * A generic type system to register arbitrary single-inherited - flat and deep derived types as well as interfaces for - structured types. - It takes care of creation, initialization and memory management - of the assorted object and class structures, maintains - parent/child relationships and deals with dynamic implementations - of such types. That is, their type specific implementations are - relocatable/unloadable during runtime. - - - * A collection of fundamental type implementations, such as integers, - doubles, enums and structured types, to name a few. - - - * A sample fundamental type implementation to base object hierarchies - upon - the GObject fundamental type. - - - * A signal system that allows very flexible user customization of - virtual/overridable object methods and can serve as a powerful - notification mechanism. - - - * An extensible parameter/value system, supporting all the provided - fundamental types that can be used to generically handle object - properties or otherwise parameterized types. - - - + Most modern programming languages come with their own native object + systems and additional fundamental algorithmic language constructs. + Just as GLib serves as an implementation of such fundamental + types and algorithms (linked lists, hash tables and so forth), the + GLib Object System provides the required implementations of a + flexible extensible and intentionally easy to map (into other + languages) object oriented framework for C. + The substantial elements that are provided can be summarized as: + + + A generic type system to register arbitrary single-inherited + flat and deep derived types as well as interfaces for + structured types. + It takes care of creation, initialization and memory management + of the assorted object and class structures, maintains + parent/child relationships and deals with dynamic implementations + of such types. That is, their type specific implementations are + relocatable/unloadable during runtime. + + + A collection of fundamental type implementations, such as integers, + doubles, enums and structured types, to name a few. + + + A sample fundamental type implementation to base object hierarchies + upon - the GObject fundamental type. + + + A signal system that allows very flexible user customization of + virtual/overridable object methods and can serve as a powerful + notification mechanism. + + + An extensible parameter/value system, supporting all the provided + fundamental types that can be used to generically handle object + properties or otherwise parameterized types. + + + - + + Concepts + + &tutorial-Intro; + &tutorial-GType; + &tutorial-GObject; + &tutorial-GSignal; + + API Reference &gobject-GType; @@ -87,13 +103,23 @@ &gobject-Value-Arrays; - + Tools Reference &glib-mkenums; &glib-genmarshal; &gobject-query; + + Tutorial + + &tutorial-HowTo; + + + Related Tools + + &tutorial-Tools; + Index diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml index 15c198a..acdf8ee 100644 --- a/docs/reference/gobject/tut_gobject.xml +++ b/docs/reference/gobject/tut_gobject.xml @@ -1,16 +1,16 @@ - GObject: what brings everything together. + The GObject base class The two previous chapters discussed the details of Glib's Dynamic Type System and its signal control system. The GObject library also contains an implementation - for a base fundamental type named GObject. + for a base fundamental type named GObject. - GObject is a fundamental classed instantiable type. It implements: + GObject is a fundamental classed instantiable type. It implements: Memory management with reference counting Construction/Destruction of instances @@ -18,7 +18,7 @@ Easy use of signals All the GTK+ objects and all of the objects in Gnome libraries which use the glib type - system inherit from GObject which is why it is important to understand + system inherit from GObject which is why it is important to understand the details of how it works. @@ -26,13 +26,13 @@ Object instanciation - The g_object_new family of functions can be used to instantiate any + The g_object_new family of functions can be used to instantiate any GType which inherits from the GObject base type. All these functions make sure the class and instance structures have been correctly initialized by glib's type system and then invoke at one point or another the constructor class method which is used to: - Allocate and clear memory through g_type_create_instance, + Allocate and clear memory through g_type_create_instance, Initialize the object' instance with the construction properties. @@ -155,7 +155,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - Once g_object_new has obtained a reference to an initialized + Once g_object_new has obtained a reference to an initialized class structure, it invokes its constructor method to create an instance of the new object. Since it has just been overridden by maman_bar_class_init to maman_bar_constructor, the latter is called and, because it @@ -164,34 +164,34 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); to save the original constructor in a static variable from maman_bar_class_init and then to re-use it from maman_bar_constructor. This is clearly possible and very simple but I was told it was not nice and the prefered way is to use the - g_type_class_peek and g_type_class_peek_parent functions. + g_type_class_peek and g_type_class_peek_parent functions. Finally, at one point or another, g_object_constructor is invoked by the last constructor in the chain. This function allocates the object's instance' buffer - through g_type_create_instance + through g_type_create_instance which means that the instance_init function is invoked at this point if one was registered. After instance_init returns, the object is fully initialized and should be - ready to answer any user-request. When g_type_create_instance + ready to answer any user-request. When g_type_create_instance returns, g_object_constructor sets the construction properties - (ie: the properties which were given to g_object_new) and returns + (ie: the properties which were given to g_object_new) and returns to the user's constructor which is then allowed to do useful instance initialization... The process described above might seem a bit complicated (it is actually overly complicated in my opinion..) but it can be summarized easily by the table below which - lists the functions invoked by g_object_new and their order of + lists the functions invoked by g_object_new and their order of invocation. - The array below lists the functions invoked by g_object_new and + The array below lists the functions invoked by g_object_new and their order of invocation: - <function>g_object_new</function> + <function><link linkend="g-object-new">g_object_new</link></function> @@ -207,7 +207,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + First call to g_object_new for target type target type's base_init function On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. @@ -217,7 +217,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + First call to g_object_new for target type target type's class_init function On target type's class structure @@ -227,19 +227,19 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + First call to g_object_new for target type interface' base_init function On interface' vtable - First call to g_object_new for target type + First call to g_object_new for target type interface' interface_init function On interface' vtable - Each call to g_object_new for target type + Each call to g_object_new for target type target type's class constructor method: GObjectClass->constructor On object's instance @@ -250,7 +250,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - Each call to g_object_new for target type + Each call to g_object_new for target type type's instance_init function On the inheritance tree of classes from fundamental type to target type. the instance_init provided for each type is invoked once for each instance @@ -270,7 +270,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); Readers should feel concerned about one little twist in the order in which functions are invoked: while, technically, the class' constructor method is called before the GType's instance_init function (since - g_type_create_instance which calls instance_init is called by + g_type_create_instance which calls instance_init is called by g_object_constructor which is the top-level class constructor method and to which users are expected to chain to), the user's code which runs in a user-provided constructor will always run after @@ -322,19 +322,19 @@ void g_object_run_dispose (GObject *object); Reference count - The functions g_object_ref/g_object_unref respectively + The functions g_object_ref/g_object_unref respectively increase and decrease the reference count. None of these function is thread-safe. The reference count is, unsurprisingly, initialized to one by - g_object_new which means that the caller + g_object_new which means that the caller is currenly the sole owner of the newly-created reference. When the reference count reaches zero, that is, - when g_object_unref is called by the last client holding + when g_object_unref is called by the last client holding a reference to the object, the dispose and the finalize class methods are invoked. Finally, after finalize is invoked, - g_type_free_instance is called to free the object instance. + g_type_free_instance is called to free the object instance. Depending on the memory allocation policy decided when the type was registered (through one of the g_type_register_* functions), the object's instance memory will be freed or returned to the object pool for this type. @@ -346,7 +346,7 @@ void g_object_run_dispose (GObject *object); The table below summarizes the destruction process of a GObject:
- <function>g_object_unref</function> + <function><link linkend="g-object-unref">g_object_unref</link></function> @@ -362,7 +362,7 @@ void g_object_run_dispose (GObject *object); - Last call to g_object_unref for an instance + Last call to g_object_unref for an instance of target type target type's dispose class function GObject instance @@ -376,7 +376,7 @@ void g_object_run_dispose (GObject *object); - Last call to g_object_unref for an instance + Last call to g_object_unref for an instance of target type target type's finalize class function @@ -392,28 +392,28 @@ void g_object_run_dispose (GObject *object); - Last call to g_object_unref for the last + Last call to g_object_unref for the last instance of target type interface' interface_finalize function On interface' vtable Never used in practice. Unlikely you will need it. - Last call to g_object_unreffor the last + Last call to g_object_unreffor the last instance of target type interface' base_finalize function On interface' vtable Never used in practice. Unlikely you will need it. - Last call to g_object_unref for the last + Last call to g_object_unref for the last instance of target type target type's class_finalize function On target type's class structure Never used in practice. Unlikely you will need it. - Last call to g_object_unref for the last + Last call to g_object_unref for the last instance of target type type's base_finalize function On the inheritance tree of classes from fundamental type to target type. @@ -432,7 +432,7 @@ void g_object_run_dispose (GObject *object); Weak References are used to monitor object finalization: - g_object_weak_ref adds a monitoring callback which does + g_object_weak_ref adds a monitoring callback which does not hold a reference to the object but which is invoked when the object runs its dispose method. As such, each weak ref can be invoked more than once upon object finalization (since dispose can run more than once during object @@ -440,13 +440,13 @@ void g_object_run_dispose (GObject *object); - g_object_weak_unref can be used to remove a monitoring + g_object_weak_unref can be used to remove a monitoring callback from the object. - Weak References are also used to implement g_object_add_weak_pointer - and g_object_remove_weak_pointer. These functions add a weak reference + Weak References are also used to implement g_object_add_weak_pointer + and g_object_remove_weak_pointer. These functions add a weak reference to the object they are applied to which makes sure to nullify the pointer given by the user when object is finalized. @@ -473,7 +473,7 @@ void g_object_run_dispose (GObject *object); This two-step destruction process is very useful to break reference counting cycles. While the detection of the cycles is up to the external code, once the cycles have been - detected, the external code can invoke g_object_dispose which + detected, the external code can invoke g_object_dispose which will indeed break any existing cycles since it will run the dispose handler associated to the object and thus release all references to other objects. @@ -483,7 +483,7 @@ void g_object_run_dispose (GObject *object); we stated a bit sooner: the dispose handler can be invoked multiple times. Let's say we have a reference count cycle: object A references B which itself references object A. Let's say we have detected the cycle and we want to destroy the two objects. One way to - do this would be to invoke g_object_dispose on one of the + do this would be to invoke g_object_dispose on one of the objects. @@ -512,7 +512,7 @@ void g_object_run_dispose (GObject *object); One of GObject's nice features is its generic get/set mechanism for object properties. When an object is instanciated, the object's class_init handler should be used to register - the object's properties with g_object_class_install_property + the object's properties with g_object_class_install_property (implemented in gobject.c). @@ -635,9 +635,9 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); - g_object_set_property first ensures a property + g_object_set_property first ensures a property with this name was registered in bar's class_init handler. If so, it calls - object_set_property which first walks the class hierarchy, + object_set_property which first walks the class hierarchy, from bottom, most derived type, to top, fundamental type to find the class which registered that property. It then tries to convert the user-provided GValue into a GValue whose type if that of the associated property. @@ -646,7 +646,7 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); If the user provides a signed char GValue, as is shown here, and if the object's property was registered as an unsigned int, - g_value_transform will try to transform the input signed char into + g_value_transform will try to transform the input signed char into an unsigned int. Of course, the success of the transformation depends on the availability of the required transform function. In practice, there will almost always be a transformation @@ -658,46 +658,46 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); - After transformation, the GValue is validated by - g_param_value_validate which makes sure the user's - data stored in the GValue matches the characteristics specified by - the property's GParamSpec. Here, the GParamSpec we + After transformation, the GValue is validated by + g_param_value_validate which makes sure the user's + data stored in the GValue matches the characteristics specified by + the property's GParamSpec. Here, the GParamSpec we provided in class_init has a validation function which makes sure that the GValue contains a value which respects the minimum and maximum bounds of the - GParamSpec. In the example above, the client's GValue does not + GParamSpec. In the example above, the client's GValue does not respect these constraints (it is set to 11, while the maximum is 10). As such, the - g_object_set_property function will return with an error. + g_object_set_property function will return with an error. - If the user's GValue had been set to a valid value, object_set_property + If the user's GValue had been set to a valid value, g_object_set_property would have proceeded with calling the object's set_property class method. Here, since our implementation of Foo did override this method, the code path would jump to foo_set_property after having retrieved from the - GParamSpec the param_id + GParamSpec the param_id It should be noted that the param_id used here need only to uniquely identify each - GParamSpec within the FooClass such that the switch + GParamSpec within the FooClass such that the switch used in the set and get methods actually works. Of course, this locally-unique integer is purely an optimization: it would have been possible to use a set of if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {} statements. which had been stored by - g_object_class_install_property. + g_object_class_install_property. Once the property has been set by the object's set_property class method, the code path - returns to g_object_set_property which calls - g_object_notify_queue_thaw. This function makes sure that + returns to g_object_set_property which calls + g_object_notify_queue_thaw. This function makes sure that the "notify" signal is emitted on the object's instance with the changed property as - parameter unless notifications were frozen by g_object_freeze_notify. + parameter unless notifications were frozen by g_object_freeze_notify. - g_object_thaw_notify can be used to re-enable notification of + g_object_thaw_notify can be used to re-enable notification of property modifications through the "notify" signal. It is important to remember that even if properties are changed while property change notification is frozen, the "notify" signal will be emitted once for each of these changed properties as soon as the property @@ -710,8 +710,8 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); - It is interesting to note that the g_object_set and - g_object_set_valist (vararg version) functions can be used to set + It is interesting to note that the g_object_set and + g_object_set_valist (vararg version) functions can be used to set multiple properties at once. The client code shown above can then be re-written as: MamanBar *foo; @@ -725,16 +725,16 @@ g_object_set (G_OBJECT (foo), - Of course, the _get versions are also available: g_object_get - and g_object_get_valist (vararg version) can be used to get numerous + Of course, the _get versions are also available: g_object_get + and g_object_get_valist (vararg version) can be used to get numerous properties at once. - Really attentive readers now understand how g_object_new, - g_object_newv and g_object_new_valist + Really attentive readers now understand how g_object_new, + g_object_newv and g_object_new_valist work: they parse the user-provided variable number of parameters and invoke - g_object_set on each pair of parameters only after the object has been successfully constructed. + g_object_set on each pair of parameters only after the object has been successfully constructed. Of course, the "notify" signal will be emitted for each property set. diff --git a/docs/reference/gobject/tut_gsignal.xml b/docs/reference/gobject/tut_gsignal.xml index d1b2f17..3779325 100644 --- a/docs/reference/gobject/tut_gsignal.xml +++ b/docs/reference/gobject/tut_gsignal.xml @@ -1,6 +1,6 @@ - Signals + The GObject messaging system Closures @@ -28,7 +28,7 @@ return_type function_callback (... , gpointer user_data); - The GClosure structure represents the common functionality of all + The GClosure structure represents the common functionality of all closure implementations: there exist a different Closure implementation for each separate runtime which wants to use the GObject type system. @@ -39,27 +39,27 @@ return_type function_callback (... , gpointer user_data); it behaves as a normal C object for GTK+ and as a normal Python object for python code. - The GObject library provides a simple GCClosure type which + The GObject library provides a simple GCClosure type which is a specific implementation of closures to be used with C/C++ callbacks. - A GClosure provides simple services: + A GClosure provides simple services: - Invocation (g_closure_invoke): this is what closures + Invocation (g_closure_invoke): this is what closures were created for: they hide the details of callback invocation from the callback invocator. Notification: the closure notifies listeners of certain events such as closure invocation, closure invalidation and closure finalization. Listeners - can be registered with g_closure_add_finalize_notifier - (finalization notification), g_closure_add_invalidate_notifier + can be registered with g_closure_add_finalize_notifier + (finalization notification), g_closure_add_invalidate_notifier (invalidation notification) and - g_closure_add_marshal_guards (invocation notification). + g_closure_add_marshal_guards (invocation notification). There exist symmetric de-registration functions for finalization and invalidation - events (g_closure_remove_finalize_notifier and - g_closure_remove_invalidate_notifier) but not for the invocation + events (g_closure_remove_finalize_notifier and + g_closure_remove_invalidate_notifier) but not for the invocation process. Closures are refcounted and notify listeners of their destruction in a two-stage @@ -74,8 +74,8 @@ return_type function_callback (... , gpointer user_data); If you are using C or C++ - to connect a callback to a given event, you will either use the simple GCClosures - which have a pretty minimal API or the even simpler g_signal_connect + to connect a callback to a given event, you will either use the simple GCClosures + which have a pretty minimal API or the even simpler g_signal_connect functions (which will be presented a bit later :). GClosure* g_cclosure_new (GCallback callback_func, @@ -90,16 +90,16 @@ GClosure* g_signal_type_cclosure_new (GType itype, - g_cclosure_new will create a new closure which can invoke the + g_cclosure_new will create a new closure which can invoke the user-provided callback_func with the user-provided user_data as last parameter. When the closure is finalized (second stage of the destruction process), it will invoke the destroy_data function if the user has supplied one. - g_cclosure_new_swap will create a new closure which can invoke the + g_cclosure_new_swap will create a new closure which can invoke the user-provided callback_func with the user-provided user_data as first parameter (instead of being the - last parameter as with g_cclosure_new). When the closure + last parameter as with g_cclosure_new). When the closure is finalized (second stage of the destruction process), it will invoke the destroy_data function if the user has supplied one. @@ -200,8 +200,8 @@ return_type function_callback (gpointer instance, ... , gpointer user_data); Signal registration - To register a new signal on an existing type, we can use any of g_signal_newv, - g_signal_new_valist or g_signal_new functions: + To register a new signal on an existing type, we can use any of g_signal_newv, + g_signal_new_valist or g_signal_new functions: guint g_signal_newv (const gchar *signal_name, GType itype, @@ -280,13 +280,13 @@ guint g_signal_newv (const gchar *signal_name, of a given signal on all the instances of the type which supports that signal. - You can use g_signal_override_class_closure which + You can use g_signal_override_class_closure which overrides the class_closure of a given type. It is possible to call this function only on a derived type of the type on which the signal was registered. This function is of use only to language bindings. - You can register a closure with the g_signal_connect + You can register a closure with the g_signal_connect family of functions. This is an instance-specific operation: the closure will be invoked only during emission of a given signal on a given instance. @@ -295,8 +295,8 @@ guint g_signal_newv (const gchar *signal_name, emission hooks are invoked whenever a given signal is emitted whatever the instance on which it is emitted. Emission hooks are used for example to get all mouse_clicked emissions in an application to be able to emit the small mouse click sound. - Emission hooks are connected with g_signal_add_emission_hook - and removed with g_signal_remove_emission_hook. + Emission hooks are connected with g_signal_add_emission_hook + and removed with g_signal_remove_emission_hook. @@ -308,7 +308,7 @@ guint g_signal_newv (const gchar *signal_name, Signal emission - Signal emission is done through the use of the g_signal_emit family + Signal emission is done through the use of the g_signal_emit family of functions. void g_signal_emitv (const GValue *instance_and_params, @@ -369,8 +369,8 @@ void g_signal_emitv (const GValue *instance_and_pa HANDLER_RUN_FIRST: if any closure were connected - with the g_signal_connect family of - functions, and if they are not blocked (with the g_signal_handler_block + with the g_signal_connect family of + functions, and if they are not blocked (with the g_signal_handler_block family of functions) they are run here, from first to last connected. Jump to RUN_LAST state. @@ -398,7 +398,7 @@ void g_signal_emitv (const GValue *instance_and_pa If, at any point during emission (except in RUN_CLEANUP state), one of the closures or emission hook stops the signal emission with - g_signal_stop, emission jumps to CLEANUP state. + g_signal_stop, emission jumps to CLEANUP state. @@ -416,7 +416,7 @@ void g_signal_emitv (const GValue *instance_and_pa If no accumulator function was provided, the value returned by the last handler - run will be returned by g_signal_emit. + run will be returned by g_signal_emit. @@ -432,11 +432,11 @@ void g_signal_emitv (const GValue *instance_and_pa Of the three main connection functions, - only one has an explicit detail parameter as a GQuark + only one has an explicit detail parameter as a GQuark A GQuark is an integer which uniquely represents a string. It is possible to transform back and forth between the integer and string representations with the functions - g_quark_from_string and g_quark_to_string. + g_quark_from_string and g_quark_to_string. : @@ -469,7 +469,7 @@ gulong g_signal_connect_data (gpointer instance, Of the four main signal emission functions, three have an explicit detail parameter as a - GQuark again: + GQuark again: void g_signal_emitv (const GValue *instance_and_params, guint signal_id, @@ -491,7 +491,7 @@ void g_signal_emit_by_name (gpointer instance, ...); The format of the detailed_signal parameter is exactly the same as the format used by - the g_signal_connect functions: signal_name::detail_name. + the g_signal_connect functions: signal_name::detail_name. diff --git a/docs/reference/gobject/tut_gtype.xml b/docs/reference/gobject/tut_gtype.xml index 791daad..b274a40 100644 --- a/docs/reference/gobject/tut_gtype.xml +++ b/docs/reference/gobject/tut_gtype.xml @@ -42,19 +42,19 @@ GType g_type_register_fundamental (GType type_id, - g_type_register_static and - g_type_register_fundamental + g_type_register_static and + g_type_register_fundamental are the C functions, defined in gtype.h and implemented in gtype.c - which you should use to register a new type in the program's type system. + which you should use to register a new GType in the program's type system. It is not likely you will ever need to use - g_type_register_fundamental (you have to be Tim Janik + g_type_register_fundamental (you have to be Tim Janik to do that) but in case you want to, the last chapter explains how to create new fundamental types. Please, note that there exist another registration function: the - g_type_register_dynamic. We will not discuss this + g_type_register_dynamic. We will not discuss this function here since its use is very similar to the _static version. @@ -64,7 +64,7 @@ GType g_type_register_fundamental (GType type_id, Fundamental types are top-level types which do not derive from any other type while other non-fundamental types derive from other types. - Upon initialization by g_type_init, the type system not + Upon initialization by g_type_init, the type system not only initializes its internal data structures but it also registers a number of core types: some of these are fundamental types. Others are types derived from these fundamental types. @@ -74,37 +74,37 @@ GType g_type_register_fundamental (GType type_id, Fundamental and non-Fundamental types are defined by: - class size: the class_size field in GTypeInfo. + class size: the class_size field in GTypeInfo. class initialization functions (C++ constructor): the base_init and - class_init fields in GTypeInfo. + class_init fields in GTypeInfo. class destruction functions (C++ destructor): the base_finalize and - class_finalize fields in GTypeInfo. + class_finalize fields in GTypeInfo. instance size (C++ parameter to new): the instance_size field in - GTypeInfo. + GTypeInfo. instanciation policy (C++ type of new operator): the n_preallocs - field in GTypeInfo. + field in GTypeInfo. copy functions (C++ copy operators): the value_table field in - GTypeInfo. + GTypeInfo. - XXX: GTypeFlags. + XXX: GTypeFlags. - Fundamental types are also defined by a set of GTypeFundamentalFlags - which are stored in a GTypeFundamentalInfo. + Fundamental types are also defined by a set of GTypeFundamentalFlags + which are stored in a GTypeFundamentalInfo. Non-Fundamental types are furthermore defined by the type of their parent which is - passed as the parent_type parameter to g_type_register_static - and g_type_register_dynamic. + passed as the parent_type parameter to g_type_register_static + and g_type_register_dynamic. @@ -117,17 +117,17 @@ GType g_type_register_fundamental (GType type_id, - The GValue structure is used as an abstract container for all of these + The GValue structure is used as an abstract container for all of these types. Its simplistic API (defined in gobject/gvalue.h) can be used to invoke the value_table functions registered - during type registration: for example g_value_copy copies the - content of a GValue to another GValue. This is similar + during type registration: for example g_value_copy copies the + content of a GValue to another GValue. This is similar to a C++ assignment which invokes the C++ copy operator to modify the default bit-by-bit copy semantics of C++/C structures/classes. - The following code shows how you can copy around a 64 bit integer, as well as a GObject + The following code shows how you can copy around a 64 bit integer, as well as a GObject instance pointer (sample code for this is located in the source tarball for this document in sample/gtype/test.c): @@ -322,7 +322,7 @@ GType maman_bar_get_type (void) To register such a type in the type system, you just need to fill the - GTypeInfo structure with zeros since these types are also most of the time + GTypeInfo structure with zeros since these types are also most of the time fundamental: GTypeInfo info = { @@ -356,9 +356,9 @@ GType maman_bar_get_type (void) Having non-instantiable types might seem a bit useless: what good is a type if you cannot instanciate an instance of that type ? Most of these types - are used in conjunction with GValues: a GValue is initialized + are used in conjunction with GValues: a GValue is initialized with an integer or a string and it is passed around by using the registered - type's value_table. GValues (and by extension these trivial fundamental + type's value_table. GValues (and by extension these trivial fundamental types) are most useful when used in conjunction with object properties and signals. @@ -370,7 +370,7 @@ GType maman_bar_get_type (void) Types which are registered with a class and are declared instantiable are what most closely resembles an object. - Although GObjects (detailed in ) + Although GObjects (detailed in ) are the most well known type of instantiable classed types, other kinds of similar objects used as the base of an inheritance hierarchy have been externally developped and they are all built on the fundamental @@ -428,8 +428,8 @@ maman_bar_get_type (void) Every object must define two structures: its class structure and its instance structure. All class structures must contain as first member - a GTypeClass structure. All instance structures must contain as first - member a GTypeInstance structure. The declaration of these C types, + a GTypeClass structure. All instance structures must contain as first + member a GTypeInstance structure. The declaration of these C types, coming from gtype.h is shown below: struct _GTypeClass @@ -496,12 +496,12 @@ B *b; Instanciation of these types can be done with - g_type_create_instance: + g_type_create_instance: GTypeInstance* g_type_create_instance (GType type); void g_type_free_instance (GTypeInstance *instance); - g_type_create_instance will lookup the type information + g_type_create_instance will lookup the type information structure associated to the type requested. Then, the instance size and instanciation policy (if the n_preallocs field is set to a non-zero value, the type system allocates the object's instance structures in chunks rather than mallocing for every instance) @@ -514,9 +514,9 @@ void g_type_free_instance (GTypeInstance *instance); a class structure: it allocates a buffer to hold the object's class structure and initializes it. It first copies the parent's class structure over this structure (if there is no parent, it initializes it to zero). It then invokes the - base_class_initialization functions (GBaseInitFunc) from topmost + base_class_initialization functions (GBaseInitFunc) from topmost fundamental object to bottom-most most derived object. The object's class_init - (GClassInitFunc) function is invoked afterwards to complete + (GClassInitFunc) function is invoked afterwards to complete initialization of the class structure. Finally, the object's interfaces are initialized (we will discuss interface initialization in more detail later). @@ -531,12 +531,12 @@ The class initialization process is entirely implemented in Once the type system has a pointer to an initialized class structure, it sets the object's instance class pointer to the object's class structure and invokes the object's - instance_init (GInstanceInitFunc)functions, from top-most fundamental + instance_init (GInstanceInitFunc)functions, from top-most fundamental type to bottom-most most derived type. - Object instance destruction through g_type_free_instance is very simple: + Object instance destruction through g_type_free_instance is very simple: the instance structure is returned to the instance pool if there is one and if this was the last living instance of the object, the class is destroyed. @@ -552,8 +552,8 @@ The class initialization process is entirely implemented in in Gtype) is the symmetric process of the initialization: interfaces are destroyed first. Then, the most derived - class_finalize (ClassFinalizeFunc) function is invoked. The - base_class_finalize (GBaseFinalizeFunc) functions are + class_finalize (ClassFinalizeFunc) function is invoked. The + base_class_finalize (GBaseFinalizeFunc) functions are Finally invoked from bottom-most most-derived type to top-most fundamental type and the class structure is freed. @@ -597,39 +597,39 @@ The class initialization process is entirely implemented in - First call to g_type_create_instance for target type + First call to g_type_create_instance for target type type's base_init function On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. - First call to g_type_create_instance for target type + First call to g_type_create_instance for target type target type's class_init function On target type's class structure - First call to g_type_create_instance for target type + First call to g_type_create_instance for target type interface initialization, see - Each call to g_type_create_instance for target type + Each call to g_type_create_instance for target type target type's instance_init function On object's instance - Last call to g_type_free_instance for target type + Last call to g_type_free_instance for target type interface destruction, see - Last call to g_type_free_instance for target type + Last call to g_type_free_instance for target type target type's class_finalize function On target type's class structure - Last call to g_type_free_instance for target type + Last call to g_type_free_instance for target type type's base_finalize function On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. @@ -647,7 +647,7 @@ The class initialization process is entirely implemented in GType's Interfaces are very similar to Java's interfaces. To declare one of these you have to register a non-instantiable classed type which derives from - GTypeInterface. The following piece of code declares such an interface. + GTypeInterface. The following piece of code declares such an interface. #define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ()) #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_IBAZ_TYPE, MamanIbaz)) @@ -684,7 +684,7 @@ void maman_ibaz_do_action (MamanIbaz *self) An interface is defined by only one structure which must contain as first member - a GTypeInterface structure. The interface structure is expected to + a GTypeInterface structure. The interface structure is expected to contain the function pointers of the interface methods. It is good style to define helper functions for each of the interface methods which simply call the interface' method directly: maman_ibaz_do_action @@ -694,7 +694,7 @@ void maman_ibaz_do_action (MamanIbaz *self) Once an interface type is registered, you must register implementations for these interfaces. The function named maman_baz_get_type registers - a new GType named MamanBaz which inherits from GObject and which + a new GType named MamanBaz which inherits from GObject and which implements the interface MamanIBaz. static void maman_baz_do_action (MamanIbaz *self) @@ -745,10 +745,11 @@ maman_baz_get_type (void) - g_type_add_interface_static records in the type system that + g_type_add_interface_static records in the type system that a given type implements also FooInterface (foo_interface_get_type returns the type of - FooInterface). The GInterfaceInfo structure holds + FooInterface). + The GInterfaceInfo structure holds information about the implementation of the interface: struct _GInterfaceInfo @@ -819,7 +820,7 @@ maman_ibaz_base_init (gpointer g_class) The above process can be summarized as follows:
- <function>Interface Initialization</function> + Interface Initialization @@ -835,7 +836,7 @@ maman_ibaz_base_init (gpointer g_class) - First call to g_type_create_instance for type + First call to g_type_create_instance for type implementing interface interface' base_init function On interface' vtable @@ -844,7 +845,7 @@ maman_ibaz_base_init (gpointer g_class) twice.). - First call to g_type_create_instance for type + First call to g_type_create_instance for type implementing interface interface' interface_init function On interface' vtable @@ -891,7 +892,7 @@ maman_ibaz_base_init (gpointer g_class) The above process can be summarized as follows:
- <function>Interface Finalization</function> + Interface Finalization @@ -906,13 +907,13 @@ maman_ibaz_base_init (gpointer g_class) - Last call to g_type_free_instance for type + Last call to g_type_free_instance for type implementing interface interface' interface_finalize function On interface' vtable - Last call to g_type_free_instancefor type + Last call to g_type_free_instancefor type implementing interface interface' base_finalize function On interface' vtable diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index 73e2b4d..937ff7a 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -1,17 +1,16 @@ - - How To ? - + This chapter tries to answer the real-life questions of users and presents the most common scenario use-cases I could come up with. The use-cases are presented from most likely to less likely. + - + How To define and implement a new GObject ? @@ -23,13 +22,13 @@ sample/gobject directory: maman-bar.{h|c}: this is the source for a object which derives from - GObject and which shows how to declare different types of methods on the object. + GObject and which shows how to declare different types of methods on the object. maman-subbar.{h|c}: this is the source for a object which derives from MamanBar and which shows how to override some of its parent's methods. maman-foo.{h|c}: this is the source for an object which derives from - GObject and which declares a signal. + GObject and which declares a signal. test.c: this is the main source which instantiates an instance of type and exercises their API. @@ -37,7 +36,7 @@ - + Boilerplate header code @@ -186,7 +185,7 @@ static void maman_bar_init(GTypeInstance *instance, gpointer g_class) { A similar alternative, available since Glib version 2.4, is to define a private structure in the .c file, declare it as a private structure in class_init using - g_type_class_add_private and declare a macro to allow convenient access to this structure. + g_type_class_add_private and declare a macro to allow convenient access to this structure. A private structure will then be attached to each newly created object by the GObject system. You dont need to free or allocate the private structure, only the objects or pointers that it may contain. @@ -238,9 +237,9 @@ maman_bar_get_private_field (MamanBar *self) - + - + Boilerplate code @@ -297,9 +296,9 @@ maman_bar_get_type (void) } - + - + Object Construction @@ -320,7 +319,7 @@ maman_bar_get_type (void) Construction properties will be set only after all instance_init functions have run. - No object reference will be returned to the client of g_object_new> + No object reference will be returned to the client of g_object_new> until all the construction properties have been set. @@ -343,14 +342,14 @@ maman_bar_init (GTypeInstance *instance, And make sure that you set maman_bar_init as the type's instance_init function in maman_bar_get_type. Make sure the code builds and runs: create an instance of the object and make sure maman_bar_init is called (add a - g_print call in it). + g_print call in it). Now, if you need special construction properties, install the properties in the class_init function, override the set and get methods and implement the get and set methods as described in . Make sure that these properties use a construct only - GParamSpec by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps + GParamSpec by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps GType ensure that these properties are not set again later by malicious user code. static void @@ -375,7 +374,7 @@ bar_class_init (MamanBarClass *klass) If you need this, make sure you can build and run code similar to the code shown above. Make sure your construct properties can set correctly during construction, make sure you cannot set them - afterwards and make sure that if your users do not call g_object_new + afterwards and make sure that if your users do not call g_object_new with the required construction properties, these will be initialized with the default values. @@ -392,14 +391,14 @@ bar_class_init (MamanBarClass *klass) use of this feature. As such, to initialize your object instances, use by default the base_init function and construction properties. - + - + Object Destruction Again, it is often difficult to figure out which mechanism to use to hook into the object's - destruction process: when the last g_object_unref function call is made, + destruction process: when the last g_object_unref function call is made, a lot of things happen as described in . @@ -487,9 +486,9 @@ if (self->private->dispose_has_run) { } - + - + Object methods @@ -511,7 +510,7 @@ if (self->private->dispose_has_run) { - + Non-virtual public methods @@ -530,9 +529,9 @@ void maman_bar_do_action (MamanBar *self, /* parameters */) There is really nothing scary about this. - + - + Virtual public methods @@ -606,9 +605,9 @@ void maman_bar_do_action_two (MamanBar *self, /* parameters */) } - + - + Virtual private Methods @@ -674,10 +673,10 @@ maman_bar_subtype_class_init (MamanBarSubTypeClass *klass) } - - + + - + Chaining up Chaining up is often loosely defined by the following set of conditions: @@ -720,7 +719,7 @@ maman_bar_subtype_class_init (MamanBarSubTypeClass *klass) - The function g_type_class_peek_parent is used to access the original parent + The function g_type_class_peek_parent is used to access the original parent class structure. Its input is a pointer to the class of the derived object and it returns a pointer to the original parent class structure. The code below shows how you could use it: @@ -738,14 +737,14 @@ b_method_to_call (B *obj, int a) } A lot of people who use this idiom in GTK+ store the parent class structure pointer in a global static - variable to avoid the costly call to g_type_class_peek_parent for each function call. + variable to avoid the costly call to g_type_class_peek_parent for each function call. Typically, the class_init callback initializes the global static variable. gtk/gtkhscale.c does this. - + - + - + How To define and implement Interfaces ? - + How To define Interfaces ? @@ -800,8 +799,8 @@ void maman_ibaz_do_action (MamanIbaz *self); #endif /*MAMAN_IBAZ_H*/ - This code is almost exactly similar to the code for a normal GType - which derives from a GObject except for a few details: + This code is almost exactly similar to the code for a normal GType + which derives from a GObject except for a few details: The _GET_CLASS macro is not implemented with @@ -870,9 +869,9 @@ void maman_ibaz_do_action (MamanIbaz *self) } - + - + How To define and implement an implementation of an Interface ? @@ -954,8 +953,8 @@ maman_baz_get_type (void) } This function is very much like all the similar functions we looked at previously. The only interface-specific - code present here is the call to g_type_add_interface_static which is used to inform - the type system that this just-registered GType also implements the interface + code present here is the call to g_type_add_interface_static which is used to inform + the type system that this just-registered GType also implements the interface MAMAN_TYPE_IBAZ. @@ -986,9 +985,9 @@ baz_instance_init (GTypeInstance *instance, but it could :) - + - + Interface definition prerequisites To specify that an interface requires the presence of other interfaces when implemented, @@ -1085,7 +1084,7 @@ maman_bar_get_type (void) } It is very important to notice that the order in which interface implementations are added to the main object - is not random: g_type_interface_static must be invoked first on the interfaces which have + is not random: g_type_add_interface_static must be invoked first on the interfaces which have no prerequisites and then on the others. @@ -1095,16 +1094,16 @@ maman_bar_get_type (void) and sample/interface/maman-bar.{h|c}. - + - + Interface Properties Starting from version 2.4 of glib, gobject interfaces can also have properties. Declaration of the interface properties is similar to declaring the properties of ordinary gobject types as explained in , - except that g_object_interface_install_property is used to - declare the properties instead of g_object_class_install_property. + except that g_object_interface_install_property is used to + declare the properties instead of g_object_class_install_property. To include a property named 'name' of type string in the @@ -1150,8 +1149,8 @@ maman_ibaz_base_init (gpointer g_class) An implementer shall declare and define it's properties in the usual way as explained in , except for one small change: it shall declare the properties of the interface it implements using - g_object_class_override_property instead of - g_object_class_install_property. The following code snipet + g_object_class_override_property instead of + g_object_class_install_property. The following code snipet shows the modifications needed in the MamanBaz declaration and implementation above: @@ -1260,10 +1259,10 @@ maman_baz_get_property (GObject * object, guint prop_id, - + - + - + Howto create and use signals @@ -1292,7 +1291,7 @@ maman_baz_get_property (GObject * object, guint prop_id, just emit events which can be received by numerous clients. - + Simple use of signals The most basic use of signals is to implement simple event notification: for example, if we have a @@ -1352,10 +1351,10 @@ The header gobject/gmarshal.h defines a set of commonly needed closures that one can use. - + - + How to provide more flexibility to users ? The previous implementation does the job but the signal facility of GObject can be used to provide @@ -1440,8 +1439,8 @@ void maman_file_complex_write (MamanFileComplex *self, guint8 *buffer, guint siz The client code (as shown in sample/signal/test.c and below) can now connect signal handlers before and after the file write is completed: since the default signal handler which does the write itself runs during the -RUN_LAST phase of the signal emission, it will run after all handlers connected with g_signal_connect -and before all handlers connected with g_signal_connect_after. If you intent to write a GObject +RUN_LAST phase of the signal emission, it will run after all handlers connected with g_signal_connect +and before all handlers connected with g_signal_connect_after. If you intent to write a GObject which emits signals, I would thus urge you to create all your signals with the G_SIGNAL_RUN_LAST such that your users have a maximum of flexibility as to when to get the event. Here, we combined it with G_SIGNAL_NO_RECURSE and G_SIGNAL_NO_HOOKS to ensure our users will not try to do really weird things with our GObject. I strongly advise you @@ -1492,7 +1491,7 @@ Complex Write event after: 0xbfffe280, 50 - + How most people do the same thing with less code For many historic reasons related to how the ancestor of GObject used to work in GTK+ 1.x versions, @@ -1510,13 +1509,13 @@ Complex Write event after: 0xbfffe280, 50 way to create a signal with a default handler than to create - a closure by hand and to use the g_signal_newv. + a closure by hand and to use the g_signal_newv. - For example, g_signal_new can be used to create a signal which uses a default + For example, g_signal_new can be used to create a signal which uses a default handler which is stored in the class structure of the object. More specifically, the class structure contains a function pointer which is accessed during signal emission to invoke the default handler and - the user is expected to provide to g_signal_new the offset from the start of the + the user is expected to provide to g_signal_new the offset from the start of the class structure to the function pointer. I would like to point out here that the reason why the default handler of a signal is named everywhere @@ -1550,7 +1549,7 @@ maman_file_simple_class_init (gpointer g_class, klass->write = default_write_signal_handler; - Finally, the signal is created with g_signal_new in the same class_init function: + Finally, the signal is created with g_signal_new in the same class_init function: klass->write_signal_id = g_signal_new ("write", @@ -1565,7 +1564,7 @@ klass->write_signal_id = G_TYPE_POINTER, G_TYPE_UINT); - Of note, here, is the 4th argument to the function: it is an integer calculated by the G_STRUCT_OFFSET + Of note, here, is the 4th argument to the function: it is an integer calculated by the G_STRUCT_OFFSET macro which indicates the offset of the member write from the start of the MamanFileSimpleClass class structure. @@ -1586,24 +1585,24 @@ klass->write_signal_id = If you have doubts about which method to use, I would advise you to use the second one which - involves g_signal_new rather than g_signal_newv: + involves g_signal_new rather than g_signal_newv: it is better to write code which looks like the vast majority of other GTK+/Gobject code than to do it your own way. However, now, you know why. - + - + - + How users can abuse signals (and why some think it is good) Now that you know how to create signals to which the users can connect easily and at any point in - the signal emission process thanks to g_signal_connect, - g_signal_connect_after and G_SIGNAL_RUN_LAST, it is time to look into how your + the signal emission process thanks to g_signal_connect, + g_signal_connect_after and G_SIGNAL_RUN_LAST, it is time to look into how your users can and will screw you. This is also interesting to know how you too, can screw other people. This will make you feel good and eleet. @@ -1625,7 +1624,7 @@ klass->write_signal_id = If all you want to do is to stop the signal emission from one of the callbacks you connected yourself, - you can call g_signal_stop_by_name. Its use is very simple which is why I won't detail + you can call g_signal_stop_by_name. Its use is very simple which is why I won't detail it further. @@ -1640,12 +1639,12 @@ klass->write_signal_id = which is why I won't bother to show exactly how to do it here again. - - + + - - - - - - +--> diff --git a/docs/reference/gobject/tut_intro.xml b/docs/reference/gobject/tut_intro.xml index c53f030..fdd58fb 100644 --- a/docs/reference/gobject/tut_intro.xml +++ b/docs/reference/gobject/tut_intro.xml @@ -1,5 +1,5 @@ -Introduction +Background GObject, and its lower-level type system, GType, are used by GTK+ and most Gnome libraries to @@ -18,7 +18,7 @@ the solution choosen by GLib. The following chapters go into greater detail into how GType and GObject work and -how you can use them as a C programmer. I personally find it useful to keep in mind that +how you can use them as a C programmer. It is useful to keep in mind that allowing access to C objects from other interpreted languages was one of the major design goals: this can often explain the sometimes rather convoluted APIs and features present in this library. diff --git a/docs/reference/gobject/tut_tools.xml b/docs/reference/gobject/tut_tools.xml index 266e415..a68e318 100644 --- a/docs/reference/gobject/tut_tools.xml +++ b/docs/reference/gobject/tut_tools.xml @@ -1,35 +1,55 @@ - - GObject related tools + + + Several useful developer tools have been build around GObject technology. + Next sections briefly introduce them and link to the respective project pages. + + - - Debugging reference count problems - - - The reference counting scheme used by GObject does solve quite - a few memory management problems but also introduces new sources of bugs. - In large applications, finding the exact spot where a the reference count - of an Object is not properly handled can be very difficult. Hopefully, - there exist at a too named refdbg/ - which can be used to automate the task of tracking down the location - of invalid code with regard to reference counting. This application - intercepts the reference counting calls and tries to detect invalid behavior. - It suports a filter-rule mechanism to let you trace only the objects you are - interested in and it can be used together with gdb. - - + + GObject builder + + + Writing gobjects can be a tedious task. It requires a lot of typing and just + doing copy and paste needs care. On obvious idea is to use some sort of + templates for the class skelletons. Then a tool could generate the real c + files from them. + GOB/ (or GOB2) is suc + h a tool. It is a preprocessor for making GObjects with inline C code so + that generated files are not edited. + Syntax is inspired by Java and Yacc or Lex. The implementation is + intentionally kept simple, and no C actual code parsing is done. + + + + + Debugging reference count problems + + + The reference counting scheme used by GObject does solve quite + a few memory management problems but also introduces new sources of bugs. + In large applications, finding the exact spot where a the reference count + of an Object is not properly handled can be very difficult. Hopefully, + there exist at a too named refdbg/ + which can be used to automate the task of tracking down the location + of invalid code with regard to reference counting. This application + intercepts the reference counting calls and tries to detect invalid behavior. + It suports a filter-rule mechanism to let you trace only the objects you are + interested in and it can be used together with gdb. + + - - Writing API docs + + Writing API docs - The API documentation for most of the Glib, GObject, GTK+ and GNOME - libraries is built with a combination of complex tools. Typically, the part of - the documentation which describes the behavior of each function is extracted - from the specially-formatted source code comments by a tool named gtk-doc which - generates docbook xml and merges this docbook xml with a set of master xml - docbook files. These xml docbook files are finally processed with xsltproc - (a small program part of the libxslt library) to generate the final html - output. Other tools can be used to generate pdf output from the source xml. - The following code excerpt shows what these comments look like. + The API documentation for most of the Glib, GObject, GTK+ and GNOME + libraries is built with a combination of complex tools. Typically, the part of + the documentation which describes the behavior of each function is extracted + from the specially-formatted source code comments by a tool named gtk-doc which + generates docbook xml and merges this docbook xml with a set of master xml + docbook files. These xml docbook files are finally processed with xsltproc + (a small program part of the libxslt library) to generate the final html + output. Other tools can be used to generate pdf output from the source xml. + The following code excerpt shows what these comments look like. /** * gtk_widget_freeze_child_notify: @@ -45,14 +65,12 @@ gtk_widget_freeze_child_notify (GtkWidget *widget) { ... - - - The great thoroughful - documentation - on how to setup and use gtk-doc in your - project is provided on the gnome developer website. - gtk-doc generates - - - + + + The great thoroughful + documentation + on how to setup and use gtk-doc in your + project is provided on the gnome developer website. + gtk-doc generates +