#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 code
-section that has the right to call g_object_unref() in order to remove that
-reference.) A #GtkObject is created with a reference count of 1 also, but it
-isn't owned by anyone; calling g_object_unref() on the newly-created #GtkObject
-is incorrect. Instead, the initial reference count of a #GtkObject is "floating".
-The floating reference can be removed by anyone at any time, by calling
-gtk_object_sink(). gtk_object_sink() does nothing if an object is already
-sunk (has no floating reference).
+#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 (G_OBJECT (child_widget));
- gtk_object_sink (GTK_OBJECT (child_widget));
+ g_object_ref_sink (G_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.
+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
#GObject
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkObject ##### -->
<para>
The object itself. You should never use these members directly -
@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 ##### -->
@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_1:
@GTK_RESERVED_2: reserved for future use
<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
@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 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>
-Constructs 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
-a #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 of
-name/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 is
-finalized. They are called "weak references" because they allow you to safely
-hold a pointer to an object without calling g_object_ref() (g_object_ref() adds
-a 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 should
@object: the object to destroy.
-<!-- ##### FUNCTION gtk_object_get ##### -->
-<para>
-Gets properties of an object.
-</para>
-
-@object: a #GtkObject.
-@first_property_name: name of first property to get the value for.
-@Varargs: %NULL-terminated list of name-return location pairs.
-@Deprecated: Use g_object_get() instead.
-
-
-<!-- ##### FUNCTION gtk_object_set ##### -->
-<para>
-Sets properties on an object.
-</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: a #GtkObject.
-@first_property_name: name of the first property to set
-@Varargs: the value of the first argument, followed optionally
-by more name/value pairs, followed by %NULL.
-@Deprecated: Use g_object_set() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_set_data() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_set_data_full() instead.
-
-
-<!-- ##### FUNCTION gtk_object_remove_data ##### -->
-<para>
-Removes 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.
-@Deprecated: Use g_object_set_data() to set the object data to %NULL instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_get_data() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_steal_data() instead.
-
-
-<!-- ##### FUNCTION gtk_object_set_user_data ##### -->
-<para>
-For convenience, every object offers a generic user data
-pointer. This function sets it.
-</para>
-
-@object: the object whose user data should be set.
-@data: the new value for the user data.
-@Deprecated: Use g_object_set_data() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_get_data() instead.
-
-
-<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
-<para>
-Deprecated in favor of the #GObject property system including #GParamSpec.
-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.
-@Deprecated: Use g_object_set_qdata() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_set_qdata_full() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_get_qdata() instead.
-
-
-<!-- ##### 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.
-@Deprecated: Use g_object_set_qdata() with data of %NULL instead.
-
-
-<!-- ##### 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: quark of the key.
-@Deprecated: Use g_object_steal_qdata() instead.
-
-
-<!-- ##### MACRO gtk_object_data_try_key ##### -->
-<para>
-Useless deprecated macro. Ignore it.
-</para>
-
-
-
-<!-- ##### MACRO gtk_object_data_force_id ##### -->
-<para>
-Useless deprecated macro. Ignore it.
-</para>
-
-
-
projects / ~andy / gtk / blobdiff