Commit 157d618d authored by Javier Jardón's avatar Javier Jardón

Move documentation to inline comments: GtkObject

parent 3d481f73
......@@ -3,6 +3,7 @@ gtkbox.sgml
gtkbuilder.sgml
gtkhbox.sgml
gtkmessagedialog.sgml
gtkobject.sgml
gtkorientable.sgml
gtkpagesetupunixdialog.sgml
gtkseparator.sgml
......
<!-- ##### SECTION Title ##### -->
GtkObject
<!-- ##### SECTION Short_Description ##### -->
The base class of the GTK+ type hierarchy
<!-- ##### SECTION Long_Description ##### -->
<refsect2>
<title>Description</title>
<para>
#GtkObject is the base class for all widgets, and for a few
non-widget objects such as #GtkAdjustment. #GtkObject predates
#GObject; non-widgets that derive from #GtkObject rather than
#GObject do so for backward compatibility reasons.
</para>
<para>
#GtkObject<!-- -->s are created with a "floating" reference count.
This means that the initial reference is not owned by anyone. Calling
g_object_unref() on a newly-created #GtkObject is incorrect, the floating
reference has to be removed first. This can be done by anyone at any time,
by calling g_object_ref_sink() to convert the floating reference into a
regular reference. g_object_ref_sink() returns a new reference if an object
is already sunk (has no floating reference).
</para>
<para>
When you add a widget to its parent container, the parent container
will do this:
<informalexample><programlisting>
g_object_ref_sink (G_OBJECT (child_widget));
</programlisting></informalexample>
This means that the container now owns a reference to the child widget
and the child widget has no floating reference.
</para>
<para>
The purpose of the floating reference is to keep the child widget alive
until you add it to a parent container:
<informalexample><programlisting>
button = gtk_button_new (<!-- -->);
/* button has one floating reference to keep it alive */
gtk_container_add (GTK_CONTAINER (container), button);
/* button has one non-floating reference owned by the container */
</programlisting></informalexample>
</para>
<para>
#GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
That is, after calling gtk_window_new(), the #GtkWindow will have one
reference which is owned by GTK+, and no floating references.
</para>
<para>
One more factor comes into play: the "destroy" signal, emitted by the
gtk_object_destroy() method. The "destroy" signal asks all code owning a
reference to an object to release said reference. So, for example, if you call
gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
be removed from its parent container and the parent container will release its
reference to the button. Because these references are released, calling
gtk_object_destroy() should result in freeing all memory associated with an
object, unless some buggy code fails to release its references in response to
the "destroy" signal. Freeing memory (referred to as
<firstterm>finalization</firstterm> only happens if the reference count reaches
zero.
</para>
<para>
Some simple rules for handling #GtkObject:
<itemizedlist>
<listitem><para>
Never call g_object_unref() unless you have previously called g_object_ref(),
even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
true for #GObject; for #GObject, the creator of the object owns a reference.)
</para></listitem>
<listitem><para>
Call gtk_object_destroy() to get rid of most objects in most cases.
In particular, widgets are almost always destroyed in this way.
</para></listitem>
<listitem><para> Because of the floating reference count, you don't need to
worry about reference counting for widgets and toplevel windows, unless you
explicitly call g_object_ref() yourself.</para></listitem>
</itemizedlist>
</para>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
#GObject
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### STRUCT GtkObject ##### -->
<para>
The object itself. You should never use these members directly -
use the accessing macros instead.
</para>
<!-- ##### SIGNAL GtkObject::destroy ##### -->
<para>
Signals that all holders of a reference to the #GtkObject should release
the reference that they hold. May result in finalization of the object
if all references are released.
</para>
@object: the object which received the signal.
<!-- ##### ENUM GtkObjectFlags ##### -->
<para>
Tells about the state of the object.
</para>
@GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
internally by GTK+ to prevent reinvokations during destruction.
@GTK_RESERVED_1:
@GTK_RESERVED_2: reserved for future use
<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
<para>
Gets the #GtkObjectFlags for an object without directly
accessing its members.
</para>
@obj: the object whose flags are returned.
<!-- ##### FUNCTION gtk_object_destroy ##### -->
<para>
Emits the "destroy" signal notifying all reference holders that they should
release the #GtkObject. See the overview documentation at the top of the
page for more details.
</para>
<para>
The memory for the object itself won't be deleted until
its reference count actually drops to 0; gtk_object_destroy() merely asks
reference holders to release their references, it does not free the object.
</para>
@object: the object to destroy.
......@@ -38,6 +38,77 @@
#include "gtkalias.h"
/**
* SECTION:gtkobject
* @Short_description: The base class of the GTK+ type hierarchy
* @Title: GtkObject
* @See_also:#GObject
*
* #GtkObject is the base class for all widgets, and for a few
* non-widget objects such as #GtkAdjustment. #GtkObject predates
* #GObject; non-widgets that derive from #GtkObject rather than
* #GObject do so for backward compatibility reasons.
*
* #GtkObject<!-- -->s are created with a "floating" reference count.
* This means that the initial reference is not owned by anyone. Calling
* g_object_unref() on a newly-created #GtkObject is incorrect, the floating
* reference has to be removed first. This can be done by anyone at any time,
* by calling g_object_ref_sink() to convert the floating reference into a
* regular reference. g_object_ref_sink() returns a new reference if an object
* is already sunk (has no floating reference).
*
* When you add a widget to its parent container, the parent container
* will do this:
* <informalexample><programlisting>
* g_object_ref_sink (G_OBJECT (child_widget));
* </programlisting></informalexample>
* This means that the container now owns a reference to the child widget
* and the child widget has no floating reference.
*
* The purpose of the floating reference is to keep the child widget alive
* until you add it to a parent container:
* <informalexample><programlisting>
* button = gtk_button_new (<!-- -->);
* /&ast; button has one floating reference to keep it alive &ast;/
* gtk_container_add (GTK_CONTAINER (container), button);
* /&ast; button has one non-floating reference owned by the container &ast;/
* </programlisting></informalexample>
*
* #GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
* That is, after calling gtk_window_new(), the #GtkWindow will have one
* reference which is owned by GTK+, and no floating references.
*
* One more factor comes into play: the #GtkObject::destroy signal, emitted by the
* gtk_object_destroy() method. The #GtkObject::destroy signal asks all code owning a
* reference to an object to release said reference. So, for example, if you call
* gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
* it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
* be removed from its parent container and the parent container will release its
* reference to the button. Because these references are released, calling
* gtk_object_destroy() should result in freeing all memory associated with an
* object, unless some buggy code fails to release its references in response to
* the #GtkObject::destroy signal. Freeing memory (referred to as
* <firstterm>finalization</firstterm>) only happens if the reference count reaches
* zero.
*
* Some simple rules for handling #GtkObject:
* <itemizedlist>
* <listitem><para>
* Never call g_object_unref() unless you have previously called g_object_ref(),
* even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
* true for #GObject; for #GObject, the creator of the object owns a reference.)
* </para></listitem>
* <listitem><para>
* Call gtk_object_destroy() to get rid of most objects in most cases.
* In particular, widgets are almost always destroyed in this way.
* </para></listitem>
* <listitem><para> Because of the floating reference count, you don't need to
* worry about reference counting for widgets and toplevel windows, unless you
* explicitly call g_object_ref() yourself.</para></listitem>
* </itemizedlist>
*/
enum {
DESTROY,
LAST_SIGNAL
......@@ -112,6 +183,14 @@ gtk_object_class_init (GtkObjectClass *class)
class->destroy = gtk_object_real_destroy;
/**
* GtkObject::destroy:
* @object: the object which received the signal.
*
* Signals that all holders of a reference to the #GtkObject should release
* the reference that they hold. May result in finalization of the object
* if all references are released.
*/
object_signals[DESTROY] =
g_signal_new (I_("destroy"),
G_TYPE_FROM_CLASS (gobject_class),
......@@ -132,6 +211,18 @@ gtk_object_init (GtkObject *object,
* Functions to end a GtkObject's life time
*
********************************************/
/**
* gtk_object_destroy:
* @object: the object to destroy.
*
* Emits the #GtkObject::destroy signal notifying all reference holders that they should
* release the #GtkObject. See the overview documentation at the top of the
* page for more details.
*
* The memory for the object itself won't be deleted until
* its reference count actually drops to 0; gtk_object_destroy() merely asks
* reference holders to release their references, it does not free the object.
*/
void
gtk_object_destroy (GtkObject *object)
{
......
......@@ -56,6 +56,15 @@ G_BEGIN_DECLS
* is a kinda nasty break up, it does make the size of
* derived objects smaller.
*/
/**
* GtkObjectFlags:
* @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
* internally by GTK+ to prevent reinvokations during destruction.
* @GTK_RESERVED_1: reserved for future use
* @GTK_RESERVED_2: reserved for future use
*
* Tells about the state of the object.
*/
typedef enum
{
GTK_IN_DESTRUCTION = 1 << 0, /* Used internally during dispose */
......@@ -63,7 +72,12 @@ typedef enum
GTK_RESERVED_2 = 1 << 3
} GtkObjectFlags;
/* Macros for extracting the object_flags from GtkObject.
/**
* GTK_OBJECT_FLAGS:
* @obj: the object whose flags are returned.
*
* Gets the #GtkObjectFlags for an object without directly
* accessing its members.
*/
#define GTK_OBJECT_FLAGS(obj) (GTK_OBJECT (obj)->flags)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment