GtkObject
<!-- ##### SECTION Short_Description ##### -->
-The base class of the Gtk type hierarchy.
+The base class of the GTK+ type hierarchy
<!-- ##### SECTION Long_Description ##### -->
<refsect2>
<title>Description</title>
<para>
-GtkObject is the root of the gtk+ type hierarchy. It serves
-a similar roles as java's Object class. It is used
-by the type-casting system to represent the base composite type.
+#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>
-Objects have <wordasword>arguments</wordasword> that are
-name/typed-value pairs.
-They may be readable or writable (or both or neither).
-The special handlers in every object are responsible for
-setting and getting these parameters.
-If the handler for a given argument <emphasis>must</emphasis>
-be called before the object may be used, be sure the
-#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags
-are set; otherwise they are set only when the user does so.
+#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>
-Object also store a simpler association table, sometimes
-called the object_data. This is just an efficient mapping from
-a fixed set of strings to a gpointer. This can be used as
-arbitrary extra members. Notice that each new field name
-allocates a new quark, so it is probably best only to use
-this for fields with fixed names.
+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 primary difference between object_data and arguments is that
-the object defines two functions which set and get each type of argument.
-The object just has a table to store its object data in: it does not
-receive notice when data changes.
+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>
-Objects are reference counted; this means that we maintain
-a count of how many references (usually in the form of a pointer)
-are being held to this object.
-To indicate that you reference an object, call gtk_object_ref().
-The object will not be freed until everyone calls
-gtk_object_unref().
-</para>
-<para>
-In order to reduce the chances of a memory leak, gtk+ defines
-"floating objects". All objects created with gtk_object_new()
-start out floating with a reference count of 1.
-In order to reduce that initial reference count you should gtk_object_sink()
-them, but usually the parent widget you add the child to will
-sink the object.
-</para>
-<para>So, because gtk_widget_set_parent() sinks the object from
-gtk_container_add(), there are no memory leaks in this code:
-<informalexample>
-<programlisting>
- button = gtk_button_new_with_label("Hi Mom!");
- gtk_container_add(GTK_CONTAINER(window), button);
- /* Button may not be used anymore since we don't retain a reference
- * to it. */
-</programlisting>
-</informalexample>
-Likewise, the following code attaches the same adjustment to two
-ranges:
-<informalexample>
-<programlisting>
- adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
- gtk_range_set_adjustment(range1, adjustment);
- gtk_range_set_adjustment(range2, adjustment);
-</programlisting>
-</informalexample>
-Note that we could put as many set_adjustments as we like: cleanup is easy
-because they all retain a reference but only one sinks the initial reference
-count. If it is possible for "range1" to stop retaining its reference
-then we need to enclose the lines using "adjustment" with ref/unref
-to guarantee the the object won't be deleted:
-<informalexample>
-<programlisting>
- adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);
- gtk_object_ref(GTK_OBJECT(adjustment));
- gtk_range_set_adjustment(range1, adjustment);
- gtk_range_set_adjustment(range1, another_adjustment);
- /* With the initial reference, `adjustment' would have
- * been deleted as `range1' lost its reference to it. */
- gtk_range_set_adjustment(range2, adjustment);
- gtk_object_unref(GTK_OBJECT(adjustment));
-</programlisting>
-</informalexample>
-</para>
-<para>
-Be careful with reference counting: if two objects reference eachother
-then they will always have at least reference count 1, even if
-there are no other pointers to them. This means that they
-will never be freed. More precisely, you must be certain that
-your references <emphasis>never</emphasis> can form cycles.
+#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>
-If you find yourself forming cyclic references, perhaps you
-can convert some of them to <wordasword>weak-references</wordasword>.
-A weak-reference is one that holds a pointer to an object,
-but doesn't increase the reference count. To insure
-the object is valid when the referer tries to use it,
-the referer registers a callback that will be invoked
-after the object has been destroyed (but before its memory is actually
-deallocated). This callback must prevent the weak-reference from
-being used again.
+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>
-</refsect2>
-<refsect2>
-<title>Brief Glossary</title>
-<variablelist>
-<varlistentry>
-<term>argument</term>
+<para>
+Some simple rules for handling #GtkObject:
+<itemizedlist>
<listitem><para>
-A typed-variable identified by ObjectType::argument_name. It may be
-readable, writable, both or none. For example,
-"GtkButton::label" is a read/write string-valued argument.
+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>
-</varlistentry>
-
-<varlistentry>
-<term>constructed</term>
<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>
-</varlistentry>
-
-<varlistentry>
-<term>destroyed</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
+<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>
-<varlistentry>
-<term>finalization</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
+</refsect2>
-<varlistentry>
-<term>floating</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GObject
+</para>
-<varlistentry>
-<term>object data</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
+<!-- ##### SECTION Stability_Level ##### -->
-<varlistentry>
-<term>reference count</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>weak-reference</term>
-<listitem><para>
-</para></listitem>
-</varlistentry>
+<!-- ##### SECTION Image ##### -->
-</variablelist>
-</refsect2>
-<!-- ##### SECTION See_Also ##### -->
+<!-- ##### STRUCT GtkObject ##### -->
<para>
-GtkType, GtkArg, gtk-signals.
+The object itself. You should never use these members directly -
+ use the accessing macros instead.
</para>
-<!-- ##### STRUCT GtkObject ##### -->
+
+<!-- ##### SIGNAL GtkObject::destroy ##### -->
<para>
-The object itself. You should never use these members directly-
-instead you the accessing macros.
+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>
-Get the type of an object.
+
</para>
-@object:
-<!-- # Unused Parameters # -->
-@obj: the object whose type we wish to get.
<!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
</para>
-@object:
<!-- ##### ENUM GtkObjectFlags ##### -->
Tells about the state of the object.
</para>
-@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it
-and is processing the shutdown callback.
-@GTK_FLOATING: whether the object is orphaned. Objects that take
-strong hold of an object may gtk_object_sink() it, after obtaining
-there own references, if they believe they are nearly primary
-ownership of the object.
-GTK_CONNECTED: refers to whether are signals are connected to this
-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:
+@GTK_RESERVED_2: reserved for future use
<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
<para>
-Get the #GtkObjectFlags for an object without directly
+Gets the #GtkObjectFlags for an object without directly
accessing its members.
</para>
@obj: the object whose flags are returned.
-<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
-<para>
-Test whether a GtkObject has had gtk_object_destroyed() invoked on it.
-</para>
-
-@obj: the object to examine.
-
-
-<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
-<para>
-When an object is created, it has an initial reference count
-of 1 and is floating. <wordasword>Sinking</wordasword> the object
-refers to decrementing that original reference count.
-</para>
-
-@obj: the object to examine.
-
-
-<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
-<para>
-Test whether a GtkObject has had a signal connected to it.
-</para>
-
-@obj: the object to examine.
-
-
-<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
-<para>
-Turn on certain object flags. (Private)
-</para>
-
-@obj: the object to affect.
-@flag: the flags to set.
-
-
-<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
-<para>
-Turn off certain object flags. (Private)
-</para>
-
-@obj: the object to affect.
-@flag: the flags to unset.
-
-
-<!-- ##### ENUM GtkArgFlags ##### -->
-<para>
-Possible flags indicating how an argument should be treated.
-</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 will
-be set once during object creation), but is otherwise cannot be
-set. 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>
-Construct an object given its arguments, enumerated in the call to the
-function.
-</para>
-
-@type: the type identifying this object. Returned by gtk_type_unique()
-although (for a properly-written object it should be accessible through
-#GTK_TYPE_FOO.)
-@first_property_name:
-@Varargs: the first argument's value, followed by any number of
-name/argument-value pairs, terminated with NULL.
-@Returns: the new GtkObject.
-<!-- # Unused Parameters # -->
-@first_arg_name: name of the first argument to set when constructing
-the object.
-
-
-<!-- ##### FUNCTION gtk_object_sink ##### -->
-<para>
-Decrement the initial count given to the object.
-Additional invocations have no effect.
-</para>
-<para>
-This is designed to free the user from worrying about
-dereferencing an object that they have just created.
-So long as the object is sunk at some point, the reference count
-will be set properly.
-</para>
-<para>
-furthermore it may be sunk multiple times.
-Only the first time will actually dereference.
-</para>
-<para>
-The basic outline is: when you create an object it is floating.
-Setting its parent causes it to be sunk, however its parent
-has obtained a reference, so its reference count is one.
-</para>
-
-@object: the object to sink.
-
-
-<!-- ##### FUNCTION gtk_object_ref ##### -->
-<para>
-Increase the reference count of the object.
-</para>
-
-@object: the object to reference.
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_unref ##### -->
-<para>
-Decrease the reference count of an object. When its reference
-count drops to 0, the object is deleted.
-</para>
-<para>
-If it was not already destroyed, it will be, with gtk_object_destroy(),
-then weak links are notified, then the object-data is freed
-and the memory for the object itself is freed using gtk_type_free().
-</para>
-
-@object: the object to dereference.
-
-
-<!-- ##### FUNCTION gtk_object_weakref ##### -->
-<para>
-Adds a weak reference callback to an object.
-</para>
-<para>
-Weak references are a mechanism to safely keep a pointer to
-an object without using the reference counting
-mechansim. They use a callback function to receive
-notice that the object is about to be freed (aka finalized).
-This happens <emphasis>after</emphasis> the destroy
-callback has been run.
-</para>
-
-@object: object to weakly reference.
-@notify: callback to invoke before the object is freed.
-@data: extra data to pass to #notify.
-
-
-<!-- ##### 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.
-
-
<!-- ##### FUNCTION gtk_object_destroy ##### -->
<para>
-Calls the object's shutdown handler.
+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 drops to 0, though.
-See gtk_object_unref().
+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.
-<!-- ##### FUNCTION gtk_object_get ##### -->
-<para>
-
-</para>
-
-@object:
-@first_property_name:
-@Varargs:
-<!-- # Unused Parameters # -->
-@first_arg_name:
-
-
-<!-- ##### FUNCTION gtk_object_set ##### -->
-<para>
-This function sets multiple arguments of an object.
-</para>
-<para>
-It takes an object, then a list of name/value pairs
-in a list, followed by NULL.
-</para>
-<para>
-<informalexample>
-<programlisting>
-void set_box_properties(GtkBox* box)
-{
- gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
- "spacing", 8,
- NULL);
-}
-</programlisting>
-</informalexample>
-</para>
-
-@object: the object whose arguments should be set.
-@first_property_name:
-@Varargs: the value of the first argument, followed optionally
-by more name/value pairs, followed by NULL.
-<!-- # Unused Parameters # -->
-@first_arg_name: the name of the first argument to set.
-
-
-<!-- ##### FUNCTION gtk_object_set_data ##### -->
-<para>
-Each object carries around a table of associations from
-strings to pointers. This function lets you set an association.
-</para>
-<para>
-If the object already had an association with that name,
-the old association will be destroyed.
-</para>
-
-@object: object containing the associations.
-@key: name of the key.
-@data: data to associate with that key.
-
-
-<!-- ##### FUNCTION gtk_object_set_data_full ##### -->
-<para>
-Like gtk_object_set_data() except it adds notification
-for when the association is destroyed, either by
-gtk_object_remove_data() or when the object is destroyed.
-</para>
-
-@object: object containing the associations.
-@key: name of the key.
-@data: data to associate with that key.
-@destroy: function to call when the association is destroyed.
-
-
-<!-- ##### FUNCTION gtk_object_remove_data ##### -->
-<para>
-Remove a specified datum from the object's data associations (the object_data).
-Subsequent calls to gtk_object_get_data() will return NULL.
-</para>
-<para>
-If you specified a destroy handler with gtk_object_set_data_full(),
-it will be invoked.
-</para>
-
-@object: the object maintaining the association.
-@key: name of the key for that association.
-
-
-<!-- ##### FUNCTION gtk_object_get_data ##### -->
-<para>
-Get a named field from the object's table of associations (the object_data).
-</para>
-
-@object: the object maintaining the associations.
-@key: name of the key for that association.
-@Returns: the data if found, or NULL if no such data exists.
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
-<para>
-Remove a specified datum from the object's data associations (the object_data),
-without invoking the association's destroy handler.
-</para>
-<para>
-Just like gtk_object_remove_data() except that any destroy handler
-will be ignored.
-Therefore this only affects data set using gtk_object_set_data_full().
-</para>
-
-@object: the object maintaining the association.
-@key: name of the key for that association.
-
-
-<!-- ##### FUNCTION gtk_object_set_user_data ##### -->
-<para>
-For convenience, every object offers a generic user data
-pointer. The function set it.
-</para>
-<para>
-This function is equivalent to:
-<informalexample>
-<programlisting>
- gtk_object_set_data(object, "user_data", data);
-</programlisting>
-</informalexample>
-</para>
-
-@object: the object whose user data should be set.
-@data: the new value for the user data.
-
-
-<!-- ##### FUNCTION gtk_object_get_user_data ##### -->
-<para>
-Get the object's user data pointer.
-</para>
-<para>
-This is intended to be a pointer for your convenience in
-writing applications.
-</para>
-
-@object: the object.
-@Returns: the user data field for object.
-
-
-<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
-<para>
-Add a new type of argument to an object class.
-Usually this is called when registering a new type of object.
-</para>
-
-@arg_name: fully qualify object name, for example GtkObject::user_data.
-@arg_type: type of the argument.
-@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is
-settable or gettable, whether it is set when the object is constructed.)
-@arg_id: an internal number, passed in from here to the "set_arg" and
-"get_arg" handlers of the object.
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
-<para>
-Just like gtk_object_set_data() except that it takes
-a #GQuark instead of a string, so it is slightly faster.
-</para>
-<para>
-Use gtk_object_data_try_key() and gtk_object_data_force_id()
-to get an id from a string.
-</para>
-
-@object: object containing the associations.
-@data_id: quark of the key.
-@data: data to associate with that key.
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
-<para>
-Just like gtk_object_set_data_full() except that it takes
-a #GQuark instead of a string, so it is slightly faster.
-</para>
-<para>
-Use gtk_object_data_try_key() and gtk_object_data_force_id()
-to get an id from a string.
-</para>
-
-@object: object containing the associations.
-@data_id: quark of the key.
-@data: data to associate with that key.
-@destroy: function to call when the association is destroyed.
-
-
-<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
-<para>
-Just like gtk_object_get_data() except that it takes
-a #GQuark instead of a string, so it is slightly faster.
-</para>
-<para>
-Use gtk_object_data_try_key() and gtk_object_data_force_id()
-to get an id from a string.
-</para>
-
-@object: object containing the associations.
-@data_id: quark of the key.
-@Returns: the data if found, or NULL if no such data exists.
-
-
-<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
-<para>
-Just like gtk_object_remove_data() except that it takes
-a #GQuark instead of a string, so it is slightly faster.
-</para>
-<para>
-Remove a specified datum from the object's data associations.
-Subsequent calls to gtk_object_get_data() will return NULL.
-</para>
-<para>
-Use gtk_object_data_try_key() and gtk_object_data_force_id()
-to get an id from a string.
-</para>
-
-@object: object containing the associations.
-@data_id: quark of the key.
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
-<para>
-Just like gtk_object_remove_no_notify() except that it takes
-a #GQuark instead of a string, so it is slightly faster.
-</para>
-<para>
-Use gtk_object_data_try_key() and gtk_object_data_force_id()
-to get an id from a string.
-</para>
-
-@object: object containing the associations.
-@key_id:
-<!-- # Unused Parameters # -->
-@data_id: quark of the key.
-
-
-<!-- ##### MACRO gtk_object_data_try_key ##### -->
-<para>
-Sees whether a certain quark exists.
-Returns that quark if so.
-</para>
-<para>
-Although this is currently the same as g_quark_try_string(),
-it might someday be different, for example, if GQuarks
-and object data are converted to separate mechanisms,
-so it is good to use this macro.
-</para>
-
-
-
-<!-- ##### MACRO gtk_object_data_force_id ##### -->
-<para>
-Makes a quark from a string, possibly allocating a new quark.
-</para>
-<para>
-Although this is currently the same as g_quark_from_string(),
-it might someday be different, for example, if GQuarks
-and object data are converted to separate mechanisms,
-so it is good to use this macro.
-</para>
-
-
-
-<!-- ##### SIGNAL GtkObject::destroy ##### -->
-<para>
-Indicates that an object is being destroyed.
-</para>
-
-@object: the object which received the signal.
-
-<!-- ##### ARG GtkObject:user-data ##### -->
-<para>
-A pointer for convenience when programming applications.
-</para>
-
projects / ~andy / gtk / blobdiff