mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-14 05:16:18 +01:00
515f42c9ed
2007-11-13 Cody Russell <bratsche@gnome.org>
* docs/reference/gobject/gobject-docs.sgml:
* docs/reference/gobject/tut_gsignal.xml:
* docs/reference/gobject/tut_gtype.xml:
* docs/reference/gobject/tut_intro.xml:
* docs/reference/gobject/tut_tools.xml:
* docs/reference/gobject/tut_howto.xml:
* docs/reference/gobject/tut_gobject.xml: Documentation fixes.
Recommend macro type names such as NAUTILUS_TYPE_WINDOW (not
NAUTILUS_WINDOW_TYPE). Fixed text which erroneously stated that
superclass initializers don't run when an object is
instantiated. Fixed numerous spelling mistakes. Minor grammar
edits. (#490637, Adam Dingle)
svn path=/trunk/; revision=5857
101 lines
4.0 KiB
XML
101 lines
4.0 KiB
XML
<?xml version='1.0' encoding="ISO-8859-1"?>
|
|
<partintro>
|
|
<para>
|
|
Several useful developer tools have been build around GObject technology.
|
|
The next sections briefly introduce them and link to the respective project pages.
|
|
</para>
|
|
</partintro>
|
|
|
|
<chapter id="tools-gob">
|
|
<title>GObject builder</title>
|
|
|
|
<para>
|
|
Writing GObjects can be a tedious task. It requires a lot of typing and just
|
|
doing a copy/paste requires a great deal of care.
|
|
One obvious idea is to use some sort of templates for the class skeletons.
|
|
and then run them through a special tool to generate the real C files.
|
|
<ulink url="http://www.5z.com/jirka/gob.html">GOB/</ulink> (or GOB2) is such
|
|
a tool. It is a preprocessor which can be used to build GObjects
|
|
with inline C code so that there is no need to edit the generated C code.
|
|
The syntax is inspired by Java and Yacc or Lex. The implementation is
|
|
intentionally kept simple: the inline C code provided by the user
|
|
is not parsed.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="tools-ginspector">
|
|
<title>Graphical inspection of GObjects</title>
|
|
|
|
<para>
|
|
Yet another tool that you may find helpful when working with
|
|
GObjects is <ulink
|
|
url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
|
|
is able to display GLib/GTK+ objects and their properties.
|
|
</para>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="tools-refdb">
|
|
<title>Debugging reference count problems</title>
|
|
|
|
<para>
|
|
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 the reference count
|
|
of an Object is not properly handled can be very difficult. Hopefully,
|
|
there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg/</ulink>
|
|
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 supports a filter-rule mechanism to let you trace only the objects you are
|
|
interested in and it can be used together with GDB.
|
|
</para>
|
|
<para>
|
|
<indexterm><primary>g_trap_object_ref</primary></indexterm>
|
|
Note that if GObject has been compiled with <option>--enable-debug=yes</option>,
|
|
it exports a trap variable
|
|
<programlisting>
|
|
static volatile GObject *g_trap_object_ref;
|
|
</programlisting>
|
|
If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>()
|
|
and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted
|
|
when called with that value.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="tools-gtkdoc">
|
|
<title>Writing API docs</title>
|
|
|
|
<para>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.
|
|
<programlisting>
|
|
/**
|
|
* gtk_widget_freeze_child_notify:
|
|
* @widget: a #GtkWidget
|
|
*
|
|
* Stops emission of "child-notify" signals on @widget. The signals are
|
|
* queued until gtk_widget_thaw_child_notify() is called on @widget.
|
|
*
|
|
* This is the analogue of g_object_freeze_notify() for child properties.
|
|
**/
|
|
void
|
|
gtk_widget_freeze_child_notify (GtkWidget *widget)
|
|
{
|
|
...
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Thorough
|
|
<ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink>
|
|
on how to set up and use gtk-doc in your
|
|
project is provided on the GNOME developer website.
|
|
</para>
|
|
</chapter>
|