<!-- ##### 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>The most interesting difference between #GtkObject and #GObject is the"floating" reference count. A #GObject is created with a reference count of 1,owned by the creator of the #GObject. (The owner of a reference is the codesection that has the right to call g_object_unref() in order to remove thatreference.)  A #GtkObject is created with a reference count of 1 also, but itisn't owned by anyone; calling g_object_unref() on the newly-created #GtkObjectis incorrect. Instead, the initial reference count of a #GtkObject is "floating". The floating reference can be removed by anyone at any time, by callinggtk_object_sink(). gtk_object_sink() does nothing if an object is already sunk (has no floating reference).</para><para>When you add a widget to its parent container, the parent containerwill do this:<informalexample><programlisting>  g_object_ref (G_OBJECT (child_widget));  gtk_object_sink (GTK_OBJECT (child_widget));</programlisting></informalexample>This means that the container now owns a reference to the child widget (since it called g_object_ref()), 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 thegtk_object_destroy() method. The "destroy" signal asks all code owning areference to an object to release said reference. So, for example, if you callgtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count thatit owns; if you call gtk_object_destroy() on a #GtkButton, then the button willbe removed from its parent container and the parent container will release itsreference to the button.  Because these references are released, callinggtk_object_destroy() should result in freeing all memory associated with anobject, unless some buggy code fails to release its references in response tothe "destroy" signal. Freeing memory (referred to as<firstterm>finalization</firstterm> only happens if the reference count reacheszero.</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 toworry about reference counting for widgets and toplevel windows, unless youexplicitly call g_object_ref() yourself.</para></listitem></itemizedlist></para></refsect2><!-- ##### SECTION See_Also ##### --><para>#GObject</para><!-- ##### SECTION Stability_Level ##### --><!-- ##### 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 releasethe reference that they hold. May result in finalization of the objectif all references are released.</para>@object: the object which received the signal.<!-- ##### ARG GtkObject:user-data ##### --><para></para><!-- ##### MACRO GTK_OBJECT_TYPE ##### --><para>Gets the type of an object.</para>@object: a #GtkObject.<!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### --><para>Gets the name of an objects type.</para>@object: a #GtkObject.<!-- ##### 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_FLOATING: the object is orphaned.  Objects that take strong hold of an   object may gtk_object_sink() it, after obtaining their own references, if   they believe they are nearly primary ownership of the object.GTK_CONNECTED: signals are connected to this object.@GTK_RESERVED_1: reserved for future use@GTK_RESERVED_2: reserved for future use<!-- ##### MACRO GTK_OBJECT_FLAGS ##### --><para>Gets the #GtkObjectFlags for an object without directlyaccessing its members.</para>@obj: the object whose flags are returned.<!-- ##### MACRO GTK_OBJECT_FLOATING ##### --><para>Evaluates to %TRUE if the object still has its floating reference count.See the overview documentation for #GtkObject.</para>@obj: the object to examine.<!-- ##### ENUM GtkArgFlags ##### --><para>Possible flags indicating how an argument should be treated.Deprecated in favor of #GParamSpec features.</para>@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)@GTK_ARG_CONSTRUCT: the argument needs construction.@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and willbe set once during object creation), but is otherwise cannot beset.  Hence this flag is not allowed with #GTK_ARG_WRITABLE,and is redundant with #GTK_ARG_CONSTRUCT.@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)each child.  Used by #GtkContainer.<!-- ##### FUNCTION gtk_object_new ##### --><para>Constructs an object given its arguments, enumerated in the call to thefunction.</para>@type: the type identifying this object.  Returned by gtk_type_unique()(although for a properly-written object it should be accessible througha #GTK_TYPE_FOO macro.)@first_property_name: name of the first property to set when constructing   the object.@Varargs: the first argument's value, followed by any number ofname/argument-value pairs, terminated with %NULL.@Returns: the new #GtkObject.@Deprecated: Use g_object_new() instead.<!-- ##### FUNCTION gtk_object_sink ##### --><para>Removes the floating reference from a #GtkObject, if it exists; otherwise does nothing. See the #GtkObject overview documentation at the top of the page.</para>@object: the object to sink.<!-- ##### FUNCTION gtk_object_ref ##### --><para>Increases the reference count of the object.</para>@object: the object to reference.@Returns: @object.@Deprecated: Use g_object_ref() instead.<!-- ##### FUNCTION gtk_object_unref ##### --><para>Decreases the reference count of an object.  When its reference count drops to 0, the object is finalized (i.e. its memory is freed).  </para>@object: the object to dereference.@Deprecated: Use g_object_unref() instead.<!-- ##### FUNCTION gtk_object_weakref ##### --><para>Adds a weak reference callback to an object. Weak references are used for notification when an object isfinalized. They are called "weak references" because they allow you to safelyhold a pointer to an object without calling g_object_ref() (g_object_ref() addsa strong reference, that is, forces the object to stay alive).</para>@object: object to weakly reference.@notify: callback to invoke before the object is freed.@data: extra data to pass to #notify.@Deprecated: Use g_object_weak_ref() instead.<!-- ##### FUNCTION gtk_object_weakunref ##### --><para>Removes a weak reference callback to an object.</para>@object: object stop weakly referencing.@notify: callback to search for.@data: data to search for.@Deprecated: Use g_object_weak_unref() instead.<!-- ##### FUNCTION gtk_object_destroy ##### --><para>Emits the "destroy" signal notifying all reference holders that they shouldrelease the #GtkObject. See the overview documentation at the top of the