objects.sgml

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

<tbody>
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
<entry>The GObject to set store a user data pointer
</entry></row>
<row><entry align="right"><parameter>quark</parameter>&nbsp;:</entry>
<entry> A <link linkend="GQuark">GQuark</link>, naming the user data pointer
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>  An opaque user data pointer


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-set-qdata-full">g_object_set_qdata_full ()</title>
<programlisting>void        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">g_object_set_qdata</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">g_object_set_qdata</link>()
with the same <parameter>quark</parameter>.
</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> The GObject to set store a user data pointer
</entry></row>
<row><entry align="right"><parameter>quark</parameter>&nbsp;:</entry>
<entry>  A <link linkend="GQuark">GQuark</link>, naming the user data pointer
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>   An opaque user data pointer
</entry></row>
<row><entry align="right"><parameter>destroy</parameter>&nbsp;:</entry>
<entry>Function to invoke with <parameter>data</parameter> as argument, when <parameter>data</parameter> needs to be freed


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-steal-qdata">g_object_steal_qdata ()</title>
<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">g_object_set_qdata</link>() and removes the <parameter>data</parameter> from object
without invoking it's <link linkend="destroy">destroy</link>() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
<msgtext><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></msgtext>
Using <link linkend="g-object-get-qdata">g_object_get_qdata</link>() in the above example, instead of <link linkend="g-object-steal-qdata">g_object_steal_qdata</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">g_object_set_qdata_full</link>().
</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> The GObject to get a stored user data pointer from
</entry></row>
<row><entry align="right"><parameter>quark</parameter>&nbsp;:</entry>
<entry>  A <link linkend="GQuark">GQuark</link>, naming the user data pointer
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The user data pointer set, or <literal>NULL</literal>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-set-property">g_object_set_property ()</title>
<programlisting>void        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>

</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_name</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-get-property">g_object_get_property ()</title>
<programlisting>void        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>

</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_name</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-new-valist">g_object_new_valist ()</title>
<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,
                                             va_list var_args);</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_type</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>first_property_name</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>var_args</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-set-valist">g_object_set_valist ()</title>
<programlisting>void        g_object_set_valist             (<link linkend="GObject">GObject</link> *object,
                                             const <link linkend="gchar">gchar</link> *first_property_name,
                                             va_list var_args);</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>first_property_name</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>var_args</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-get-valist">g_object_get_valist ()</title>
<programlisting>void        g_object_get_valist             (<link linkend="GObject">GObject</link> *object,
                                             const <link linkend="gchar">gchar</link> *first_property_name,
                                             va_list var_args);</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>first_property_name</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>var_args</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-watch-closure">g_object_watch_closure ()</title>
<programlisting>void        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">g_closure_invalidate</link>() on it,
in order to prevent invocations of the closure with a finalized (non
existing) object. Also, <link linkend="g-object-ref">g_object_ref</link>() and <link linkend="g-object-unref">g_object_unref</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><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> GObject restricting lifetime of <parameter>closure</parameter>
</entry></row>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>GClosure to watch


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-object-run-dispose">g_object_run_dispose ()</title>
<programlisting>void        g_object_run_dispose            (<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-OBJECT-WARN-INVALID-PSPEC-CAPS">G_OBJECT_WARN_INVALID_PSPEC()</title>
<programlisting>#define     G_OBJECT_WARN_INVALID_PSPEC(object, pname, property_id, 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>pname</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>property_id</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="G-OBJECT-WARN-INVALID-PROPERTY-ID-CAPS">G_OBJECT_WARN_INVALID_PROPERTY_ID()</title>
<programlisting>#define     G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, 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>pspec</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>