objects.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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>
<synopsis>

#include &lt;gobject.h&gt;


struct      <link linkend="GObject">GObject</link>;
struct      <link linkend="GObjectClass">GObjectClass</link>;
void        (<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);
void        (<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);
void        (<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)
void        <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="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);
void        <link linkend="g-object-unref">g_object_unref</link>                  (<link linkend="gpointer">gpointer</link> object);
void        (<link linkend="GWeakNotify">*GWeakNotify</link>)                  (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GObject">GObject</link> *where_the_object_was);
void        <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);
void        <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);
void        <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);
void        <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,
                                             ...);
void        <link linkend="g-object-disconnect">g_object_disconnect</link>             (<link linkend="gpointer">gpointer</link> object,
                                             const <link linkend="gchar">gchar</link> *signal_spec,
                                             ...);
void        <link linkend="g-object-set">g_object_set</link>                    (<link linkend="gpointer">gpointer</link> object,
                                             const <link linkend="gchar">gchar</link> *first_property_name,
                                             ...);
void        <link linkend="g-object-get">g_object_get</link>                    (<link linkend="gpointer">gpointer</link> object,
                                             const <link linkend="gchar">gchar</link> *first_property_name,
                                             ...);
void        <link linkend="g-object-notify">g_object_notify</link>                 (<link linkend="GObject">GObject</link> *object,
                                             const <link linkend="gchar">gchar</link> *property_name);
void        <link linkend="g-object-freeze-notify">g_object_freeze_notify</link>          (<link linkend="GObject">GObject</link> *object);
void        <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);
void        <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);
void        <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);
void        <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);
void        <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);
void        <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);
void        <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,
                                             va_list var_args);
void        <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,
                                             va_list var_args);
void        <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,
                                             va_list var_args);
void        <link linkend="g-object-watch-closure">g_object_watch_closure</link>          (<link linkend="GObject">GObject</link> *object,
                                             <link linkend="GClosure">GClosure</link> *closure);
void        <link linkend="g-object-run-dispose">g_object_run_dispose</link>            (<link linkend="GObject">GObject</link> *object);
#define     <link linkend="G-OBJECT-WARN-INVALID-PSPEC-CAPS">G_OBJECT_WARN_INVALID_PSPEC</link>     (object, pname, property_id, pspec)
#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>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GObject">struct GObject</title>
<programlisting>struct GObject
{
  GTypeInstance g_type_instance;
  
  /*&lt; private &gt;*/
  guint         ref_count;
  GData        *qdata;
};
</programlisting>
<para>
All the fields in the GObject structure are private to the <link linkend="GObject">GObject</link> implementation
and should never be accessed directly.
</para></refsect2>
<refsect2>
<title><anchor id="GObjectClass">struct GObjectClass</title>
<programlisting>struct GObjectClass;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GObjectGetPropertyFunc">GObjectGetPropertyFunc ()</title>
<programlisting>void        (*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>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>property_id</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GObjectSetPropertyFunc">GObjectSetPropertyFunc ()</title>
<programlisting>void        (*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>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>property_id</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GObjectFinalizeFunc">GObjectFinalizeFunc ()</title>
<programlisting>void        (*GObjectFinalizeFunc)          (<link linkend="GObject">GObject</link> *object);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-TYPE-IS-OBJECT-CAPS">G_TYPE_IS_OBJECT()</title>
<programlisting>#define G_TYPE_IS_OBJECT(type)      (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT)
</programlisting>
<para>
Return 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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>Type id to check for is a <literal>G_TYPE_OBJECT</literal> relationship.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>FALSE</literal> or <literal>TRUE</literal>, indicating whether <parameter>type</parameter> is a <literal>G_TYPE_OBJECT</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CAPS">G_OBJECT()</title>
<programlisting>#define G_OBJECT(object)            (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject))
</programlisting>
<para>
Cast a <link linkend="GObject">GObject</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>Object which is subject to casting.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-IS-OBJECT-CAPS">G_IS_OBJECT()</title>
<programlisting>#define G_IS_OBJECT(object)         (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))
</programlisting>
<para>
Check whether a valid <link linkend="GTypeInstance">GTypeInstance</link> pointer is of type <literal>G_TYPE_OBJECT</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>Instance to check for being a <literal>G_TYPE_OBJECT</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-CLASS-CAPS">G_OBJECT_CLASS()</title>
<programlisting>#define G_OBJECT_CLASS(class)       (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass))
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>class</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-IS-OBJECT-CLASS-CAPS">G_IS_OBJECT_CLASS()</title>
<programlisting>#define G_IS_OBJECT_CLASS(class)    (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>class</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-OBJECT-GET-CLASS-CAPS">G_OBJECT_GET_CLASS()</title>