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