GtkObject
<!-- ##### SECTION Short_Description ##### -->
-
+The base class of the GTK+ type hierarchy
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+<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>
-
-</para>
-
-<!-- ##### STRUCT GtkObject ##### -->
-<para>
-
-</para>
-
-@klass:
-@flags:
-@ref_count:
-@object_data:
-
-<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### ENUM GtkObjectFlags ##### -->
-<para>
-
-</para>
-
-@GTK_DESTROYED:
-@GTK_FLOATING:
-@GTK_CONNECTED:
-@GTK_CONSTRUCTED:
-
-<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-@flag:
-
-
-<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-@flag:
-
-
-<!-- ##### ENUM GtkArgFlags ##### -->
-<para>
-
-</para>
-
-@GTK_ARG_READABLE:
-@GTK_ARG_WRITABLE:
-@GTK_ARG_CONSTRUCT:
-@GTK_ARG_CONSTRUCT_ONLY:
-@GTK_ARG_CHILD_ARG:
-@GTK_ARG_MASK:
-@GTK_ARG_READWRITE:
-
-<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
-<para>
-
-</para>
-
-@klass:
-@name:
-@signal_flags:
-@marshaller:
-@return_val:
-@nparams:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
-<para>
-
-</para>
-
-@klass:
-@name:
-@signal_flags:
-@marshaller:
-@return_val:
-@nparams:
-@params:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_new ##### -->
-<para>
-
+#GObject
</para>
-@type:
-@first_arg_name:
-@Varargs:
-@Returns:
-
+<!-- ##### SECTION Stability_Level ##### -->
-<!-- ##### FUNCTION gtk_object_newv ##### -->
-<para>
-
-</para>
-@object_type:
-@n_args:
-@args:
-@Returns:
+<!-- ##### SECTION Image ##### -->
-<!-- ##### FUNCTION gtk_object_constructed ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_default_construct ##### -->
+<!-- ##### STRUCT GtkObject ##### -->
<para>
-
+The object itself. You should never use these members directly -
+ use the accessing macros instead.
</para>
-@object:
-
-<!-- ##### FUNCTION gtk_object_sink ##### -->
+<!-- ##### 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:
-
+@object: the object which received the signal.
-<!-- ##### FUNCTION gtk_object_ref ##### -->
+<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
<para>
</para>
-@object:
-<!-- ##### FUNCTION gtk_object_unref ##### -->
+<!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
<para>
</para>
-@object:
-<!-- ##### FUNCTION gtk_object_weakref ##### -->
+<!-- ##### ENUM GtkObjectFlags ##### -->
<para>
-
+Tells about the state of the object.
</para>
-@object:
-@notify:
-@data:
-
+@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
-<!-- ##### FUNCTION gtk_object_weakunref ##### -->
+<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
<para>
-
+Gets the #GtkObjectFlags for an object without directly
+accessing its members.
</para>
-@object:
-@notify:
-@data:
+@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>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_getv ##### -->
<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:
-@n_args:
-@args:
+@object: the object to destroy.
-<!-- ##### FUNCTION gtk_object_set ##### -->
-<para>
-
-</para>
-
-@object:
-@first_arg_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_object_setv ##### -->
-<para>
-
-</para>
-
-@object:
-@n_args:
-@args:
-
-
-<!-- ##### FUNCTION gtk_object_query_args ##### -->
-<para>
-
-</para>
-
-@class_type:
-@arg_flags:
-@n_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_set_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_full ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@data:
-@destroy:
-
-
-<!-- ##### FUNCTION gtk_object_remove_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-
-
-<!-- ##### FUNCTION gtk_object_get_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-
-
-<!-- ##### FUNCTION gtk_object_set_user_data ##### -->
-<para>
-
-</para>
-
-@object:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_get_user_data ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
-<para>
-
-</para>
-
-@klass:
-@signals:
-@nsignals:
-
-
-<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
-<para>
-
-</para>
-
-@arg_name:
-@arg_type:
-@arg_flags:
-@arg_id:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@data:
-@destroy:
-
-
-<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@key_id:
-
-
-<!-- ##### MACRO gtk_object_data_try_key ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_object_data_force_id ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_object_arg_set ##### -->
-<para>
-
-</para>
-
-@object:
-@arg:
-@info:
-
-
-<!-- ##### FUNCTION gtk_object_arg_get ##### -->
-<para>
-
-</para>
-
-@object:
-@arg:
-@info:
-
-
-<!-- ##### FUNCTION gtk_object_args_collect ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_list_p:
-@info_list_p:
-@first_arg_name:
-@var_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_name:
-@info_p:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_trace_referencing ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@dummy:
-@line:
-@do_ref:
-
-
-<!-- ##### SIGNAL GtkObject::destroy ##### -->
-<para>
-
-</para>
-
-@object: the object which received the signal.
-
-<!-- ##### ARG GtkObject:user_data ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:signal ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:signal_after ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:object_signal ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:object_signal_after ##### -->
-<para>
-
-</para>
-
projects / ~andy / gtk / blobdiff