datalist.sgml

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

<refentry id="glib-Keyed-Data-Lists">
<refmeta>
<refentrytitle>Keyed Data Lists</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Keyed Data Lists</refname><refpurpose>lists of data elements which are accessible by a string or <link linkend="GQuark">GQuark</link> identifier.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GData">GData</link>;
void        <link linkend="g-datalist-init">g_datalist_init</link>                 (<link linkend="GData">GData</link> **datalist);

#define     <link linkend="g-datalist-id-set-data">g_datalist_id_set_data</link>          (dl, q, d)
void        <link linkend="g-datalist-id-set-data-full">g_datalist_id_set_data_full</link>     (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GQuark">GQuark</link> key_id,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func);
<link linkend="gpointer">gpointer</link>    <link linkend="g-datalist-id-get-data">g_datalist_id_get_data</link>          (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GQuark">GQuark</link> key_id);
#define     <link linkend="g-datalist-id-remove-data">g_datalist_id_remove_data</link>       (dl, q)
<link linkend="gpointer">gpointer</link>    <link linkend="g-datalist-id-remove-no-notify">g_datalist_id_remove_no_notify</link>  (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GQuark">GQuark</link> key_id);

#define     <link linkend="g-datalist-set-data">g_datalist_set_data</link>             (dl, k, d)
#define     <link linkend="g-datalist-set-data-full">g_datalist_set_data_full</link>        (dl, k, d, f)
#define     <link linkend="g-datalist-get-data">g_datalist_get_data</link>             (dl, k)
#define     <link linkend="g-datalist-remove-data">g_datalist_remove_data</link>          (dl, k)
#define     <link linkend="g-datalist-remove-no-notify">g_datalist_remove_no_notify</link>     (dl, k)

void        <link linkend="g-datalist-foreach">g_datalist_foreach</link>              (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GDataForeachFunc">GDataForeachFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-datalist-clear">g_datalist_clear</link>                (<link linkend="GData">GData</link> **datalist);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Keyed data lists provide lists of arbitrary data elements which can be accessed
either with a string or with a <link linkend="GQuark">GQuark</link> corresponding to the string.
</para>
<para>
The <link linkend="GQuark">GQuark</link> methods are quicker, since the strings have to be converted to
<link linkend="GQuarks">GQuarks</link> anyway.
</para>
<para>
Data lists are used in GTK+ for associating arbitrary data with
<link linkend="GtkObjects">GtkObjects</link>, using <link linkend="gtk-object-set-data">gtk_object_set_data</link>() and related functions.
</para>

<para>
To create a datalist, use <link linkend="g-datalist-init">g_datalist_init</link>().
</para>
<para>
To add data elements to a datalist use <link linkend="g-datalist-id-set-data">g_datalist_id_set_data</link>(),
<link linkend="g-datalist-id-set-data-full">g_datalist_id_set_data_full</link>(), <link linkend="g-datalist-set-data">g_datalist_set_data</link>()
and <link linkend="g-datalist-set-data-full">g_datalist_set_data_full</link>().
</para>
<para>
To get data elements from a datalist use <link linkend="g-datalist-id-get-data">g_datalist_id_get_data</link>() and
<link linkend="g-datalist-get-data">g_datalist_get_data</link>().
</para>
<para>
To iterate over all data elements in a datalist use <link linkend="g-datalist-foreach">g_datalist_foreach</link>().
</para>
<para>
To remove data elements from a datalist use <link linkend="g-datalist-id-remove-data">g_datalist_id_remove_data</link>() and
<link linkend="g-datalist-remove-data">g_datalist_remove_data</link>().
</para>
<para>
To remove all data elements from a datalist, use <link linkend="g-datalist-clear">g_datalist_clear</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GData">struct GData</title>
<programlisting>struct GData;</programlisting>
<para>
The <link linkend="GData">GData</link> struct is an opaque data structure to represent a
<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
It should only be accessed via the following functions.
</para></refsect2>
<refsect2>
<title><anchor id="g-datalist-init">g_datalist_init ()</title>
<programlisting>void        g_datalist_init                 (<link linkend="GData">GData</link> **datalist);</programlisting>
<para>
Resets the datalist to <literal>NULL</literal>.
It does not free any memory or call any destroy functions.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>datalist</parameter>&nbsp;:</entry>
<entry>a pointer to a pointer to a datalist.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-datalist-id-set-data">g_datalist_id_set_data()</title>
<programlisting>#define     g_datalist_id_set_data(dl, q, d)</programlisting>
<para>
Sets the data corresponding to the given <link linkend="GQuark">GQuark</link> id.
Any previous data with the same key is removed, and its
destroy function is called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dl</parameter>&nbsp;:</entry>
<entry>a datalist.
</entry></row>
<row><entry align="right"><parameter>q</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> to identify the data element.
</entry></row>
<row><entry align="right"><parameter>d</parameter>&nbsp;:</entry>
<entry>the data element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-datalist-id-set-data-full">g_datalist_id_set_data_full ()</title>
<programlisting>void        g_datalist_id_set_data_full     (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GQuark">GQuark</link> key_id,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func);</programlisting>
<para>
Sets the data corresponding to the given <link linkend="GQuark">GQuark</link> id, and the function to
be called when the element is removed from the datalist.
Any previous data with the same key is removed, and its
destroy function is called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>datalist</parameter>&nbsp;:</entry>
<entry>a datalist.
</entry></row>
<row><entry align="right"><parameter>key_id</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> to identify the data element.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data element.
</entry></row>
<row><entry align="right"><parameter>destroy_func</parameter>&nbsp;:</entry>
<entry>the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-datalist-id-get-data">g_datalist_id_get_data ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_datalist_id_get_data          (<link linkend="GData">GData</link> **datalist,
                                             <link linkend="GQuark">GQuark</link> key_id);</programlisting>
<para>
Gets a data element.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>datalist</parameter>&nbsp;:</entry>
<entry>a datalist.
</entry></row>
<row><entry align="right"><parameter>key_id</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> identifying a data element.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the data element, or <literal>NULL</literal> if it is not found.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-datalist-id-remove-data">g_datalist_id_remove_data()</title>
<programlisting>#define     g_datalist_id_remove_data(dl, q)</programlisting>
<para>
Removes an element, using its <link linkend="GQuark">GQuark</link> identifier.
</para><informaltable pgwide="1" frame="none" role="params">