Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkobject.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkObject
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The base class of the GTK+ type hierarchy
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <refsect2>
   9 <title>Description</title>
  10 <para>
  11 #GtkObject is the base class for all widgets, and for a few
  12 non-widget objects such as #GtkAdjustment. #GtkObject predates
  13 #GObject; non-widgets that derive from #GtkObject rather than
  14 #GObject do so for backward compatibility reasons.
  15 </para>
  16 <para>
  17 #GtkObject<!-- -->s are created with a "floating" reference count.
  18 This means that the initial reference is not owned by anyone. Calling
  19 g_object_unref() on a newly-created #GtkObject is incorrect, the floating
  20 reference has to be removed first. This can be done by anyone at any time,
  21 by calling g_object_ref_sink() to convert the floating reference into a
  22 regular reference. g_object_ref_sink() returns a new reference if an object
  23 is already sunk (has no floating reference).
  24 </para>
  25 <para>
  26 When you add a widget to its parent container, the parent container
  27 will do this:
  28 <informalexample><programlisting>
  29   g_object_ref_sink (G_OBJECT (child_widget));
  30 </programlisting></informalexample>
  31 This means that the container now owns a reference to the child widget
  32 and the child widget has no floating reference.
  33 </para>
  34 <para>
  35 The purpose of the floating reference is to keep the child widget alive
  36 until you add it to a parent container:
  37 <informalexample><programlisting>
  38    button = gtk_button_new (<!-- -->);
  39    /* button has one floating reference to keep it alive */
  40    gtk_container_add (GTK_CONTAINER (container), button);
  41    /* button has one non-floating reference owned by the container */
  42 </programlisting></informalexample>
  43 </para>
  44 <para>
  45 #GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
  46 That is, after calling gtk_window_new(), the #GtkWindow will have one
  47 reference which is owned by GTK+, and no floating references.
  48 </para>
  49
  50 <para>
  51 One more factor comes into play: the "destroy" signal, emitted by the
  52 gtk_object_destroy() method. The "destroy" signal asks all code owning a
  53 reference to an object to release said reference. So, for example, if you call
  54 gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
  55 it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
  56 be removed from its parent container and the parent container will release its
  57 reference to the button.  Because these references are released, calling
  58 gtk_object_destroy() should result in freeing all memory associated with an
  59 object, unless some buggy code fails to release its references in response to
  60 the "destroy" signal. Freeing memory (referred to as
  61 <firstterm>finalization</firstterm> only happens if the reference count reaches
  62 zero.
  63 </para>
  64
  65 <para>
  66 Some simple rules for handling #GtkObject:
  67 <itemizedlist>
  68 <listitem><para>
  69 Never call g_object_unref() unless you have previously called g_object_ref(),
  70 even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
  71 true for #GObject; for #GObject, the creator of the object owns a reference.)
  72 </para></listitem>
  73 <listitem><para>
  74 Call gtk_object_destroy() to get rid of most objects in most cases.
  75 In particular, widgets are almost always destroyed in this way.
  76 </para></listitem>
  77 <listitem><para> Because of the floating reference count, you don't need to
  78 worry about reference counting for widgets and toplevel windows, unless you
  79 explicitly call g_object_ref() yourself.</para></listitem>
  80 </itemizedlist>
  81 </para>
  82
  83 </refsect2>
  84
  85 <!-- ##### SECTION See_Also ##### -->
  86 <para>
  87 #GObject
  88 </para>
  89
  90 <!-- ##### SECTION Stability_Level ##### -->
  91
  92
  93 <!-- ##### SECTION Image ##### -->
  94
  95
  96 <!-- ##### STRUCT GtkObject ##### -->
  97 <para>
  98 The object itself.  You should never use these members directly -
  99  use the accessing macros instead.
 100 </para>
 101
 102
 103 <!-- ##### SIGNAL GtkObject::destroy ##### -->
 104 <para>
 105 Signals that all holders of a reference to the #GtkObject should release
 106 the reference that they hold. May result in finalization of the object
 107 if all references are released.
 108 </para>
 109
 110 @object: the object which received the signal.
 111
 112 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
 113 <para>
 114
 115 </para>
 116
 117
 118
 119 <!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
 120 <para>
 121
 122 </para>
 123
 124
 125
 126 <!-- ##### ENUM GtkObjectFlags ##### -->
 127 <para>
 128 Tells about the state of the object.
 129 </para>
 130
 131 @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
 132   internally by GTK+ to prevent reinvokations during destruction.
 133 @GTK_RESERVED_1:
 134 @GTK_RESERVED_2: reserved for future use
 135
 136 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
 137 <para>
 138 Gets the #GtkObjectFlags for an object without directly
 139 accessing its members.
 140 </para>
 141
 142 @obj: the object whose flags are returned.
 143
 144
 145 <!-- ##### FUNCTION gtk_object_destroy ##### -->
 146 <para>
 147 Emits the "destroy" signal notifying all reference holders that they should
 148 release the #GtkObject. See the overview documentation at the top of the
 149 page for more details.
 150 </para>
 151 <para>
 152 The memory for the object itself won't be deleted until
 153 its reference count actually drops to 0; gtk_object_destroy() merely asks
 154 reference holders to release their references, it does not free the object.
 155 </para>
 156
 157 @object: the object to destroy.
 158
 159