glib/docs/reference/gobject/tmpl/objects.sgml
Matthias Clasen dfa521fdf7 Additions.
2003-03-24 23:28:35 +00:00

721 lines
20 KiB
Plaintext

<!-- ##### SECTION Title ##### -->
GObject
<!-- ##### SECTION Short_Description ##### -->
The base object type
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### STRUCT GObject ##### -->
<para>
All the fields in the <structname>GObject</structname> structure are private
to the #GObject implementation and should never be accessed directly.
</para>
@g_type_instance:
<!-- ##### STRUCT GObjectClass ##### -->
<para>
</para>
@g_type_class:
<!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
<para>
</para>
@object:
@property_id:
@value:
@pspec:
<!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
<para>
</para>
@object:
@property_id:
@value:
@pspec:
<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
<para>
</para>
@object:
<!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
<para>
Returns a boolean value of %FALSE or %TRUE indicating whether
the passed in type id is a %G_TYPE_OBJECT or derived from it.
</para>
@type: Type id to check for is a %G_TYPE_OBJECT relationship.
@Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
<!-- ##### MACRO G_OBJECT ##### -->
<para>
Casts a #GObject or derived pointer into a (GObject*) pointer.
Depending on the current debugging level, this function may invoke
certain runtime checks to identify invalid casts.
</para>
@object: Object which is subject to casting.
<!-- ##### MACRO G_IS_OBJECT ##### -->
<para>
Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
</para>
@object: Instance to check for being a %G_TYPE_OBJECT.
<!-- ##### MACRO G_OBJECT_CLASS ##### -->
<para>
Casts a derived #GObjectClass structure into a #GObjectClass structure.
</para>
@class: a valid #GObjectClass
<!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
<para>
Checks whether @class "is a" valid #GObjectClass structure of type
%G_TYPE_OBJECT or derived.
</para>
@class: a #GObjectClass
<!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
<para>
Returns the class structure associated to a #GObject instance.
</para>
@object: a #GObject instance.
<!-- ##### MACRO G_OBJECT_TYPE ##### -->
<para>
Return the type id of an object.
</para>
@object: Object to return the type id for.
@Returns: Type id of @object.
<!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
<para>
Returns the name of an object's type.
</para>
@object: Object to return the type name for.
@Returns: Type name of @object. The string is owned by the type system and
should not be freed.
<!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
<para>
Return the type id of a class structure.
</para>
@class: a valid #GObjectClass
@Returns: Type id of @class.
<!-- ##### MACRO G_OBJECT_CLASS_NAME ##### -->
<para>
Return the name of a class structure's type.
</para>
@class: a valid #GObjectClass
@Returns: Type name of @class. The string is owned by the type system and
should not be freed.
<!-- ##### FUNCTION g_object_class_install_property ##### -->
<para>
Installs a new property. This is usually done in the class initializer.
</para>
@oclass: a #GObjectClass
@property_id: the id for the new property
@pspec: the #GParamSpec for the new property
<!-- ##### FUNCTION g_object_class_find_property ##### -->
<para>
Looks up the #GParamSpec for a property of a class.
</para>
@oclass: a #GObjectClass
@property_name: the name of the property to look up
@Returns: the #GParamSpec for the property, or %NULL if the class doesn't have
a property of that name
<!-- ##### FUNCTION g_object_class_list_properties ##### -->
<para>
Returns an array of #GParamSpec* for all properties of a class.
</para>
@oclass: a #GObjectClass
@n_properties: return location for the length of the returned array
@Returns: an array of #GParamSpec* which should be freed after use
<!-- ##### FUNCTION g_object_new ##### -->
<para>
Creates a new instance of a #GObject subtype and sets its properties.
</para>
<para>
Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
which are not explicitly specified are set to their default values.
</para>
@object_type: the type id of the #GObject subtype to instantiate
@first_property_name: the name of the first property
@Varargs: the value of the first property, followed optionally by more
name/value pairs, followed by %NULL
@Returns: a new instance of @object_type
<!-- ##### FUNCTION g_object_newv ##### -->
<para>
Creates a new instance of a #GObject subtype and sets its properties.
</para>
<para>
Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
which are not explicitly specified are set to their default values.
</para>
@object_type: the type id of the #GObject subtype to instantiate
@n_parameters: the length of the @parameters array
@parameters: an array of #GParameter
@Returns: a new instance of @object_type
<!-- ##### STRUCT GParameter ##### -->
<para>
The <structname>GParameter</structname> struct is an auxiliary structure used
to hand parameter name/value pairs to g_object_newv().
</para>
@name: the parameter name
@value: the parameter value
<!-- ##### FUNCTION g_object_ref ##### -->
<para>
Increases the reference count of @object.
</para>
@object: a #GObject
@Returns: @object
<!-- ##### FUNCTION g_object_unref ##### -->
<para>
Decreases the reference count if @object.
When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
</para>
@object: a #GObject
<!-- ##### USER_FUNCTION GWeakNotify ##### -->
<para>
</para>
@data:
@where_the_object_was:
<!-- ##### FUNCTION g_object_weak_ref ##### -->
<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: #GObject to reference weakly
@notify: callback to invoke before the object is freed
@data: extra data to pass to notify
<!-- ##### FUNCTION g_object_weak_unref ##### -->
<para>
Removes a weak reference callback to an object.
</para>
@object: #GObject to remove a weak reference from
@notify: callback to search for
@data: data to search for
<!-- ##### FUNCTION g_object_add_weak_pointer ##### -->
<para>
Adds a weak reference from weak_pointer to @object to indicate that
the pointer located at @weak_pointer_location is only valid during the
lifetime of @object. When the @object is finalized, @weak_pointer will
be set to %NULL.
</para>
@object: The object that should be weak referenced.
@weak_pointer_location: The memory address of a pointer.
<!-- ##### FUNCTION g_object_remove_weak_pointer ##### -->
<para>
Removes a weak reference from @object that was previously added
using g_object_add_weak_pointer(). The @weak_pointer_location has
to match the one used with g_object_add_weak_pointer().
</para>
@object: The object that is weak referenced.
@weak_pointer_location: The memory address of a pointer.
<!-- ##### FUNCTION g_object_connect ##### -->
<para>
A convenience function to connect multiple signals at once.
</para>
<para>
The signal specs expected by this function have the form
"modifier::signal_name", where modifier can be one of the following:
<variablelist>
<varlistentry>
<term>signal</term>
<listitem><para>
equivalent to <literal>g_signal_connect_data (...)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>object_signal</term>
<listitem><para>
equivalent to <literal>g_signal_connect_object (...)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>swapped_signal</term>
<listitem><para>
equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>swapped_object_signal</term>
<listitem><para>
equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>signal_after</term>
<listitem><para>
equivalent to <literal>g_signal_connect_data (..., G_CONNECT_AFTER)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>object_signal_after</term>
<listitem><para>
equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>swapped_signal_after</term>
<listitem><para>
equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
</para></listitem>
</varlistentry>
<varlistentry>
<term>swapped_object_signal_after</term>
<listitem><para>
equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
</para></listitem>
</varlistentry>
</variablelist>
</para>
<informalexample>
<programlisting>
menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
"type", GTK_WINDOW_POPUP,
"child", menu,
NULL),
"signal::event", gtk_menu_window_event, menu,
"signal::size_request", gtk_menu_window_size_request, menu,
"signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
NULL);
</programlisting>
</informalexample>
@object: a #GObject
@signal_spec: the spec for the first signal
@Varargs: #GCallback for the first signal, followed by data for the first signal,
followed optionally by more signal spec/callback/data triples,
followed by %NULL
@Returns: @object
<!-- ##### FUNCTION g_object_disconnect ##### -->
<para>
A convenience function to disconnect multiple signals at once.
</para>
<para>
The signal specs expected by this function have the form "any_signal", which
means to disconnect any signal with matching callback and data, or
"any_signal::signal_name", which only disconnects the signal named "signal_name".
</para>
@object: a #GObject
@signal_spec: the spec for the first signal
@Varargs: #GCallback for the first signal, followed by data for the first signal,
followed optionally by more signal spec/callback/data triples,
followed by %NULL
<!-- ##### FUNCTION g_object_set ##### -->
<para>
Sets properties on an object.
</para>
@object: a #GObject
@first_property_name: name of the first property to set
@Varargs: value for the first property, followed optionally by more
name/value pairs, followed by %NULL
<!-- ##### FUNCTION g_object_get ##### -->
<para>
Gets properties of an object.
</para>
<para>
In general, a copy is made of the property contents and the caller is
responsible for freeing the memory in the appropriate manner for the type,
for instance by calling g_free() or g_object_unref().
</para>
<example>
<title>Using g_object_get(<!-- -->)</title>
<para>
An example of using g_object_get() to get the contents
of three properties - one of type #G_TYPE_INT,
one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
</para>
<programlisting>
gint intval;
gchar *strval;
GObject *objval;
g_object_get (my_object,
"intproperty", &amp;intval,
"strproperty", &amp;strval,
"objproperty", &amp;objval,
NULL);
/* Do something with intval, strval, objval */
g_free (strval);
g_object_unref (objval);
</programlisting>
</example>
@object: a #GObject
@first_property_name: name of the first property to get
@Varargs: return location for the first property, followed optionally by more
name/return location pairs, followed by %NULL
<!-- ##### FUNCTION g_object_notify ##### -->
<para>
Emits a "notify" signal for the property @property_name on @object.
</para>
@object: a #GObject
@property_name: the name of a property installed on the class of @object.
<!-- ##### FUNCTION g_object_freeze_notify ##### -->
<para>
Stops emission of "notify" signals on @object. The signals are
queued until g_object_thaw_notify() is called on @object.
</para>
@object: a #GObject
<!-- ##### FUNCTION g_object_thaw_notify ##### -->
<para>
Reverts the effect of a previous call to g_object_freeze_notify().
This causes all queued "notify" signals on @object to be emitted.
</para>
@object: a #GObject
<!-- ##### FUNCTION g_object_get_data ##### -->
<para>
Gets a named field from the objects table of associations (see g_object_set_data()).
</para>
@object: #GObject containing the associations
@key: name of the key for that association
@Returns: the data if found, or %NULL if no such data exists.
<!-- ##### FUNCTION g_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: #GObject containing the associations.
@key: name of the key
@data: data to associate with that key
<!-- ##### FUNCTION g_object_set_data_full ##### -->
<para>
Like g_object_set_data() except it adds notification
for when the association is destroyed, either by setting it
to a different value or when the object is destroyed.
</para>
@object: #GObject 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 g_object_steal_data ##### -->
<para>
Remove a specified datum from the object's data associations,
without invoking the association's destroy handler.
</para>
@object: #GObject containing the associations
@key: name of the key
@Returns: the data if found, or %NULL if no such data exists.
<!-- ##### FUNCTION g_object_get_qdata ##### -->
<para>
This function gets back user data pointers stored via
g_object_set_qdata().
</para>
@object: The GObject to get a stored user data pointer from
@quark: A #GQuark, naming the user data pointer
@Returns: The user data pointer set, or %NULL
<!-- ##### FUNCTION g_object_set_qdata ##### -->
<para>
This sets an opaque, named pointer on an object.
The name is specified through a #GQuark (retrived e.g. via
g_quark_from_static_string()), and the pointer
can be gotten back from the @object with g_object_get_qdata()
until the @object is finalized.
Setting a previously set user data pointer, overrides (frees)
the old pointer set, using #NULL as pointer essentially
removes the data stored.
</para>
@object: The GObject to set store a user data pointer
@quark: A #GQuark, naming the user data pointer
@data: An opaque user data pointer
<!-- ##### FUNCTION g_object_set_qdata_full ##### -->
<para>
This function works like g_object_set_qdata(), but in addition,
a void (*destroy) (gpointer) function may be specified which is
called with @data as argument when the @object is finalized, or
the data is being overwritten by a call to g_object_set_qdata()
with the same @quark.
</para>
@object: The GObject to set store a user data pointer
@quark: A #GQuark, naming the user data pointer
@data: An opaque user data pointer
@destroy: Function to invoke with @data as argument, when @data needs to be freed
<!-- ##### FUNCTION g_object_steal_qdata ##### -->
<para>
This function gets back user data pointers stored via
g_object_set_qdata() and removes the @data from object
without invoking it's destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
<programlisting>
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
/* the quark, naming the object data */
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
/* retrive the old string list */
GList *list = g_object_steal_qdata (object, quark_string_list);
/* prepend new string */
list = g_list_prepend (list, g_strdup (new_string));
/* this changed 'list', so we need to set it again */
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
</programlisting>
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
would have left the destroy function set, and thus the partial string list would
have been freed upon g_object_set_qdata_full().
</para>
@object: The GObject to get a stored user data pointer from
@quark: A #GQuark, naming the user data pointer
@Returns: The user data pointer set, or %NULL
<!-- ##### FUNCTION g_object_set_property ##### -->
<para>
Sets a property on an object.
</para>
@object: a #GObject
@property_name: the name of the property to set
@value: the value
<!-- ##### FUNCTION g_object_get_property ##### -->
<para>
Gets a property of an object.
</para>
<para>
In general, a copy is made of the property contents and the caller is
responsible for freeing the memory in the appropriate manner for the type,
for instance by calling g_free() or g_object_unref().
</para>
<para>
See g_object_get().
</para>
@object: a #GObject
@property_name: the name of the property to get
@value: return location for the property value
<!-- ##### FUNCTION g_object_new_valist ##### -->
<para>
Creates a new instance of a #GObject subtype and sets its properties.
</para>
<para>
Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
which are not explicitly specified are set to their default values.
</para>
@object_type: the type id of the #GObject subtype to instantiate
@first_property_name: the name of the first property
@var_args: the value of the first property, followed optionally by more
name/value pairs, followed by %NULL
@Returns: a new instance of @object_type
<!-- ##### FUNCTION g_object_set_valist ##### -->
<para>
Sets properties on an object.
</para>
@object: a #GObject
@first_property_name: name of the first property to set
@var_args: value for the first property, followed optionally by more
name/value pairs, followed by %NULL
<!-- ##### FUNCTION g_object_get_valist ##### -->
<para>
Gets properties of an object.
</para>
<para>
In general, a copy is made of the property contents and the caller is
responsible for freeing the memory in the appropriate manner for the type,
for instance by calling g_free() or g_object_unref().
</para>
<para>
See g_object_get().
</para>
@object: a #GObject
@first_property_name: name of the first property to get
@var_args: return location for the first property, followed optionally by more
name/return location pairs, followed by %NULL
<!-- ##### FUNCTION g_object_watch_closure ##### -->
<para>
This function essentially limits the life time of the @closure
to the life time of the object. That is, when the object is finalized,
the @closure is invalidated by calling g_closure_invalidate() on it,
in order to prevent invocations of the closure with a finalized (non
existing) object. Also, g_object_ref() and g_object_unref() are added
as marshal guards to the @closure, to ensure that an extra reference
count is held on @object during invocation of the @closure.
Usually, this function will be called on closures that use this @object
as closure data.
</para>
@object: GObject restricting lifetime of @closure
@closure: GClosure to watch
<!-- ##### FUNCTION g_object_run_dispose ##### -->
<para>
Releases all references to other objects. This can be used to break
reference cycles.
</para>
<note><para>
This functions should only be called from object system implementations.
</para></note>
@object: a #GObject
<!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->
<para>
This macros should be used to emit a standard warning about unexpected
properties in set_property() and get_property() implementations.
</para>
@object: the #GObject on which set_property() or get_property() was called
@property_id: the numeric id of the property
@pspec: the #GParamSpec of the property