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