forked from AuroraMiddleware/gtk
Move documentation to inline comments: GtkObject
This commit is contained in:
Javier Jardón
parent
3d481f735a
commit
157d618d6b
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -3,6 +3,7 @@ gtkbox.sgml
|
||||
gtkbuilder.sgml
|
||||
gtkhbox.sgml
|
||||
gtkmessagedialog.sgml
|
||||
gtkobject.sgml
|
||||
gtkorientable.sgml
|
||||
gtkpagesetupunixdialog.sgml
|
||||
gtkseparator.sgml
|
||||
|
||||
@ -1,146 +0,0 @@
|
||||
<!-- ##### 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 (<!-- -->);
|
||||
* /* 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>
|
||||
*
|
||||
* #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)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user