objects.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

</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: the same @object


<!-- ##### FUNCTION g_object_unref ##### -->
<para>
Decreases the reference count of @object.
When its reference count drops to 0, the object is finalized 
(i.e. its memory is freed).
</para>

@object: a #GObject


<!-- ##### FUNCTION g_object_ref_sink ##### -->
<para>
Increase the reference count of @object, and possibly remove the 
<link linkend="floating-ref">floating</link> reference, if @object
has a floating reference.
</para>
<para>
In other words, if the object is floating, then this call "assumes 
ownership" of the floating reference, converting it to a normal reference 
by clearing the floating flag while leaving the reference count unchanged. 
If the object is not floating, then this call adds a new normal reference 
increasing the reference count by one.
</para>

@object: a #GObject
@Returns: @object
@Since: 2.10


<!-- ##### TYPEDEF GInitiallyUnowned ##### -->
<para>
All the fields in the <structname>GInitiallyUnowned</structname> structure 
are private to the #GInitiallyUnowned implementation and should never be 
accessed directly.
</para>


<!-- ##### TYPEDEF GInitiallyUnownedClass ##### -->
<para>
The class structure for the <structname>GInitiallyUnowned</structname> type.
</para>


<!-- ##### MACRO G_TYPE_INITIALLY_UNOWNED ##### -->
<para>
The type for #GInitiallyUnowned.
</para>



<!-- ##### FUNCTION g_object_is_floating ##### -->
<para>
Checks wether @object has a <link linkend="floating-ref">floating</link>
reference.
</para>

@object: a #GObject
@Returns: %TRUE if @object has a floating reference
@Since: 2.10


<!-- ##### FUNCTION g_object_force_floating ##### -->
<para>
This function is intended for #GObject implementations to re-enforce a
<link linkend="floating-ref">floating</link> object reference.
Doing this is seldomly required, all
#GInitiallyUnowned<!-- -->s are created with a floating reference which 
usually just needs to be sunken by calling g_object_ref_sink().
</para>

@object: a #GObject
@Since: 2.10


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


<!-- ##### USER_FUNCTION GToggleNotify ##### -->
<para>
A callback function used for notification when the state
of a toggle reference changes. See g_object_add_toggle_ref().
</para>

@data: Callback data passed to g_object_add_toggle_ref()
@object: The object on which g_object_add_toggle_ref() was called.
@is_last_ref: %TRUE if the toggle reference is now the
  last reference to the object. %FALSE if the toggle
  reference was the last reference and there are now other
  references.


<!-- ##### FUNCTION g_object_add_toggle_ref ##### -->
<para>
Increases the reference count of the object by one and sets a
callback to be called when all other references to the object are
dropped, or when this is already the last reference to the object
and another reference is established.
</para>
<para>
This functionality is intended for binding @object to a proxy
object managed by another memory manager. This is done with two
paired references: the strong reference added by
g_object_add_toggle_ref() and a reverse reference to the proxy
object which is either a strong reference or weak reference.
</para>
<para>
The setup is that when there are no other references to @object,
only a weak reference is held in the reverse direction from @object
to the proxy object, but when there are other references held to
@object, a strong reference is held. The @notify callback is called
when the reference from @object to the proxy object should be
<firstterm>toggled</firstterm> from strong to weak (@is_last_ref
true) or weak to strong (@is_last_ref false).
</para>
<para>
Since a (normal) reference must be held to the object before
calling g_object_toggle_ref(), the initial state of the reverse
link is always strong.
</para>
<para>
Multiple toggle references may be added to the same gobject,
however if there are multiple toggle references to an object, none
of them will ever be notified until all but one are removed.  For
this reason, you should only ever use a toggle reference if there
is important state in the proxy object.
</para>

@object: a #GObject
@notify: a function to call when this reference is the
  last reference to the object, or is no longer
  the last reference.
@data: data to pass to @notify
@Since: 2.8


<!-- ##### FUNCTION g_object_remove_toggle_ref ##### -->
<para>
Removes a reference added with g_object_add_toggle_ref(). The
reference count of the object is decreased by one.
</para>

@object: a #GObject
@notify: a function to call when this reference is the
  last reference to the object, or is no longer
  the last reference.
@data: data to pass to @notify
@Since: 2.8


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