mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-28 16:36:14 +01:00
2118d96318
2004-10-05 Matthias Clasen <mclasen@redhat.com> * gobject/tmpl/objects.sgml: Improve the docs for g_object_get_property(). (#153424, Stefan Kost)
869 lines
26 KiB
Plaintext
869 lines
26 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>
|
|
|
|
|
|
<!-- ##### SIGNAL GObject::notify ##### -->
|
|
<para>
|
|
The notify signal is emitted on an object when one of its properties
|
|
has been changed. Note that getting this signal doesn't guarantee that the
|
|
value of the property has actually changed, it may also be emitted when
|
|
the setter for the property is called to reinstate the previous value.
|
|
</para>
|
|
|
|
@gobject: the object which received the signal.
|
|
@pspec: the #GParamSpec of the property which changed
|
|
|
|
<!-- ##### STRUCT GObjectClass ##### -->
|
|
<para>
|
|
The class structure for the <structname>GObject</structname> type.
|
|
</para>
|
|
|
|
@g_type_class: the parent class
|
|
@constructor: the @constructor function is called by g_object_new () to
|
|
complete the object initialization after all the construction properties are
|
|
set. The first thing a @constructor implementation must do is chain up to the
|
|
@constructor of the parent class. Overriding @constructor should be rarely
|
|
needed.
|
|
@set_property: the generic setter for all properties of this type. Should be
|
|
overridden for every type with properties. Implementations of @set_property
|
|
don't need to emit property change notification explicitly, this is handled
|
|
by the type system.
|
|
@get_property: the generic getter for all properties of this type. Should be
|
|
overridden for every type with properties.
|
|
@dispose: the @dispose function is supposed to drop all references to other
|
|
objects, but keep the instance otherwise intact, so that client method
|
|
invocations still work. It may be run multiple times (due to reference
|
|
loops). Before returning, @dispose should chain up to the @dispose method
|
|
of the parent class.
|
|
@finalize: instance finalization function, should finish the finalization of
|
|
the instance begun in @dispose and chain up to the @finalize method of the
|
|
parent class.
|
|
@dispatch_properties_changed: emits property change notification for a bunch
|
|
of properties. Overriding @dispatch_properties_changed should be rarely
|
|
needed.
|
|
@notify: the class closure for the notify signal
|
|
|
|
<!-- ##### STRUCT GObjectConstructParam ##### -->
|
|
<para>
|
|
The <structname>GObjectConstructParam</structname> struct is an auxiliary
|
|
structure used to hand #GParamSpec/#GValue pairs to the @constructor of
|
|
a #GObjectClass.
|
|
</para>
|
|
|
|
@pspec: the #GParamSpec of the construct parameter
|
|
@value: the value to set the parameter to
|
|
|
|
<!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
|
|
<para>
|
|
The type of the @get_property function of #GObjectClass.
|
|
</para>
|
|
|
|
@object: a #GObject
|
|
@property_id: the numeric id under which the property was registered with
|
|
g_object_class_install_property().
|
|
@value: a #GValue to return the property value in
|
|
@pspec: the #GParamSpec describing the property
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
|
|
<para>
|
|
The type of the @set_property function of #GObjectClass.
|
|
</para>
|
|
|
|
@object: a #GObject
|
|
@property_id: the numeric id under which the property was registered with
|
|
g_object_class_install_property().
|
|
@value: the new value for the property
|
|
@pspec: the #GParamSpec describing the property
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
|
|
<para>
|
|
The type of the @finalize function of #GObjectClass.
|
|
</para>
|
|
|
|
@object: the #GObject being finalized
|
|
|
|
|
|
<!-- ##### 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_class_override_property ##### -->
|
|
<para>
|
|
Registers @property_id as referring to a property with the
|
|
name @name in a parent class or in an interface implemented
|
|
by @oclass. This allows this class to <firstterm>override</firstterm>
|
|
a property implementation in a parent class or to provide
|
|
the implementation of a property from an interface.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Internally, overriding is implemented by creating a property of type
|
|
#GParamSpecOverride; generally operations that query the properties of
|
|
the object class, such as g_object_class_find_property() or
|
|
g_object_class_list_properties() will return the overridden
|
|
property. However, in one case, the @construct_properties argument of
|
|
the @constructor virtual function, the #GParamSpecOverride is passed
|
|
instead, so that the @param_id field of the #GParamSpec will be
|
|
correct. For virtually all uses, this makes no difference. If you
|
|
need to get the overridden property, you can call
|
|
g_param_spec_get_redirect_target().
|
|
</para>
|
|
</note>
|
|
|
|
@oclass: a #GObjectClass
|
|
@property_id: the new property ID
|
|
@name: the name of a property registered in a parent class or
|
|
in an interface of this class.
|
|
|
|
|
|
<!-- ##### FUNCTION g_object_interface_install_property ##### -->
|
|
<para>
|
|
Add a property to an interface; this is only useful for interfaces
|
|
that are added to GObject-derived types. Adding a property to an
|
|
interface forces all objects classes with that interface to have a
|
|
compatible property. The compatible property could be a newly
|
|
created #GParamSpec, but normally
|
|
g_object_class_override_property() will be used so that the object
|
|
class only needs to provide an implementation and inherits the
|
|
property description, default value, bounds, and so forth from the
|
|
interface property.
|
|
</para>
|
|
<para>
|
|
This function is meant to be called from the interface's default
|
|
vtable initialization function (the @class_init member of
|
|
#GTypeInfo.) It must not be called after after @class_init has
|
|
been called for any object types implementing this interface.
|
|
</para>
|
|
|
|
@g_iface: any interface vtable for the interface, or the default
|
|
vtable for the interface.
|
|
@pspec: the #GParamSpec for the new property
|
|
@Since: 2.4
|
|
|
|
|
|
<!-- ##### FUNCTION g_object_interface_find_property ##### -->
|
|
<para>
|
|
Find the #GParamSpec with the given name for an
|
|
interface. Generally, the interface vtable passed in as @g_iface
|
|
will be the default vtable from g_type_default_interface_ref(), or,
|
|
if you know the interface has already been loaded,
|
|
g_type_default_interface_peek().
|
|
</para>
|
|
|
|
@g_iface: any interface vtable for the interface, or the default
|
|
vtable for the interface
|
|
@property_name: name of a property to lookup.
|
|
@Returns: the #GParamSpec for the property of the
|
|
interface with the name @property_name, or %NULL
|
|
if no such property exists.
|
|
@Since: 2.4
|
|
|
|
|
|
<!-- ##### FUNCTION g_object_interface_list_properties ##### -->
|
|
<para>
|
|
Lists the properties of an interface.Generally, the interface
|
|
vtable passed in as @g_iface will be the default vtable from
|
|
g_type_default_interface_ref(), or, if you know the interface has
|
|
already been loaded, g_type_default_interface_peek().
|
|
</para>
|
|
|
|
@g_iface: any interface vtable for the interface, or the default
|
|
vtable for the interface
|
|
@n_properties_p: location to store number of properties returned.
|
|
@Returns: a pointer to an array of pointers to #GParamSpec structures.
|
|
The paramspecs are owned by GLib, but the array should
|
|
be freed with g_free() when you are done with it.
|
|
@Since: 2.4
|
|
|
|
|
|
<!-- ##### 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>
|
|
A #GWeakNotify function can be added to an object as a callback that gets
|
|
triggered when the object is finalized. Since the object is already being
|
|
finalized when the #GWeakNotify is called, there's not much you could do
|
|
with the object, apart from e.g. using its adress as hash-index or the like.
|
|
</para>
|
|
|
|
@data: data that was provided when the weak reference was established
|
|
@where_the_object_was: the object being finalized
|
|
|
|
|
|
<!-- ##### 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>
|
|
<term>object-signal</term>
|
|
<listitem><para>
|
|
equivalent to <literal>g_signal_connect_object (...)</literal>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>swapped_signal</term>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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, &menu->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", &intval,
|
|
"strproperty", &strval,
|
|
"objproperty", &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>
|
|
<para>
|
|
This is necessary for accessors that modify multiple properties to prevent
|
|
premature notification while the object is still being modified.
|
|
</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 by calling g_value_unset().
|
|
</para>
|
|
<para>
|
|
Note that g_object_get_property() is really intended for language
|
|
bindings, g_object_get() is much more convenient for C programming.
|
|
</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
|
|
(nonexisting) 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
|
|
|
|
|