gtk2/docs/reference/gtk/tmpl/gtkobject.sgml

<!-- ##### SECTION Title ##### -->
GtkObject

<!-- ##### SECTION Short_Description ##### -->
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.
</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.
</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.
</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.
</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.
</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.
</para>
</refsect2>
<refsect2>
<title>Brief Glossary</title>
<variablelist>

<varlistentry>
<term>argument</term>
<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.
</para></listitem>
</varlistentry>

<varlistentry>
<term>constructed</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>destroyed</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>finalization</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>floating</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>object data</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>reference count</term>
<listitem><para>
</para></listitem>
</varlistentry>

<varlistentry>
<term>weak-reference</term>
<listitem><para>
</para></listitem>
</varlistentry>

</variablelist>
</refsect2>

<!-- ##### SECTION See_Also ##### -->
<para>
GtkType, GtkArg, gtk-signals.
</para>

<!-- ##### STRUCT GtkObject ##### -->
<para>
The object itself.  You should never use these members directly-
instead you the accessing macros.
</para>


<!-- ##### 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>

</para>

@object: 


<!-- ##### ENUM GtkObjectFlags ##### -->
<para>
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_RESERVED_1: 
@GTK_RESERVED_2: 

<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
<para>
Get 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.
</para>
<para>
The memory for the object itself won't be deleted until
its reference count drops to 0, though.
See gtk_object_unref().
</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>