docs/reference/glib/tmpl/datalist.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Keyed Data Lists
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 lists of data elements which are accessible by a string or #GQuark identifier.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Keyed data lists provide lists of arbitrary data elements which can be accessed
  10 either with a string or with a #GQuark corresponding to the
  11 string.
  12 </para>
  13 <para>
  14 The #GQuark methods are quicker, since the strings have to be converted to
  15 #GQuarks anyway.
  16 </para>
  17 <para>
  18 Data lists are used for associating arbitrary data with
  19 #GObjects, using g_object_set_data() and related functions.
  20 </para>
  21
  22 <para>
  23 To create a datalist, use g_datalist_init().
  24 </para>
  25 <para>
  26 To add data elements to a datalist use g_datalist_id_set_data(),
  27 g_datalist_id_set_data_full(), g_datalist_set_data()
  28 and g_datalist_set_data_full().
  29 </para>
  30 <para>
  31 To get data elements from a datalist use g_datalist_id_get_data() and
  32 g_datalist_get_data().
  33 </para>
  34 <para>
  35 To iterate over all data elements in a datalist use g_datalist_foreach().
  36 </para>
  37 <para>
  38 To remove data elements from a datalist use g_datalist_id_remove_data() and
  39 g_datalist_remove_data().
  40 </para>
  41 <para>
  42 To remove all data elements from a datalist, use g_datalist_clear().
  43 </para>
  44
  45 <!-- ##### SECTION See_Also ##### -->
  46 <para>
  47
  48 </para>
  49
  50 <!-- ##### SECTION Stability_Level ##### -->
  51
  52
  53 <!-- ##### STRUCT GData ##### -->
  54 <para>
  55 The #GData struct is an opaque data structure to represent a
  56 <link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
  57 It should only be accessed via the following functions.
  58 </para>
  59
  60
  61 <!-- ##### FUNCTION g_datalist_init ##### -->
  62 <para>
  63 Resets the datalist to %NULL.
  64 It does not free any memory or call any destroy functions.
  65 </para>
  66
  67 @datalist: a pointer to a pointer to a datalist.
  68
  69
  70 <!-- ##### MACRO g_datalist_id_set_data ##### -->
  71 <para>
  72 Sets the data corresponding to the given #GQuark id.
  73 Any previous data with the same key is removed, and its
  74 destroy function is called.
  75 </para>
  76
  77 @dl: a datalist.
  78 @q: the #GQuark to identify the data element.
  79 @d: the data element, or %NULL to remove any previous element
  80 corresponding to @q.
  81
  82
  83 <!-- ##### FUNCTION g_datalist_id_set_data_full ##### -->
  84 <para>
  85 Sets the data corresponding to the given #GQuark id, and the function to
  86 be called when the element is removed from the datalist.
  87 Any previous data with the same key is removed, and its
  88 destroy function is called.
  89 </para>
  90
  91 @datalist: a datalist.
  92 @key_id: the #GQuark to identify the data element.
  93 @data: the data element or %NULL to remove any previous element
  94 corresponding to @key_id.
  95 @destroy_func: the function to call when the data element is removed. This
  96 function will be called with the data element and can be used to free any
  97 memory allocated for it. If @data is %NULL, then @destroy_func must
  98 also be %NULL.
  99
 100
 101 <!-- ##### FUNCTION g_datalist_id_get_data ##### -->
 102 <para>
 103 Retrieves the data element corresponding to @key_id.
 104 </para>
 105
 106 @datalist: a datalist.
 107 @key_id: the #GQuark identifying a data element.
 108 @Returns: the data element, or %NULL if it is not found.
 109
 110
 111 <!-- ##### MACRO g_datalist_id_remove_data ##### -->
 112 <para>
 113 Removes an element, using its #GQuark identifier.
 114 </para>
 115
 116 @dl: a datalist.
 117 @q: the #GQuark identifying the data element.
 118
 119
 120 <!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### -->
 121 <para>
 122 Removes an element, without calling its destroy notification function.
 123 </para>
 124
 125 @datalist: a datalist.
 126 @key_id: the #GQuark identifying a data element.
 127 @Returns: the data previously stored at @key_id, or %NULL if none.
 128
 129
 130 <!-- ##### MACRO g_datalist_set_data ##### -->
 131 <para>
 132 Sets the data element corresponding to the given string identifier.
 133 </para>
 134
 135 @dl: a datalist.
 136 @k: the string to identify the data element.
 137 @d: the data element, or %NULL to remove any previous element
 138 corresponding to @k.
 139
 140
 141 <!-- ##### MACRO g_datalist_set_data_full ##### -->
 142 <para>
 143 Sets the data element corresponding to the given string identifier, and the
 144 function to be called when the data element is removed.
 145 </para>
 146
 147 @dl: a datalist.
 148 @k: the string to identify the data element.
 149 @d: the data element, or %NULL to remove any previous element corresponding to
 150 @k.
 151 @f: the function to call when the data element is removed. This
 152 function will be called with the data element and can be used to free any
 153 memory allocated for it. If @d is %NULL, then @f must also be %NULL.
 154
 155
 156 <!-- ##### MACRO g_datalist_get_data ##### -->
 157 <para>
 158 Gets a data element, using its string identifer.
 159 This is slower than g_datalist_id_get_data() because the string is first
 160 converted to a #GQuark.
 161 </para>
 162
 163 @dl: a datalist.
 164 @k: the string identifying a data element.
 165 @Returns: the data element, or %NULL if it is not found.
 166
 167
 168 <!-- ##### MACRO g_datalist_remove_data ##### -->
 169 <para>
 170 Removes an element using its string identifier.
 171 The data element's destroy function is called if it has been set.
 172 </para>
 173
 174 @dl: a datalist.
 175 @k: the string identifying the data element.
 176
 177
 178 <!-- ##### MACRO g_datalist_remove_no_notify ##### -->
 179 <para>
 180 Removes an element, without calling its destroy notifier.
 181 </para>
 182
 183 @dl: a datalist.
 184 @k: the string identifying the data element.
 185
 186
 187 <!-- ##### FUNCTION g_datalist_foreach ##### -->
 188 <para>
 189 Calls the given function for each data element of the datalist.
 190 The function is called with each data element's #GQuark id and data,
 191 together with the given @user_data parameter.
 192 </para>
 193
 194 @datalist: a datalist.
 195 @func: the function to call for each data element.
 196 @user_data: user data to pass to the function.
 197
 198
 199 <!-- ##### FUNCTION g_datalist_clear ##### -->
 200 <para>
 201 Frees all the data elements of the datalist.
 202 The data elements' destroy functions are called if they have been set.
 203 </para>
 204
 205 @datalist: a datalist.
 206
 207
 208 <!-- ##### FUNCTION g_datalist_set_flags ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @datalist:
 214 @flags:
 215
 216
 217 <!-- ##### FUNCTION g_datalist_unset_flags ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @datalist:
 223 @flags:
 224
 225
 226 <!-- ##### FUNCTION g_datalist_get_flags ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @datalist:
 232 @Returns:
 233
 234
 235 <!-- ##### MACRO G_DATALIST_FLAGS_MASK ##### -->
 236 <para>
 237
 238 </para>
 239
 240
 241