forked from AuroraMiddleware/gtk
c26e3eeebc
Mon Jan 8 15:21:15 2001 Owen Taylor <otaylor@redhat.com> * Makefile.am (SUBDIRS): Restore build. * gdk/gdk-sections.txt gdk/gdk-docs.sgml gdk-pixbuf/gdk-pixbuf-sections.txt gtk/gtk-sections.txt gtk/gtk-docs.sgml: : Update. * */tmpl/*: Changes from update.
662 lines
18 KiB
Plaintext
662 lines
18 KiB
Plaintext
<!-- ##### 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>
|
|
|