docs/reference/glib/html/glib-Keyed-Data-Lists.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Keyed Data Lists</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-data-types.html" title="GLib Data Types">
   9 <link rel="prev" href="glib-Quarks.html" title="Quarks">
  10 <link rel="next" href="glib-Datasets.html" title="Datasets">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Quarks.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Datasets.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Keyed-Data-Lists.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Keyed-Data-Lists.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Keyed-Data-Lists"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Keyed-Data-Lists.top_of_page"></a>Keyed Data Lists</span></h2>
  34 <p>Keyed Data Lists — lists of data elements which are accessible by a
  35                     string or GQuark identifier</p>
  36 </td>
  37 <td valign="top" align="right"></td>
  38 </tr></table></div>
  39 <div class="refsynopsisdiv">
  40 <a name="glib-Keyed-Data-Lists.synopsis"></a><h2>Synopsis</h2>
  41 <pre class="synopsis">
  42 #include &lt;glib.h&gt;
  43
  44                     <a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData">GData</a>;
  45 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-init" title="g_datalist_init ()">g_datalist_init</a>                     (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);
  46
  47 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-set-data" title="g_datalist_id_set_data()">g_datalist_id_set_data</a>              (dl,
  48                                                          q,
  49                                                          d)
  50 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-set-data-full" title="g_datalist_id_set_data_full ()">g_datalist_id_set_data_full</a>         (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>,
  52                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>);
  54 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-get-data" title="g_datalist_id_get_data ()">g_datalist_id_get_data</a>              (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  55                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>);
  56 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-remove-data" title="g_datalist_id_remove_data()">g_datalist_id_remove_data</a>           (dl,
  57                                                          q)
  58 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-remove-no-notify" title="g_datalist_id_remove_no_notify ()">g_datalist_id_remove_no_notify</a>      (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>);
  60
  61 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-data" title="g_datalist_set_data()">g_datalist_set_data</a>                 (dl,
  62                                                          k,
  63                                                          d)
  64 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-data-full" title="g_datalist_set_data_full()">g_datalist_set_data_full</a>            (dl,
  65                                                          k,
  66                                                          d,
  67                                                          f)
  68 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-get-data" title="g_datalist_get_data ()">g_datalist_get_data</a>                 (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  69                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *key</code></em>);
  70 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-remove-data" title="g_datalist_remove_data()">g_datalist_remove_data</a>              (dl,
  71                                                          k)
  72 #define             <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-remove-no-notify" title="g_datalist_remove_no_notify()">g_datalist_remove_no_notify</a>         (dl,
  73                                                          k)
  74
  75 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-foreach" title="g_datalist_foreach ()">g_datalist_foreach</a>                  (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  76                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDataForeachFunc" title="GDataForeachFunc ()"><span class="type">GDataForeachFunc</span></a> func</code></em>,
  77                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  78 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-clear" title="g_datalist_clear ()">g_datalist_clear</a>                    (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);
  79 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-flags" title="g_datalist_set_flags ()">g_datalist_set_flags</a>                (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  80                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> flags</code></em>);
  81 <span class="returnvalue">void</span>                <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-unset-flags" title="g_datalist_unset_flags ()">g_datalist_unset_flags</a>              (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
  82                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> flags</code></em>);
  83 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-get-flags" title="g_datalist_get_flags ()">g_datalist_get_flags</a>                (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);
  84 #define             <a class="link" href="glib-Keyed-Data-Lists.html#G-DATALIST-FLAGS-MASK:CAPS" title="G_DATALIST_FLAGS_MASK">G_DATALIST_FLAGS_MASK</a>
  85 </pre>
  86 </div>
  87 <div class="refsect1">
  88 <a name="glib-Keyed-Data-Lists.description"></a><h2>Description</h2>
  89 <p>
  90 Keyed data lists provide lists of arbitrary data elements which can
  91 be accessed either with a string or with a <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> corresponding to
  92 the string.
  93 </p>
  94 <p>
  95 The <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> methods are quicker, since the strings have to be
  96 converted to <a href="glib-Quarks.html#GQuark"><span class="type">GQuarks</span></a> anyway.
  97 </p>
  98 <p>
  99 Data lists are used for associating arbitrary data with <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObjects</span></a>,
 100 using <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-set-data"><code class="function">g_object_set_data()</code></a> and related functions.
 101 </p>
 102 <p>
 103 To create a datalist, use <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-init" title="g_datalist_init ()"><code class="function">g_datalist_init()</code></a>.
 104 </p>
 105 <p>
 106 To add data elements to a datalist use <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-set-data" title="g_datalist_id_set_data()"><code class="function">g_datalist_id_set_data()</code></a>,
 107 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-set-data-full" title="g_datalist_id_set_data_full ()"><code class="function">g_datalist_id_set_data_full()</code></a>, <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-data" title="g_datalist_set_data()"><code class="function">g_datalist_set_data()</code></a> and
 108 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-data-full" title="g_datalist_set_data_full()"><code class="function">g_datalist_set_data_full()</code></a>.
 109 </p>
 110 <p>
 111 To get data elements from a datalist use <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-get-data" title="g_datalist_id_get_data ()"><code class="function">g_datalist_id_get_data()</code></a>
 112 and <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-get-data" title="g_datalist_get_data ()"><code class="function">g_datalist_get_data()</code></a>.
 113 </p>
 114 <p>
 115 To iterate over all data elements in a datalist use
 116 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-foreach" title="g_datalist_foreach ()"><code class="function">g_datalist_foreach()</code></a> (not thread-safe).
 117 </p>
 118 <p>
 119 To remove data elements from a datalist use
 120 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-remove-data" title="g_datalist_id_remove_data()"><code class="function">g_datalist_id_remove_data()</code></a> and <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-remove-data" title="g_datalist_remove_data()"><code class="function">g_datalist_remove_data()</code></a>.
 121 </p>
 122 <p>
 123 To remove all data elements from a datalist, use <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-clear" title="g_datalist_clear ()"><code class="function">g_datalist_clear()</code></a>.
 124 </p>
 125 </div>
 126 <div class="refsect1">
 127 <a name="glib-Keyed-Data-Lists.details"></a><h2>Details</h2>
 128 <div class="refsect2">
 129 <a name="GData"></a><h3>GData</h3>
 130 <pre class="programlisting">typedef struct _GData GData;</pre>
 131 <p>
 132 The <a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> struct is an opaque data structure to represent a <a class="link" href="glib-Keyed-Data-Lists.html" title="Keyed Data Lists">Keyed Data List</a>. It should
 133 only be accessed via the following functions.
 134 </p>
 135 </div>
 136 <hr>
 137 <div class="refsect2">
 138 <a name="g-datalist-init"></a><h3>g_datalist_init ()</h3>
 139 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_init                     (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);</pre>
 140 <p>
 141 Resets the datalist to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. It does not free any memory or call
 142 any destroy functions.
 143 </p>
 144 <div class="variablelist"><table border="0">
 145 <col align="left" valign="top">
 146 <tbody><tr>
 147 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 148 <td>a pointer to a pointer to a datalist.</td>
 149 </tr></tbody>
 150 </table></div>
 151 </div>
 152 <hr>
 153 <div class="refsect2">
 154 <a name="g-datalist-id-set-data"></a><h3>g_datalist_id_set_data()</h3>
 155 <pre class="programlisting">#define             g_datalist_id_set_data(dl, q, d)</pre>
 156 <p>
 157 Sets the data corresponding to the given <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> id. Any previous
 158 data with the same key is removed, and its destroy function is
 159 called.
 160 </p>
 161 <div class="variablelist"><table border="0">
 162 <col align="left" valign="top">
 163 <tbody>
 164 <tr>
 165 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 166 <td>a datalist.</td>
 167 </tr>
 168 <tr>
 169 <td><p><span class="term"><em class="parameter"><code>q</code></em> :</span></p></td>
 170 <td>the <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> to identify the data element.</td>
 171 </tr>
 172 <tr>
 173 <td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td>
 174 <td>the data element, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to remove any previous element
 175 corresponding to <em class="parameter"><code>q</code></em>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 176 </td>
 177 </tr>
 178 </tbody>
 179 </table></div>
 180 </div>
 181 <hr>
 182 <div class="refsect2">
 183 <a name="g-datalist-id-set-data-full"></a><h3>g_datalist_id_set_data_full ()</h3>
 184 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_id_set_data_full         (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 185                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>,
 186                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
 187                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>);</pre>
 188 <p>
 189 Sets the data corresponding to the given <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> id, and the
 190 function to be called when the element is removed from the datalist.
 191 Any previous data with the same key is removed, and its destroy
 192 function is called.
 193 </p>
 194 <div class="variablelist"><table border="0">
 195 <col align="left" valign="top">
 196 <tbody>
 197 <tr>
 198 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 199 <td>a datalist.</td>
 200 </tr>
 201 <tr>
 202 <td><p><span class="term"><em class="parameter"><code>key_id</code></em> :</span></p></td>
 203 <td>the <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> to identify the data element.</td>
 204 </tr>
 205 <tr>
 206 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 207 <td>the data element or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to remove any previous element
 208 corresponding to <em class="parameter"><code>key_id</code></em>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 209 </td>
 210 </tr>
 211 <tr>
 212 <td><p><span class="term"><em class="parameter"><code>destroy_func</code></em> :</span></p></td>
 213 <td>the function to call when the data element is
 214 removed. This function will be called with the data
 215 element and can be used to free any memory allocated
 216 for it. If <em class="parameter"><code>data</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then <em class="parameter"><code>destroy_func</code></em> must
 217 also be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.</td>
 218 </tr>
 219 </tbody>
 220 </table></div>
 221 </div>
 222 <hr>
 223 <div class="refsect2">
 224 <a name="g-datalist-id-get-data"></a><h3>g_datalist_id_get_data ()</h3>
 225 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_datalist_id_get_data              (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 226                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>);</pre>
 227 <p>
 228 Retrieves the data element corresponding to <em class="parameter"><code>key_id</code></em>.
 229 </p>
 230 <div class="variablelist"><table border="0">
 231 <col align="left" valign="top">
 232 <tbody>
 233 <tr>
 234 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 235 <td>a datalist.</td>
 236 </tr>
 237 <tr>
 238 <td><p><span class="term"><em class="parameter"><code>key_id</code></em> :</span></p></td>
 239 <td>the <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> identifying a data element.</td>
 240 </tr>
 241 <tr>
 242 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 243 <td>the data element, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if it is not found.</td>
 244 </tr>
 245 </tbody>
 246 </table></div>
 247 </div>
 248 <hr>
 249 <div class="refsect2">
 250 <a name="g-datalist-id-remove-data"></a><h3>g_datalist_id_remove_data()</h3>
 251 <pre class="programlisting">#define             g_datalist_id_remove_data(dl, q)</pre>
 252 <p>
 253 Removes an element, using its <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> identifier.
 254 </p>
 255 <div class="variablelist"><table border="0">
 256 <col align="left" valign="top">
 257 <tbody>
 258 <tr>
 259 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 260 <td>a datalist.</td>
 261 </tr>
 262 <tr>
 263 <td><p><span class="term"><em class="parameter"><code>q</code></em> :</span></p></td>
 264 <td>the <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> identifying the data element.</td>
 265 </tr>
 266 </tbody>
 267 </table></div>
 268 </div>
 269 <hr>
 270 <div class="refsect2">
 271 <a name="g-datalist-id-remove-no-notify"></a><h3>g_datalist_id_remove_no_notify ()</h3>
 272 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_datalist_id_remove_no_notify      (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 273                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> key_id</code></em>);</pre>
 274 <p>
 275 Removes an element, without calling its destroy notification
 276 function.
 277 </p>
 278 <div class="variablelist"><table border="0">
 279 <col align="left" valign="top">
 280 <tbody>
 281 <tr>
 282 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 283 <td>a datalist.</td>
 284 </tr>
 285 <tr>
 286 <td><p><span class="term"><em class="parameter"><code>key_id</code></em> :</span></p></td>
 287 <td>the <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> identifying a data element.</td>
 288 </tr>
 289 <tr>
 290 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 291 <td>the data previously stored at <em class="parameter"><code>key_id</code></em>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if none.</td>
 292 </tr>
 293 </tbody>
 294 </table></div>
 295 </div>
 296 <hr>
 297 <div class="refsect2">
 298 <a name="g-datalist-set-data"></a><h3>g_datalist_set_data()</h3>
 299 <pre class="programlisting">#define             g_datalist_set_data(dl, k, d)</pre>
 300 <p>
 301 Sets the data element corresponding to the given string identifier.
 302 </p>
 303 <div class="variablelist"><table border="0">
 304 <col align="left" valign="top">
 305 <tbody>
 306 <tr>
 307 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 308 <td>a datalist.</td>
 309 </tr>
 310 <tr>
 311 <td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td>
 312 <td>the string to identify the data element.</td>
 313 </tr>
 314 <tr>
 315 <td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td>
 316 <td>the data element, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to remove any previous element
 317 corresponding to <em class="parameter"><code>k</code></em>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 318 </td>
 319 </tr>
 320 </tbody>
 321 </table></div>
 322 </div>
 323 <hr>
 324 <div class="refsect2">
 325 <a name="g-datalist-set-data-full"></a><h3>g_datalist_set_data_full()</h3>
 326 <pre class="programlisting">#define             g_datalist_set_data_full(dl, k, d, f)</pre>
 327 <p>
 328 Sets the data element corresponding to the given string identifier,
 329 and the function to be called when the data element is removed.
 330 </p>
 331 <div class="variablelist"><table border="0">
 332 <col align="left" valign="top">
 333 <tbody>
 334 <tr>
 335 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 336 <td>a datalist.</td>
 337 </tr>
 338 <tr>
 339 <td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td>
 340 <td>the string to identify the data element.</td>
 341 </tr>
 342 <tr>
 343 <td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td>
 344 <td>the data element, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to remove any previous element
 345 corresponding to <em class="parameter"><code>k</code></em>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 346 </td>
 347 </tr>
 348 <tr>
 349 <td><p><span class="term"><em class="parameter"><code>f</code></em> :</span></p></td>
 350 <td>the function to call when the data element is removed. This
 351 function will be called with the data element and can be used to
 352 free any memory allocated for it. If <em class="parameter"><code>d</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then <em class="parameter"><code>f</code></em> must
 353 also be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.</td>
 354 </tr>
 355 </tbody>
 356 </table></div>
 357 </div>
 358 <hr>
 359 <div class="refsect2">
 360 <a name="g-datalist-get-data"></a><h3>g_datalist_get_data ()</h3>
 361 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_datalist_get_data                 (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 362                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *key</code></em>);</pre>
 363 <p>
 364 Gets a data element, using its string identifier. This is slower than
 365 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-id-get-data" title="g_datalist_id_get_data ()"><code class="function">g_datalist_id_get_data()</code></a> because it compares strings.
 366 </p>
 367 <div class="variablelist"><table border="0">
 368 <col align="left" valign="top">
 369 <tbody>
 370 <tr>
 371 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 372 <td>a datalist.</td>
 373 </tr>
 374 <tr>
 375 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 376 <td>the string identifying a data element.</td>
 377 </tr>
 378 <tr>
 379 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 380 <td>the data element, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if it is not found.</td>
 381 </tr>
 382 </tbody>
 383 </table></div>
 384 </div>
 385 <hr>
 386 <div class="refsect2">
 387 <a name="g-datalist-remove-data"></a><h3>g_datalist_remove_data()</h3>
 388 <pre class="programlisting">#define             g_datalist_remove_data(dl, k)</pre>
 389 <p>
 390 Removes an element using its string identifier. The data element's
 391 destroy function is called if it has been set.
 392 </p>
 393 <div class="variablelist"><table border="0">
 394 <col align="left" valign="top">
 395 <tbody>
 396 <tr>
 397 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 398 <td>a datalist.</td>
 399 </tr>
 400 <tr>
 401 <td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td>
 402 <td>the string identifying the data element.</td>
 403 </tr>
 404 </tbody>
 405 </table></div>
 406 </div>
 407 <hr>
 408 <div class="refsect2">
 409 <a name="g-datalist-remove-no-notify"></a><h3>g_datalist_remove_no_notify()</h3>
 410 <pre class="programlisting">#define             g_datalist_remove_no_notify(dl, k)</pre>
 411 <p>
 412 Removes an element, without calling its destroy notifier.
 413 </p>
 414 <div class="variablelist"><table border="0">
 415 <col align="left" valign="top">
 416 <tbody>
 417 <tr>
 418 <td><p><span class="term"><em class="parameter"><code>dl</code></em> :</span></p></td>
 419 <td>a datalist.</td>
 420 </tr>
 421 <tr>
 422 <td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td>
 423 <td>the string identifying the data element.</td>
 424 </tr>
 425 </tbody>
 426 </table></div>
 427 </div>
 428 <hr>
 429 <div class="refsect2">
 430 <a name="g-datalist-foreach"></a><h3>g_datalist_foreach ()</h3>
 431 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_foreach                  (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 432                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDataForeachFunc" title="GDataForeachFunc ()"><span class="type">GDataForeachFunc</span></a> func</code></em>,
 433                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 434 <p>
 435 Calls the given function for each data element of the datalist. The
 436 function is called with each data element's <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> id and data,
 437 together with the given <em class="parameter"><code>user_data</code></em> parameter. Note that this
 438 function is NOT thread-safe. So unless <em class="parameter"><code>datalist</code></em> can be protected
 439 from any modifications during invocation of this function, it should
 440 not be called.
 441 </p>
 442 <div class="variablelist"><table border="0">
 443 <col align="left" valign="top">
 444 <tbody>
 445 <tr>
 446 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 447 <td>a datalist.</td>
 448 </tr>
 449 <tr>
 450 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 451 <td>the function to call for each data element.</td>
 452 </tr>
 453 <tr>
 454 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 455 <td>user data to pass to the function.</td>
 456 </tr>
 457 </tbody>
 458 </table></div>
 459 </div>
 460 <hr>
 461 <div class="refsect2">
 462 <a name="g-datalist-clear"></a><h3>g_datalist_clear ()</h3>
 463 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_clear                    (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);</pre>
 464 <p>
 465 Frees all the data elements of the datalist.
 466 The data elements' destroy functions are called
 467 if they have been set.
 468 </p>
 469 <div class="variablelist"><table border="0">
 470 <col align="left" valign="top">
 471 <tbody><tr>
 472 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 473 <td>a datalist.</td>
 474 </tr></tbody>
 475 </table></div>
 476 </div>
 477 <hr>
 478 <div class="refsect2">
 479 <a name="g-datalist-set-flags"></a><h3>g_datalist_set_flags ()</h3>
 480 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_set_flags                (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 481                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> flags</code></em>);</pre>
 482 <p>
 483 Turns on flag values for a data list. This function is used
 484 to keep a small number of boolean flags in an object with
 485 a data list without using any additional space. It is
 486 not generally useful except in circumstances where space
 487 is very tight. (It is used in the base <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> type, for
 488 example.)
 489 </p>
 490 <div class="variablelist"><table border="0">
 491 <col align="left" valign="top">
 492 <tbody>
 493 <tr>
 494 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 495 <td>pointer to the location that holds a list</td>
 496 </tr>
 497 <tr>
 498 <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td>
 499 <td>the flags to turn on. The values of the flags are
 500 restricted by <a class="link" href="glib-Keyed-Data-Lists.html#G-DATALIST-FLAGS-MASK:CAPS" title="G_DATALIST_FLAGS_MASK"><code class="literal">G_DATALIST_FLAGS_MASK</code></a> (currently
 501 3; giving two possible boolean flags).
 502 A value for <em class="parameter"><code>flags</code></em> that doesn't fit within the mask is
 503 an error.</td>
 504 </tr>
 505 </tbody>
 506 </table></div>
 507 <p class="since">Since 2.8</p>
 508 </div>
 509 <hr>
 510 <div class="refsect2">
 511 <a name="g-datalist-unset-flags"></a><h3>g_datalist_unset_flags ()</h3>
 512 <pre class="programlisting"><span class="returnvalue">void</span>                g_datalist_unset_flags              (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>,
 513                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> flags</code></em>);</pre>
 514 <p>
 515 Turns off flag values for a data list. See <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-unset-flags" title="g_datalist_unset_flags ()"><code class="function">g_datalist_unset_flags()</code></a>
 516 </p>
 517 <div class="variablelist"><table border="0">
 518 <col align="left" valign="top">
 519 <tbody>
 520 <tr>
 521 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 522 <td>pointer to the location that holds a list</td>
 523 </tr>
 524 <tr>
 525 <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td>
 526 <td>the flags to turn off. The values of the flags are
 527 restricted by <a class="link" href="glib-Keyed-Data-Lists.html#G-DATALIST-FLAGS-MASK:CAPS" title="G_DATALIST_FLAGS_MASK"><code class="literal">G_DATALIST_FLAGS_MASK</code></a> (currently
 528 3: giving two possible boolean flags).
 529 A value for <em class="parameter"><code>flags</code></em> that doesn't fit within the mask is
 530 an error.</td>
 531 </tr>
 532 </tbody>
 533 </table></div>
 534 <p class="since">Since 2.8</p>
 535 </div>
 536 <hr>
 537 <div class="refsect2">
 538 <a name="g-datalist-get-flags"></a><h3>g_datalist_get_flags ()</h3>
 539 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_datalist_get_flags                (<em class="parameter"><code><a class="link" href="glib-Keyed-Data-Lists.html#GData" title="GData"><span class="type">GData</span></a> **datalist</code></em>);</pre>
 540 <p>
 541 Gets flags values packed in together with the datalist.
 542 See <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-flags" title="g_datalist_set_flags ()"><code class="function">g_datalist_set_flags()</code></a>.
 543 </p>
 544 <div class="variablelist"><table border="0">
 545 <col align="left" valign="top">
 546 <tbody>
 547 <tr>
 548 <td><p><span class="term"><em class="parameter"><code>datalist</code></em> :</span></p></td>
 549 <td>pointer to the location that holds a list</td>
 550 </tr>
 551 <tr>
 552 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 553 <td>the flags of the datalist</td>
 554 </tr>
 555 </tbody>
 556 </table></div>
 557 <p class="since">Since 2.8</p>
 558 </div>
 559 <hr>
 560 <div class="refsect2">
 561 <a name="G-DATALIST-FLAGS-MASK:CAPS"></a><h3>G_DATALIST_FLAGS_MASK</h3>
 562 <pre class="programlisting">#define G_DATALIST_FLAGS_MASK 0x3
 563 </pre>
 564 <p>
 565 A bitmask that restricts the possible flags passed to
 566 <a class="link" href="glib-Keyed-Data-Lists.html#g-datalist-set-flags" title="g_datalist_set_flags ()"><code class="function">g_datalist_set_flags()</code></a>. Passing a flags value where
 567 flags &amp; ~G_DATALIST_FLAGS_MASK != 0 is an error.
 568 </p>
 569 </div>
 570 </div>
 571 </div>
 572 <div class="footer">
 573 <hr>
 574           Generated by GTK-Doc V1.18</div>
 575 </body>
 576 </html>