<refentry id="gobject-The-Base-Object-Type">
<refmeta>
<refentrytitle>GObject</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GObject</refname><refpurpose>The base object type</refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<anchor id="GObject"/>
<synopsis>
#include <glib-object.h>
struct <link linkend="GObject-struct">GObject</link>;
struct <link linkend="GObjectClass">GObjectClass</link>;
struct <link linkend="GObjectConstructParam">GObjectConstructParam</link>;
<link linkend="void">void</link> (<link linkend="GObjectGetPropertyFunc">*GObjectGetPropertyFunc</link>) (<link linkend="GObject">GObject</link> *object,
<link linkend="guint">guint</link> property_id,
<link linkend="GValue">GValue</link> *value,
<link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="void">void</link> (<link linkend="GObjectSetPropertyFunc">*GObjectSetPropertyFunc</link>) (<link linkend="GObject">GObject</link> *object,
<link linkend="guint">guint</link> property_id,
const <link linkend="GValue">GValue</link> *value,
<link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="void">void</link> (<link linkend="GObjectFinalizeFunc">*GObjectFinalizeFunc</link>) (<link linkend="GObject">GObject</link> *object);
#define <link linkend="G-TYPE-IS-OBJECT-CAPS">G_TYPE_IS_OBJECT</link> (type)
#define <link linkend="G-OBJECT-CAPS">G_OBJECT</link> (object)
#define <link linkend="G-IS-OBJECT-CAPS">G_IS_OBJECT</link> (object)
#define <link linkend="G-OBJECT-CLASS-CAPS">G_OBJECT_CLASS</link> (class)
#define <link linkend="G-IS-OBJECT-CLASS-CAPS">G_IS_OBJECT_CLASS</link> (class)
#define <link linkend="G-OBJECT-GET-CLASS-CAPS">G_OBJECT_GET_CLASS</link> (object)
#define <link linkend="G-OBJECT-TYPE-CAPS">G_OBJECT_TYPE</link> (object)
#define <link linkend="G-OBJECT-TYPE-NAME-CAPS">G_OBJECT_TYPE_NAME</link> (object)
#define <link linkend="G-OBJECT-CLASS-TYPE-CAPS">G_OBJECT_CLASS_TYPE</link> (class)
#define <link linkend="G-OBJECT-CLASS-NAME-CAPS">G_OBJECT_CLASS_NAME</link> (class)
<link linkend="void">void</link> <link linkend="g-object-class-install-property">g_object_class_install_property</link> (<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> property_id,
<link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="GParamSpec">GParamSpec</link>* <link linkend="g-object-class-find-property">g_object_class_find_property</link> (<link linkend="GObjectClass">GObjectClass</link> *oclass,
const <link linkend="gchar">gchar</link> *property_name);
<link linkend="GParamSpec">GParamSpec</link>** <link linkend="g-object-class-list-properties">g_object_class_list_properties</link> (<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> *n_properties);
<link linkend="void">void</link> <link linkend="g-object-class-override-property">g_object_class_override_property</link>
(<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> property_id,
const <link linkend="gchar">gchar</link> *name);
<link linkend="void">void</link> <link linkend="g-object-interface-install-property">g_object_interface_install_property</link>
(<link linkend="gpointer">gpointer</link> g_iface,
<link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="GParamSpec">GParamSpec</link>* <link linkend="g-object-interface-find-property">g_object_interface_find_property</link>
(<link linkend="gpointer">gpointer</link> g_iface,
const <link linkend="gchar">gchar</link> *property_name);
<link linkend="GParamSpec">GParamSpec</link>** <link linkend="g-object-interface-list-properties">g_object_interface_list_properties</link>
(<link linkend="gpointer">gpointer</link> g_iface,
<link linkend="guint">guint</link> *n_properties_p);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-new">g_object_new</link> (<link linkend="GType">GType</link> object_type,
const <link linkend="gchar">gchar</link> *first_property_name,
...);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-newv">g_object_newv</link> (<link linkend="GType">GType</link> object_type,
<link linkend="guint">guint</link> n_parameters,
<link linkend="GParameter">GParameter</link> *parameters);
struct <link linkend="GParameter">GParameter</link>;
<link linkend="gpointer">gpointer</link> <link linkend="g-object-ref">g_object_ref</link> (<link linkend="gpointer">gpointer</link> object);
<link linkend="void">void</link> <link linkend="g-object-unref">g_object_unref</link> (<link linkend="gpointer">gpointer</link> object);
<link linkend="void">void</link> (<link linkend="GWeakNotify">*GWeakNotify</link>) (<link linkend="gpointer">gpointer</link> data,
<link linkend="GObject">GObject</link> *where_the_object_was);
<link linkend="void">void</link> <link linkend="g-object-weak-ref">g_object_weak_ref</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GWeakNotify">GWeakNotify</link> notify,
<link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link> <link linkend="g-object-weak-unref">g_object_weak_unref</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GWeakNotify">GWeakNotify</link> notify,
<link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link> <link linkend="g-object-add-weak-pointer">g_object_add_weak_pointer</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="gpointer">gpointer</link> *weak_pointer_location);
<link linkend="void">void</link> <link linkend="g-object-remove-weak-pointer">g_object_remove_weak_pointer</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="gpointer">gpointer</link> *weak_pointer_location);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-connect">g_object_connect</link> (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *signal_spec,
...);
<link linkend="void">void</link> <link linkend="g-object-disconnect">g_object_disconnect</link> (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *signal_spec,
...);
<link linkend="void">void</link> <link linkend="g-object-set">g_object_set</link> (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *first_property_name,
...);
<link linkend="void">void</link> <link linkend="g-object-get">g_object_get</link> (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *first_property_name,
...);
<link linkend="void">void</link> <link linkend="g-object-notify">g_object_notify</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name);
<link linkend="void">void</link> <link linkend="g-object-freeze-notify">g_object_freeze_notify</link> (<link linkend="GObject">GObject</link> *object);
<link linkend="void">void</link> <link linkend="g-object-thaw-notify">g_object_thaw_notify</link> (<link linkend="GObject">GObject</link> *object);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-get-data">g_object_get_data</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key);
<link linkend="void">void</link> <link linkend="g-object-set-data">g_object_set_data</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key,
<link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link> <link linkend="g-object-set-data-full">g_object_set_data_full</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-steal-data">g_object_steal_data</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-get-qdata">g_object_get_qdata</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark);
<link linkend="void">void</link> <link linkend="g-object-set-qdata">g_object_set_qdata</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark,
<link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link> <link linkend="g-object-set-qdata-full">g_object_set_qdata_full</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="gpointer">gpointer</link> <link linkend="g-object-steal-qdata">g_object_steal_qdata</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark);
<link linkend="void">void</link> <link linkend="g-object-set-property">g_object_set_property</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name,
const <link linkend="GValue">GValue</link> *value);
<link linkend="void">void</link> <link linkend="g-object-get-property">g_object_get_property</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name,
<link linkend="GValue">GValue</link> *value);
<link linkend="GObject">GObject</link>* <link linkend="g-object-new-valist">g_object_new_valist</link> (<link linkend="GType">GType</link> object_type,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);
<link linkend="void">void</link> <link linkend="g-object-set-valist">g_object_set_valist</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);
<link linkend="void">void</link> <link linkend="g-object-get-valist">g_object_get_valist</link> (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);
<link linkend="void">void</link> <link linkend="g-object-watch-closure">g_object_watch_closure</link> (<link linkend="GObject">GObject</link> *object,
<link linkend="GClosure">GClosure</link> *closure);
<link linkend="void">void</link> <link linkend="g-object-run-dispose">g_object_run_dispose</link> (<link linkend="GObject">GObject</link> *object);
#define <link linkend="G-OBJECT-WARN-INVALID-PROPERTY-ID-CAPS">G_OBJECT_WARN_INVALID_PROPERTY_ID</link>(object, property_id, pspec)
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Object Hierarchy</title>
<synopsis>
GObject
+----<link linkend="GTypeModule">GTypeModule</link>
</synopsis>
</refsect1>
<refsect1>
<title>Signal Prototypes</title>
<synopsis>
"<link linkend="GObject-notify">notify</link>" <link linkend="void">void</link> user_function (<link linkend="GObject">GObject</link> *gobject,
<link linkend="GParamSpec">GParamSpec</link> *arg1,
<link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GObject-struct"/>struct GObject</title>
<indexterm><primary>GObject</primary></indexterm><programlisting>struct GObject;</programlisting>
<para>
All the fields in the <structname>GObject</structname> structure are private
to the <link linkend="GObject"><type>GObject</type></link> implementation and should never be accessed directly.
</para></refsect2>
<refsect2>
<title><anchor id="GObjectClass"/>struct GObjectClass</title>
<indexterm><primary>GObjectClass</primary></indexterm><programlisting>struct GObjectClass {
GTypeClass g_type_class;
/* overridable methods */
GObject* (*constructor) (GType type,
guint n_construct_properties,
GObjectConstructParam *construct_properties);
void (*set_property) (GObject *object,
guint property_id,
const GValue *value,
GParamSpec *pspec);
void (*get_property) (GObject *object,
guint property_id,
GValue *value,
GParamSpec *pspec);
void (*dispose) (GObject *object);
void (*finalize) (GObject *object);
/* seldomly overidden */
void (*dispatch_properties_changed) (GObject *object,
guint n_pspecs,
GParamSpec **pspecs);
/* signals */
void (*notify) (GObject *object,
GParamSpec *pspec);
};
</programlisting>
<para>
The class structure for the <structname>GObject</structname> type.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTypeClass">GTypeClass</link> <structfield>g_type_class</structfield></term>
<listitem><simpara>the parent class
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GObject">GObject</link>* (*<structfield>constructor</structfield>) (GType type,
guint n_construct_properties,
GObjectConstructParam *construct_properties)</term>
<listitem><simpara> the <parameter>constructor</parameter> function is called by <link linkend="g-object-new"><function>g_object_new()</function></link> to
complete the object initialization after all the construction properties are
set. The first thing a <parameter>constructor</parameter> implementation must do is chain up to the
<parameter>constructor</parameter> of the parent class. Overriding <parameter>constructor</parameter> should be rarely
needed.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>set_property</structfield>) (GObject *object,
guint property_id,
const GValue *value,
GParamSpec *pspec)</term>
<listitem><simpara>the generic setter for all properties of this type. Should be
overridden for every type with properties. Implementations of <parameter>set_property</parameter>
don't need to emit property change notification explicitly, this is handled
by the type system.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>get_property</structfield>) (GObject *object,
guint property_id,
GValue *value,
GParamSpec *pspec)</term>
<listitem><simpara>the generic getter for all properties of this type. Should be
overridden for every type with properties.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>dispose</structfield>) (GObject *object)</term>
<listitem><simpara>the <parameter>dispose</parameter> 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, <parameter>dispose</parameter> should chain up to the <parameter>dispose</parameter> method
of the parent class.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>finalize</structfield>) (GObject *object)</term>
<listitem><simpara>instance finalization function, should finish the finalization of
the instance begun in <parameter>dispose</parameter> and chain up to the <parameter>finalize</parameter> method of the
parent class.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>dispatch_properties_changed</structfield>) (GObject *object,
guint n_pspecs,
GParamSpec **pspecs)</term>
<listitem><simpara>emits property change notification for a bunch
of properties. Overriding <parameter>dispatch_properties_changed</parameter> should be rarely
needed.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>notify</structfield>) (GObject *object,
GParamSpec *pspec)</term>
<listitem><simpara>the class closure for the notify signal
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GObjectConstructParam"/>struct GObjectConstructParam</title>
<indexterm><primary>GObjectConstructParam</primary></indexterm><programlisting>struct GObjectConstructParam {
GParamSpec *pspec;
GValue *value;
};
</programlisting>
<para>
The <structname>GObjectConstructParam</structname> struct is an auxiliary
structure used to hand <link linkend="GParamSpec"><type>GParamSpec</type></link>/<link linkend="GValue"><type>GValue</type></link> pairs to the <parameter>constructor</parameter> of
a <link linkend="GObjectClass"><type>GObjectClass</type></link>.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GParamSpec">GParamSpec</link> *<structfield>pspec</structfield></term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> of the construct parameter
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GValue">GValue</link> *<structfield>value</structfield></term>
<listitem><simpara>the value to set the parameter to
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GObjectGetPropertyFunc"/>GObjectGetPropertyFunc ()</title>
<indexterm><primary>GObjectGetPropertyFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GObjectGetPropertyFunc) (<link linkend="GObject">GObject</link> *object,
<link linkend="guint">guint</link> property_id,
<link linkend="GValue">GValue</link> *value,
<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
The type of the <parameter>get_property</parameter> function of <link linkend="GObjectClass"><type>GObjectClass</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_id</parameter> :</term>
<listitem><simpara>the numeric id under which the property was registered with
<link linkend="g-object-class-install-property"><function>g_object_class_install_property()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara>a <link linkend="GValue"><type>GValue</type></link> to return the property value in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> describing the property
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GObjectSetPropertyFunc"/>GObjectSetPropertyFunc ()</title>
<indexterm><primary>GObjectSetPropertyFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GObjectSetPropertyFunc) (<link linkend="GObject">GObject</link> *object,
<link linkend="guint">guint</link> property_id,
const <link linkend="GValue">GValue</link> *value,
<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
The type of the <parameter>set_property</parameter> function of <link linkend="GObjectClass"><type>GObjectClass</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_id</parameter> :</term>
<listitem><simpara>the numeric id under which the property was registered with
<link linkend="g-object-class-install-property"><function>g_object_class_install_property()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara>the new value for the property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> describing the property
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GObjectFinalizeFunc"/>GObjectFinalizeFunc ()</title>
<indexterm><primary>GObjectFinalizeFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GObjectFinalizeFunc) (<link linkend="GObject">GObject</link> *object);</programlisting>
<para>
The type of the <parameter>finalize</parameter> function of <link linkend="GObjectClass"><type>GObjectClass</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>the <link linkend="GObject"><type>GObject</type></link> being finalized
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-TYPE-IS-OBJECT-CAPS"/>G_TYPE_IS_OBJECT()</title>
<indexterm><primary>G_TYPE_IS_OBJECT</primary></indexterm><programlisting>#define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT)
</programlisting>
<para>
Returns a boolean value of <literal>FALSE</literal> or <literal>TRUE</literal> indicating whether
the passed in type id is a <literal>G_TYPE_OBJECT</literal> or derived from it.
</para><variablelist role="params">
<varlistentry><term><parameter>type</parameter> :</term>
<listitem><simpara>Type id to check for is a <literal>G_TYPE_OBJECT</literal> relationship.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>FALSE</literal> or <literal>TRUE</literal>, indicating whether <parameter>type</parameter> is a <literal>G_TYPE_OBJECT</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CAPS"/>G_OBJECT()</title>
<indexterm><primary>G_OBJECT</primary></indexterm><programlisting>#define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject))
</programlisting>
<para>
Casts a <link linkend="GObject"><type>GObject</type></link> 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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>Object which is subject to casting.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-IS-OBJECT-CAPS"/>G_IS_OBJECT()</title>
<indexterm><primary>G_IS_OBJECT</primary></indexterm><programlisting>#define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))
</programlisting>
<para>
Checks whether a valid <link linkend="GTypeInstance"><type>GTypeInstance</type></link> pointer is of type <literal>G_TYPE_OBJECT</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>Instance to check for being a <literal>G_TYPE_OBJECT</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CLASS-CAPS"/>G_OBJECT_CLASS()</title>
<indexterm><primary>G_OBJECT_CLASS</primary></indexterm><programlisting>#define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass))
</programlisting>
<para>
Casts a derived <link linkend="GObjectClass"><type>GObjectClass</type></link> structure into a <link linkend="GObjectClass"><type>GObjectClass</type></link> structure.
</para><variablelist role="params">
<varlistentry><term><parameter>class</parameter> :</term>
<listitem><simpara>a valid <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-IS-OBJECT-CLASS-CAPS"/>G_IS_OBJECT_CLASS()</title>
<indexterm><primary>G_IS_OBJECT_CLASS</primary></indexterm><programlisting>#define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))
</programlisting>
<para>
Checks whether <parameter>class</parameter> "is a" valid <link linkend="GObjectClass"><type>GObjectClass</type></link> structure of type
<literal>G_TYPE_OBJECT</literal> or derived.
</para><variablelist role="params">
<varlistentry><term><parameter>class</parameter> :</term>
<listitem><simpara>a <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-GET-CLASS-CAPS"/>G_OBJECT_GET_CLASS()</title>
<indexterm><primary>G_OBJECT_GET_CLASS</primary></indexterm><programlisting>#define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass))
</programlisting>
<para>
Returns the class structure associated to a <link linkend="GObject"><type>GObject</type></link> instance.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link> instance.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-TYPE-CAPS"/>G_OBJECT_TYPE()</title>
<indexterm><primary>G_OBJECT_TYPE</primary></indexterm><programlisting>#define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object))
</programlisting>
<para>
Return the type id of an object.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>Object to return the type id for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>Type id of <parameter>object</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-TYPE-NAME-CAPS"/>G_OBJECT_TYPE_NAME()</title>
<indexterm><primary>G_OBJECT_TYPE_NAME</primary></indexterm><programlisting>#define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object)))
</programlisting>
<para>
Returns the name of an object's type.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>Object to return the type name for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>Type name of <parameter>object</parameter>. The string is owned by the type system and
should not be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CLASS-TYPE-CAPS"/>G_OBJECT_CLASS_TYPE()</title>
<indexterm><primary>G_OBJECT_CLASS_TYPE</primary></indexterm><programlisting>#define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
</programlisting>
<para>
Return the type id of a class structure.
</para><variablelist role="params">
<varlistentry><term><parameter>class</parameter> :</term>
<listitem><simpara>a valid <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>Type id of <parameter>class</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CLASS-NAME-CAPS"/>G_OBJECT_CLASS_NAME()</title>
<indexterm><primary>G_OBJECT_CLASS_NAME</primary></indexterm><programlisting>#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class)))
</programlisting>
<para>
Return the name of a class structure's type.
</para><variablelist role="params">
<varlistentry><term><parameter>class</parameter> :</term>
<listitem><simpara>a valid <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>Type name of <parameter>class</parameter>. The string is owned by the type system and
should not be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-class-install-property"/>g_object_class_install_property ()</title>
<indexterm><primary>g_object_class_install_property</primary></indexterm><programlisting><link linkend="void">void</link> g_object_class_install_property (<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> property_id,
<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
Installs a new property. This is usually done in the class initializer.
</para><variablelist role="params">
<varlistentry><term><parameter>oclass</parameter> :</term>
<listitem><simpara>a <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_id</parameter> :</term>
<listitem><simpara>the id for the new property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> for the new property
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-class-find-property"/>g_object_class_find_property ()</title>
<indexterm><primary>g_object_class_find_property</primary></indexterm><programlisting><link linkend="GParamSpec">GParamSpec</link>* g_object_class_find_property (<link linkend="GObjectClass">GObjectClass</link> *oclass,
const <link linkend="gchar">gchar</link> *property_name);</programlisting>
<para>
Looks up the <link linkend="GParamSpec"><type>GParamSpec</type></link> for a property of a class.
</para><variablelist role="params">
<varlistentry><term><parameter>oclass</parameter> :</term>
<listitem><simpara>a <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_name</parameter> :</term>
<listitem><simpara>the name of the property to look up
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> for the property, or <literal>NULL</literal> if the class doesn't have
a property of that name
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-class-list-properties"/>g_object_class_list_properties ()</title>
<indexterm><primary>g_object_class_list_properties</primary></indexterm><programlisting><link linkend="GParamSpec">GParamSpec</link>** g_object_class_list_properties (<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> *n_properties);</programlisting>
<para>
Returns an array of <link linkend="GParamSpec"><type>GParamSpec</type></link>* for all properties of a class.
</para><variablelist role="params">
<varlistentry><term><parameter>oclass</parameter> :</term>
<listitem><simpara>a <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_properties</parameter> :</term>
<listitem><simpara>return location for the length of the returned array
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>an array of <link linkend="GParamSpec"><type>GParamSpec</type></link>* which should be freed after use
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-class-override-property"/>g_object_class_override_property ()</title>
<indexterm><primary>g_object_class_override_property</primary></indexterm><programlisting><link linkend="void">void</link> g_object_class_override_property
(<link linkend="GObjectClass">GObjectClass</link> *oclass,
<link linkend="guint">guint</link> property_id,
const <link linkend="gchar">gchar</link> *name);</programlisting>
<para>
Registers <parameter>property_id</parameter> as referring to a property with the
name <parameter>name</parameter> in a parent class or in an interface implemented
by <parameter>oclass</parameter>. 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
<link linkend="GParamSpecOverride"><type>GParamSpecOverride</type></link>; generally operations that query the properties of
the object class, such as <link linkend="g-object-class-find-property"><function>g_object_class_find_property()</function></link> or
<link linkend="g-object-class-list-properties"><function>g_object_class_list_properties()</function></link> will return the overridden
property. However, in one case, the <parameter>construct_properties</parameter> argument of
the <parameter>constructor</parameter> virtual function, the <link linkend="GParamSpecOverride"><type>GParamSpecOverride</type></link> is passed
instead, so that the <parameter>param_id</parameter> field of the <link linkend="GParamSpec"><type>GParamSpec</type></link> will be
correct. For virtually all uses, this makes no difference. If you
need to get the overridden property, you can call
<link linkend="g-param-spec-get-redirect-target"><function>g_param_spec_get_redirect_target()</function></link>.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>oclass</parameter> :</term>
<listitem><simpara>a <link linkend="GObjectClass"><type>GObjectClass</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_id</parameter> :</term>
<listitem><simpara>the new property ID
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter> :</term>
<listitem><simpara>the name of a property registered in a parent class or
in an interface of this class.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-interface-install-property"/>g_object_interface_install_property ()</title>
<indexterm role="2.4"><primary>g_object_interface_install_property</primary></indexterm><programlisting><link linkend="void">void</link> g_object_interface_install_property
(<link linkend="gpointer">gpointer</link> g_iface,
<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<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 <link linkend="GParamSpec"><type>GParamSpec</type></link>, but normally
<link linkend="g-object-class-override-property"><function>g_object_class_override_property()</function></link> 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 <parameter>class_init</parameter> member of
<link linkend="GTypeInfo"><type>GTypeInfo</type></link>.) It must not be called after after <parameter>class_init</parameter> has
been called for any object types implementing this interface.
</para><variablelist role="params">
<varlistentry><term><parameter>g_iface</parameter> :</term>
<listitem><simpara>any interface vtable for the interface, or the default
vtable for the interface.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> for the new property
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-object-interface-find-property"/>g_object_interface_find_property ()</title>
<indexterm role="2.4"><primary>g_object_interface_find_property</primary></indexterm><programlisting><link linkend="GParamSpec">GParamSpec</link>* g_object_interface_find_property
(<link linkend="gpointer">gpointer</link> g_iface,
const <link linkend="gchar">gchar</link> *property_name);</programlisting>
<para>
Find the <link linkend="GParamSpec"><type>GParamSpec</type></link> with the given name for an
interface. Generally, the interface vtable passed in as <parameter>g_iface</parameter>
will be the default vtable from <link linkend="g-type-default-interface-ref"><function>g_type_default_interface_ref()</function></link>, or,
if you know the interface has already been loaded,
<link linkend="g-type-default-interface-peek"><function>g_type_default_interface_peek()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>g_iface</parameter> :</term>
<listitem><simpara>any interface vtable for the interface, or the default
vtable for the interface
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_name</parameter> :</term>
<listitem><simpara>name of a property to lookup.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> for the property of the
interface with the name <parameter>property_name</parameter>, or <literal>NULL</literal>
if no such property exists.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-object-interface-list-properties"/>g_object_interface_list_properties ()</title>
<indexterm role="2.4"><primary>g_object_interface_list_properties</primary></indexterm><programlisting><link linkend="GParamSpec">GParamSpec</link>** g_object_interface_list_properties
(<link linkend="gpointer">gpointer</link> g_iface,
<link linkend="guint">guint</link> *n_properties_p);</programlisting>
<para>
Lists the properties of an interface.Generally, the interface
vtable passed in as <parameter>g_iface</parameter> will be the default vtable from
<link linkend="g-type-default-interface-ref"><function>g_type_default_interface_ref()</function></link>, or, if you know the interface has
already been loaded, <link linkend="g-type-default-interface-peek"><function>g_type_default_interface_peek()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>g_iface</parameter> :</term>
<listitem><simpara>any interface vtable for the interface, or the default
vtable for the interface
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_properties_p</parameter> :</term>
<listitem><simpara>location to store number of properties returned.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a pointer to an array of pointers to <link linkend="GParamSpec"><type>GParamSpec</type></link> structures.
The paramspecs are owned by GLib, but the array should
be freed with <link linkend="g-free"><function>g_free()</function></link> when you are done with it.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-object-new"/>g_object_new ()</title>
<indexterm><primary>g_object_new</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_new (<link linkend="GType">GType</link> object_type,
const <link linkend="gchar">gchar</link> *first_property_name,
...);</programlisting>
<para>
Creates a new instance of a <link linkend="GObject"><type>GObject</type></link> subtype and sets its properties.
</para>
<para>
Construction parameters (see <link linkend="G-PARAM-CONSTRUCT-CAPS"><type>G_PARAM_CONSTRUCT</type></link>, <link linkend="G-PARAM-CONSTRUCT-ONLY-CAPS"><type>G_PARAM_CONSTRUCT_ONLY</type></link>)
which are not explicitly specified are set to their default values.
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter> :</term>
<listitem><simpara>the type id of the <link linkend="GObject"><type>GObject</type></link> subtype to instantiate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>the name of the first property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>the value of the first property, followed optionally by more
name/value pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new instance of <parameter>object_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-newv"/>g_object_newv ()</title>
<indexterm><primary>g_object_newv</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_newv (<link linkend="GType">GType</link> object_type,
<link linkend="guint">guint</link> n_parameters,
<link linkend="GParameter">GParameter</link> *parameters);</programlisting>
<para>
Creates a new instance of a <link linkend="GObject"><type>GObject</type></link> subtype and sets its properties.
</para>
<para>
Construction parameters (see <link linkend="G-PARAM-CONSTRUCT-CAPS"><type>G_PARAM_CONSTRUCT</type></link>, <link linkend="G-PARAM-CONSTRUCT-ONLY-CAPS"><type>G_PARAM_CONSTRUCT_ONLY</type></link>)
which are not explicitly specified are set to their default values.
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter> :</term>
<listitem><simpara>the type id of the <link linkend="GObject"><type>GObject</type></link> subtype to instantiate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_parameters</parameter> :</term>
<listitem><simpara>the length of the <parameter>parameters</parameter> array
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>parameters</parameter> :</term>
<listitem><simpara>an array of <link linkend="GParameter"><type>GParameter</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new instance of <parameter>object_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GParameter"/>struct GParameter</title>
<indexterm><primary>GParameter</primary></indexterm><programlisting>struct GParameter {
const gchar *name;
GValue value;
};
</programlisting>
<para>
The <structname>GParameter</structname> struct is an auxiliary structure used
to hand parameter name/value pairs to <link linkend="g-object-newv"><function>g_object_newv()</function></link>.
</para><variablelist role="struct">
<varlistentry>
<term>const <link linkend="gchar">gchar</link> *<structfield>name</structfield></term>
<listitem><simpara>the parameter name
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GValue">GValue</link> <structfield>value</structfield></term>
<listitem><simpara>the parameter value
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-ref"/>g_object_ref ()</title>
<indexterm><primary>g_object_ref</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_ref (<link linkend="gpointer">gpointer</link> object);</programlisting>
<para>
Increases the reference count of <parameter>object</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><parameter>object</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-unref"/>g_object_unref ()</title>
<indexterm><primary>g_object_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_object_unref (<link linkend="gpointer">gpointer</link> object);</programlisting>
<para>
Decreases the reference count if <parameter>object</parameter>.
When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GWeakNotify"/>GWeakNotify ()</title>
<indexterm><primary>GWeakNotify</primary></indexterm><programlisting><link linkend="void">void</link> (*GWeakNotify) (<link linkend="gpointer">gpointer</link> data,
<link linkend="GObject">GObject</link> *where_the_object_was);</programlisting>
<para>
A <link linkend="GWeakNotify"><type>GWeakNotify</type></link> 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 <link linkend="GWeakNotify"><type>GWeakNotify</type></link> 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><variablelist role="params">
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>data that was provided when the weak reference was established
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>where_the_object_was</parameter> :</term>
<listitem><simpara>the object being finalized
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-weak-ref"/>g_object_weak_ref ()</title>
<indexterm><primary>g_object_weak_ref</primary></indexterm><programlisting><link linkend="void">void</link> g_object_weak_ref (<link linkend="GObject">GObject</link> *object,
<link linkend="GWeakNotify">GWeakNotify</link> notify,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<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
<link linkend="g-object-ref"><function>g_object_ref()</function></link> (<link linkend="g-object-ref"><function>g_object_ref()</function></link> adds a strong reference, that is, forces the
object to stay alive).
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> to reference weakly
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara>callback to invoke before the object is freed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>extra data to pass to notify
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-weak-unref"/>g_object_weak_unref ()</title>
<indexterm><primary>g_object_weak_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_object_weak_unref (<link linkend="GObject">GObject</link> *object,
<link linkend="GWeakNotify">GWeakNotify</link> notify,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Removes a weak reference callback to an object.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> to remove a weak reference from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara>callback to search for
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>data to search for
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-add-weak-pointer"/>g_object_add_weak_pointer ()</title>
<indexterm><primary>g_object_add_weak_pointer</primary></indexterm><programlisting><link linkend="void">void</link> g_object_add_weak_pointer (<link linkend="GObject">GObject</link> *object,
<link linkend="gpointer">gpointer</link> *weak_pointer_location);</programlisting>
<para>
Adds a weak reference from weak_pointer to <parameter>object</parameter> to indicate that
the pointer located at <parameter>weak_pointer_location</parameter> is only valid during the
lifetime of <parameter>object</parameter>. When the <parameter>object</parameter> is finalized, <parameter>weak_pointer</parameter> will
be set to <literal>NULL</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>The object that should be weak referenced.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>weak_pointer_location</parameter> :</term>
<listitem><simpara>The memory address of a pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-remove-weak-pointer"/>g_object_remove_weak_pointer ()</title>
<indexterm><primary>g_object_remove_weak_pointer</primary></indexterm><programlisting><link linkend="void">void</link> g_object_remove_weak_pointer (<link linkend="GObject">GObject</link> *object,
<link linkend="gpointer">gpointer</link> *weak_pointer_location);</programlisting>
<para>
Removes a weak reference from <parameter>object</parameter> that was previously added
using <link linkend="g-object-add-weak-pointer"><function>g_object_add_weak_pointer()</function></link>. The <parameter>weak_pointer_location</parameter> has
to match the one used with <link linkend="g-object-add-weak-pointer"><function>g_object_add_weak_pointer()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>The object that is weak referenced.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>weak_pointer_location</parameter> :</term>
<listitem><simpara>The memory address of a pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-connect"/>g_object_connect ()</title>
<indexterm><primary>g_object_connect</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_connect (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *signal_spec,
...);</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_spec</parameter> :</term>
<listitem><simpara>the spec for the first signal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara><link linkend="GCallback"><type>GCallback</type></link> for the first signal, followed by data for the first signal,
followed optionally by more signal spec/callback/data triples,
followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><parameter>object</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-disconnect"/>g_object_disconnect ()</title>
<indexterm><primary>g_object_disconnect</primary></indexterm><programlisting><link linkend="void">void</link> g_object_disconnect (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *signal_spec,
...);</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_spec</parameter> :</term>
<listitem><simpara>the spec for the first signal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara><link linkend="GCallback"><type>GCallback</type></link> for the first signal, followed by data for the first signal,
followed optionally by more signal spec/callback/data triples,
followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set"/>g_object_set ()</title>
<indexterm><primary>g_object_set</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *first_property_name,
...);</programlisting>
<para>
Sets properties on an object.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>name of the first property to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>value for the first property, followed optionally by more
name/value pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-get"/>g_object_get ()</title>
<indexterm><primary>g_object_get</primary></indexterm><programlisting><link linkend="void">void</link> g_object_get (<link linkend="gpointer">gpointer</link> object,
const <link linkend="gchar">gchar</link> *first_property_name,
...);</programlisting>
<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 <link linkend="g-free"><function>g_free()</function></link> or <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
</para>
<example>
<title>Using g_object_get(<!-- -->)</title>
<para>
An example of using <link linkend="g-object-get"><function>g_object_get()</function></link> to get the contents
of three properties - one of type <link linkend="G-TYPE-INT-CAPS"><type>G_TYPE_INT</type></link>,
one of type <link linkend="G-TYPE-STRING-CAPS"><type>G_TYPE_STRING</type></link>, and one of type <link linkend="G-TYPE-OBJECT-CAPS"><type>G_TYPE_OBJECT</type></link>:
</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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>name of the first property to get
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>return location for the first property, followed optionally by more
name/return location pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-notify"/>g_object_notify ()</title>
<indexterm><primary>g_object_notify</primary></indexterm><programlisting><link linkend="void">void</link> g_object_notify (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name);</programlisting>
<para>
Emits a "notify" signal for the property <parameter>property_name</parameter> on <parameter>object</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_name</parameter> :</term>
<listitem><simpara>the name of a property installed on the class of <parameter>object</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-freeze-notify"/>g_object_freeze_notify ()</title>
<indexterm><primary>g_object_freeze_notify</primary></indexterm><programlisting><link linkend="void">void</link> g_object_freeze_notify (<link linkend="GObject">GObject</link> *object);</programlisting>
<para>
Stops emission of "notify" signals on <parameter>object</parameter>. The signals are
queued until <link linkend="g-object-thaw-notify"><function>g_object_thaw_notify()</function></link> is called on <parameter>object</parameter>.
</para>
<para>
This is necessary for accessors that modify multiple properties to prevent
premature notification while the object is still being modified.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-thaw-notify"/>g_object_thaw_notify ()</title>
<indexterm><primary>g_object_thaw_notify</primary></indexterm><programlisting><link linkend="void">void</link> g_object_thaw_notify (<link linkend="GObject">GObject</link> *object);</programlisting>
<para>
Reverts the effect of a previous call to <link linkend="g-object-freeze-notify"><function>g_object_freeze_notify()</function></link>.
This causes all queued "notify" signals on <parameter>object</parameter> to be emitted.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-get-data"/>g_object_get_data ()</title>
<indexterm><primary>g_object_get_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_get_data (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key);</programlisting>
<para>
Gets a named field from the objects table of associations (see <link linkend="g-object-set-data"><function>g_object_set_data()</function></link>).
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> containing the associations
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara>name of the key for that association
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the data if found, or <literal>NULL</literal> if no such data exists.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-data"/>g_object_set_data ()</title>
<indexterm><primary>g_object_set_data</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_data (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> containing the associations.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara>name of the key
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>data to associate with that key
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-data-full"/>g_object_set_data_full ()</title>
<indexterm><primary>g_object_set_data_full</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_data_full (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<para>
Like <link linkend="g-object-set-data"><function>g_object_set_data()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> containing the associations
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara>name of the key
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>data to associate with that key
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter> :</term>
<listitem><simpara>function to call when the association is destroyed
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-steal-data"/>g_object_steal_data ()</title>
<indexterm><primary>g_object_steal_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_steal_data (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *key);</programlisting>
<para>
Remove a specified datum from the object's data associations,
without invoking the association's destroy handler.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara><link linkend="GObject"><type>GObject</type></link> containing the associations
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara>name of the key
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the data if found, or <literal>NULL</literal> if no such data exists.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-get-qdata"/>g_object_get_qdata ()</title>
<indexterm><primary>g_object_get_qdata</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_get_qdata (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark);</programlisting>
<para>
This function gets back user data pointers stored via
<link linkend="g-object-set-qdata"><function>g_object_set_qdata()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara> The GObject to get a stored user data pointer from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>quark</parameter> :</term>
<listitem><simpara> A <link linkend="GQuark"><type>GQuark</type></link>, naming the user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The user data pointer set, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-qdata"/>g_object_set_qdata ()</title>
<indexterm><primary>g_object_set_qdata</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_qdata (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
This sets an opaque, named pointer on an object.
The name is specified through a <link linkend="GQuark"><type>GQuark</type></link> (retrived e.g. via
<link linkend="g-quark-from-static-string"><function>g_quark_from_static_string()</function></link>), and the pointer
can be gotten back from the <parameter>object</parameter> with <link linkend="g-object-get-qdata"><function>g_object_get_qdata()</function></link>
until the <parameter>object</parameter> is finalized.
Setting a previously set user data pointer, overrides (frees)
the old pointer set, using <link linkend="NULL-CAPS"><type>NULL</type></link> as pointer essentially
removes the data stored.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>The GObject to set store a user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>quark</parameter> :</term>
<listitem><simpara> A <link linkend="GQuark"><type>GQuark</type></link>, naming the user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> An opaque user data pointer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-qdata-full"/>g_object_set_qdata_full ()</title>
<indexterm><primary>g_object_set_qdata_full</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_qdata_full (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<para>
This function works like <link linkend="g-object-set-qdata"><function>g_object_set_qdata()</function></link>, but in addition,
a void (*destroy) (gpointer) function may be specified which is
called with <parameter>data</parameter> as argument when the <parameter>object</parameter> is finalized, or
the data is being overwritten by a call to <link linkend="g-object-set-qdata"><function>g_object_set_qdata()</function></link>
with the same <parameter>quark</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara> The GObject to set store a user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>quark</parameter> :</term>
<listitem><simpara> A <link linkend="GQuark"><type>GQuark</type></link>, naming the user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> An opaque user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter> :</term>
<listitem><simpara>Function to invoke with <parameter>data</parameter> as argument, when <parameter>data</parameter> needs to be freed
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-steal-qdata"/>g_object_steal_qdata ()</title>
<indexterm><primary>g_object_steal_qdata</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_object_steal_qdata (<link linkend="GObject">GObject</link> *object,
<link linkend="GQuark">GQuark</link> quark);</programlisting>
<para>
This function gets back user data pointers stored via
<link linkend="g-object-set-qdata"><function>g_object_set_qdata()</function></link> and removes the <parameter>data</parameter> from object
without invoking it's <link linkend="destroy"><function>destroy()</function></link> 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 <link linkend="g-object-get-qdata"><function>g_object_get_qdata()</function></link> in the above example, instead of <link linkend="g-object-steal-qdata"><function>g_object_steal_qdata()</function></link>
would have left the destroy function set, and thus the partial string list would
have been freed upon <link linkend="g-object-set-qdata-full"><function>g_object_set_qdata_full()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara> The GObject to get a stored user data pointer from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>quark</parameter> :</term>
<listitem><simpara> A <link linkend="GQuark"><type>GQuark</type></link>, naming the user data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The user data pointer set, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-property"/>g_object_set_property ()</title>
<indexterm><primary>g_object_set_property</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_property (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name,
const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Sets a property on an object.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_name</parameter> :</term>
<listitem><simpara>the name of the property to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara>the value
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-get-property"/>g_object_get_property ()</title>
<indexterm><primary>g_object_get_property</primary></indexterm><programlisting><link linkend="void">void</link> g_object_get_property (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *property_name,
<link linkend="GValue">GValue</link> *value);</programlisting>
<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 <link linkend="g-free"><function>g_free()</function></link> or <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
</para>
<para>
See <link linkend="g-object-get"><function>g_object_get()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_name</parameter> :</term>
<listitem><simpara>the name of the property to get
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara>return location for the property value
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-new-valist"/>g_object_new_valist ()</title>
<indexterm><primary>g_object_new_valist</primary></indexterm><programlisting><link linkend="GObject">GObject</link>* g_object_new_valist (<link linkend="GType">GType</link> object_type,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);</programlisting>
<para>
Creates a new instance of a <link linkend="GObject"><type>GObject</type></link> subtype and sets its properties.
</para>
<para>
Construction parameters (see <link linkend="G-PARAM-CONSTRUCT-CAPS"><type>G_PARAM_CONSTRUCT</type></link>, <link linkend="G-PARAM-CONSTRUCT-ONLY-CAPS"><type>G_PARAM_CONSTRUCT_ONLY</type></link>)
which are not explicitly specified are set to their default values.
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter> :</term>
<listitem><simpara>the type id of the <link linkend="GObject"><type>GObject</type></link> subtype to instantiate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>the name of the first property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>var_args</parameter> :</term>
<listitem><simpara>the value of the first property, followed optionally by more
name/value pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new instance of <parameter>object_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-set-valist"/>g_object_set_valist ()</title>
<indexterm><primary>g_object_set_valist</primary></indexterm><programlisting><link linkend="void">void</link> g_object_set_valist (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);</programlisting>
<para>
Sets properties on an object.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>name of the first property to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>var_args</parameter> :</term>
<listitem><simpara>value for the first property, followed optionally by more
name/value pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-get-valist"/>g_object_get_valist ()</title>
<indexterm><primary>g_object_get_valist</primary></indexterm><programlisting><link linkend="void">void</link> g_object_get_valist (<link linkend="GObject">GObject</link> *object,
const <link linkend="gchar">gchar</link> *first_property_name,
<link linkend="va-list">va_list</link> var_args);</programlisting>
<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 <link linkend="g-free"><function>g_free()</function></link> or <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
</para>
<para>
See <link linkend="g-object-get"><function>g_object_get()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter> :</term>
<listitem><simpara>name of the first property to get
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>var_args</parameter> :</term>
<listitem><simpara>return location for the first property, followed optionally by more
name/return location pairs, followed by <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-watch-closure"/>g_object_watch_closure ()</title>
<indexterm><primary>g_object_watch_closure</primary></indexterm><programlisting><link linkend="void">void</link> g_object_watch_closure (<link linkend="GObject">GObject</link> *object,
<link linkend="GClosure">GClosure</link> *closure);</programlisting>
<para>
This function essentially limits the life time of the <parameter>closure</parameter>
to the life time of the object. That is, when the object is finalized,
the <parameter>closure</parameter> is invalidated by calling <link linkend="g-closure-invalidate"><function>g_closure_invalidate()</function></link> on it,
in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, <link linkend="g-object-ref"><function>g_object_ref()</function></link> and <link linkend="g-object-unref"><function>g_object_unref()</function></link> are added
as marshal guards to the <parameter>closure</parameter>, to ensure that an extra reference
count is held on <parameter>object</parameter> during invocation of the <parameter>closure</parameter>.
Usually, this function will be called on closures that use this <parameter>object</parameter>
as closure data.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara> GObject restricting lifetime of <parameter>closure</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>closure</parameter> :</term>
<listitem><simpara>GClosure to watch
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-object-run-dispose"/>g_object_run_dispose ()</title>
<indexterm><primary>g_object_run_dispose</primary></indexterm><programlisting><link linkend="void">void</link> g_object_run_dispose (<link linkend="GObject">GObject</link> *object);</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>a <link linkend="GObject"><type>GObject</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-WARN-INVALID-PROPERTY-ID-CAPS"/>G_OBJECT_WARN_INVALID_PROPERTY_ID()</title>
<indexterm><primary>G_OBJECT_WARN_INVALID_PROPERTY_ID</primary></indexterm><programlisting>#define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec)</programlisting>
<para>
This macros should be used to emit a standard warning about unexpected
properties in <link linkend="set-property"><function>set_property()</function></link> and <link linkend="get-property"><function>get_property()</function></link> implementations.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter> :</term>
<listitem><simpara>the <link linkend="GObject"><type>GObject</type></link> on which <link linkend="set-property"><function>set_property()</function></link> or <link linkend="get-property"><function>get_property()</function></link> was called
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>property_id</parameter> :</term>
<listitem><simpara>the numeric id of the property
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> of the property
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1>
<title>Signals</title>
<refsect2><title><anchor id="GObject-notify"/>The "notify" signal</title>
<programlisting><link linkend="void">void</link> user_function (<link linkend="GObject">GObject</link> *gobject,
<link linkend="GParamSpec">GParamSpec</link> *arg1,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<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><variablelist role="params">
<varlistentry><term><parameter>gobject</parameter> :</term>
<listitem><simpara>the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>the <link linkend="GParamSpec"><type>GParamSpec</type></link> of the property which changed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>