diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 8b4eaa0db9..d8fbb174c6 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -3,6 +3,7 @@ gtkbox.sgml gtkbuilder.sgml gtkhbox.sgml gtkmessagedialog.sgml +gtkobject.sgml gtkorientable.sgml gtkpagesetupunixdialog.sgml gtkseparator.sgml diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml deleted file mode 100644 index 5a3f5b7a7b..0000000000 --- a/docs/reference/gtk/tmpl/gtkobject.sgml +++ /dev/null @@ -1,146 +0,0 @@ - -GtkObject - - -The base class of the GTK+ type hierarchy - - - -Description - -#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. - - -#GtkObjects 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: - - g_object_ref_sink (G_OBJECT (child_widget)); - -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: - - 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 */ - - - -#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 "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 -finalization only happens if the reference count reaches -zero. - - - -Some simple rules for handling #GtkObject: - - -Never call g_object_unref() unless you have previously called g_object_ref(), -even if you created the #GtkObject. (Note: this is not -true for #GObject; for #GObject, the creator of the object owns a reference.) - - -Call gtk_object_destroy() to get rid of most objects in most cases. -In particular, widgets are almost always destroyed in this way. - - 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. - - - - - - - -#GObject - - - - - - - - - - -The object itself. You should never use these members directly - - use the accessing macros instead. - - - - - -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: the object which received the signal. - - - - -Tells about the state of the object. - - -@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 - - - -Gets the #GtkObjectFlags for an object without directly -accessing its members. - - -@obj: the object whose flags are returned. - - - - -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. - - -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. - - -@object: the object to destroy. - - diff --git a/gtk/gtkobject.c b/gtk/gtkobject.c index 9cedfe346f..a393070fdb 100644 --- a/gtk/gtkobject.c +++ b/gtk/gtkobject.c @@ -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. + * + * #GtkObjects 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: + * + * g_object_ref_sink (G_OBJECT (child_widget)); + * + * 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: + * + * 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 */ + * + * + * #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 + * finalization) only happens if the reference count reaches + * zero. + * + * Some simple rules for handling #GtkObject: + * + * + * Never call g_object_unref() unless you have previously called g_object_ref(), + * even if you created the #GtkObject. (Note: this is not + * true for #GObject; for #GObject, the creator of the object owns a reference.) + * + * + * Call gtk_object_destroy() to get rid of most objects in most cases. + * In particular, widgets are almost always destroyed in this way. + * + * 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. + * + */ + + 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) { diff --git a/gtk/gtkobject.h b/gtk/gtkobject.h index b20f249927..34f34ed7ab 100644 --- a/gtk/gtkobject.h +++ b/gtk/gtkobject.h @@ -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)