forked from AuroraMiddleware/gtk
7447ef0fc2
In particular, rename - libraries to lib*-3.0.so - pc files to *-3.0.pc - include paths to /usr/include/gtk-3.0/* - module paths to /usr/lib/gtk-3.0/* - rc files names to gtk-3.0/gtkrc - commandline utilities to *-3.0 - adjust documentation Also change the install location for unix-print headers to /usr/include/gtk-3.0/unix-print/gtk.
160 lines
5.1 KiB
Plaintext
160 lines
5.1 KiB
Plaintext
<!-- ##### 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.
|
|
|
|
<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
|