doc/gconf/tmpl/gconf-changeset.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GConfChangeSet
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 a set of configuration changes to be made.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 a #GConfChangeSet allows you to collect a set of changes to
  11 configuration keys (set/unset operations). You can then commit
  12 all the changes at once. This is convenient for something like a
  13 preferences dialog; you can collect all the pending changes in a
  14 #GConfChangeSet, then when the user clicks "apply" send them all to
  15 the configuration database. The #GConfChangeSet allows you to avoid
  16 sending every preferences setting when "apply" is clicked; you only
  17 have to send the settings the user changed.
  18 </para>
  19
  20 <para>
  21 In the future, GConf may also have optimizations so that
  22 changing a group of values with #GConfChangeSet is faster than calling
  23 gconf_engine_set () for each value. In the future, #GConfChangeSet may also
  24 represent an atomic transaction, where all or none of the values are
  25 set; however, for now the operation is <emphasis>not</emphasis>
  26 atomic.
  27 </para>
  28
  29 <!-- ##### SECTION See_Also ##### -->
  30 <para>
  31
  32 </para>
  33
  34 <!-- ##### SECTION Stability_Level ##### -->
  35
  36
  37 <!-- ##### STRUCT GConfChangeSet ##### -->
  38 <para>
  39 An opaque data type representing a set of changes to be made.
  40 A change set can contain "set" and "unset" operations.
  41 </para>
  42
  43
  44 <!-- ##### USER_FUNCTION GConfChangeSetForeachFunc ##### -->
  45 <para>
  46 The type of a function passed to gconf_change_set_foreach().
  47 The @cs argument is the #GConfChangeSet you're iterating over. @key is
  48 a key in the change set. @value is the value the key will be set to,
  49 or <symbol>NULL</symbol> if the key will be unset. @user_data is the
  50 user data passed to gconf_change_set_foreach().
  51 </para>
  52
  53 @cs: the #GConfChangeSet being iterated over.
  54 @key: the current key.
  55 @value: the current value, or <symbol>NULL</symbol>.
  56 @user_data: user data passed to gconf_change_set_foreach().
  57
  58
  59 <!-- ##### FUNCTION gconf_engine_commit_change_set ##### -->
  60 <para>
  61 Applies the changes in the change set to the #GConfEngine passed as
  62 the first argument. If @remove_committed is <symbol>TRUE</symbol>,
  63 then any successfully-committed changes are removed from the change
  64 set. If @remove_committed is <symbol>FALSE</symbol>, the
  65 #GConfChangeSet is left unmodified.
  66 </para>
  67
  68 <para>
  69 If any set or unset operation results in an error, then processing
  70 terminates and the error is returned in @err (unless @err was
  71 <symbol>NULL</symbol>). If @remove_committed was
  72 <symbol>TRUE</symbol>, then all the changes committed before the error
  73 occurred will have been removed from the set. If any error occurs,
  74 <symbol>FALSE</symbol> is returned.
  75 </para>
  76
  77 @conf: a #GConfEngine.
  78 @cs: a #GConfChangeSet.
  79 @remove_committed: whether to remove successfully-committed changes from the set
  80 @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
  81 @Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> if an error occurs.
  82
  83
  84 <!-- ##### FUNCTION gconf_engine_reverse_change_set ##### -->
  85 <para>
  86 Creates a change set that would reverse @cs. That is, for each change in @cs,
  87 save the current state of that key in the returned change set.
  88 </para>
  89
  90 @conf: a #GConfEngine.
  91 @cs: the #GConfChangeSet to be reverted.
  92 @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
  93 @Returns: the modified #GConfChangeSet.
  94
  95
  96 <!-- ##### FUNCTION gconf_engine_change_set_from_currentv ##### -->
  97 <para>
  98 Creates a change set that will change the keys in
  99 <symbol>NULL</symbol>terminated array @keys to their current state.
 100 </para>
 101
 102 @conf: a #GConfEngine.
 103 @keys: <symbol>NULL</symbol>terminated array of key names.
 104 @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
 105 @Returns: the newly allocated #GConfChangeSet.
 106
 107
 108 <!-- ##### FUNCTION gconf_engine_change_set_from_current ##### -->
 109 <para>
 110 Convenient Varags version of gconf_engine_change_set_from_current().
 111 </para>
 112
 113 @conf: a #GConfEngine.
 114 @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
 115 @first_key: the first key, a char* value.
 116 @Varargs: the keys to be set.
 117 @Returns: the newly allocated #GConfChangeSet.
 118
 119
 120 <!-- ##### FUNCTION gconf_change_set_new ##### -->
 121 <para>
 122 Creates a new, empty #GConfChangeSet. The caller assumes one reference
 123 count, and must call gconf_change_set_unref() eventually.
 124 </para>
 125
 126 @Returns: a new #GConfChangeSet.
 127
 128
 129 <!-- ##### FUNCTION gconf_change_set_ref ##### -->
 130 <para>
 131 Increases the reference count of a #GConfChangeSet by one.
 132 </para>
 133
 134 @cs: a #GConfChangeSet.
 135
 136
 137 <!-- ##### FUNCTION gconf_change_set_unref ##### -->
 138 <para>
 139 Decreases the reference count of a #GConfChangeSet by one. If the
 140 reference count reaches 0, destroys the #GConfChangeSet.
 141 </para>
 142
 143 @cs: a #GConfChangeSet.
 144
 145
 146 <!-- ##### FUNCTION gconf_change_set_clear ##### -->
 147 <para>
 148 Clears all changes from a #GConfChangeSet, so that committing the
 149 change set would have no effect.
 150 </para>
 151
 152 @cs: a #GConfChangeSet.
 153
 154
 155 <!-- ##### FUNCTION gconf_change_set_size ##### -->
 156 <para>
 157 Returns the size of the changeset, a #guint value.
 158 </para>
 159
 160 @cs: a #GConfChangeSet.
 161 @Returns: the size, a #guint value.
 162
 163
 164 <!-- ##### FUNCTION gconf_change_set_remove ##### -->
 165 <para>
 166 Removes a change from a #GConfChangeSet. The key given as the @key
 167 argument will not be modified if this change set is committed.
 168 If @key is not in the change set, this function has no effect.
 169 </para>
 170
 171 @cs: a #GConfChangeSet.
 172 @key: key to remove from the change set.
 173
 174
 175 <!-- ##### FUNCTION gconf_change_set_foreach ##### -->
 176 <para>
 177 Iterates over a #GConfChangeSet by calling a
 178 #GConfChangeSetForeachFunc for each change in the set. See the
 179 description of #GConfChangeSetForeachFunc for details.  You may not
 180 call gconf_change_set_remove() during the iteration, because you'll
 181 confuse the internal data structures and cause memory corruption.
 182 </para>
 183
 184 @cs: a #GConfChangeSet.
 185 @func: function to call for each change in the change set.
 186 @user_data: user data to pass to the #GConfChangeSetForeachFunc.
 187
 188
 189 <!-- ##### FUNCTION gconf_change_set_check_value ##### -->
 190 <para>
 191 Looks up the hash table associated with the #GConfChangeSet for the key @key. If the key
 192 is found , the value is set in value_retloc.
 193 </para>
 194
 195 @cs: a #GConfChangeSet.
 196 @key: the key to be searched in the changeset.
 197 @value_retloc: a #GConfValue ** to hold the key, if found.
 198 @Returns: <symbol>TRUE</symbol> on finding the key, <symbol>FALSE</symbol> if key is not found.
 199
 200
 201 <!-- ##### FUNCTION gconf_change_set_set ##### -->
 202 <para>
 203 Adds a "set" operation to a change set. This function is similar to
 204 gconf_engine_set (), except that no errors can occur (errors occur later, when
 205 you try to commit the change set).
 206 </para>
 207
 208 @cs: a #GConfChangeSet.
 209 @key: the key to change.
 210 @value: the value to change the key to.
 211
 212
 213 <!-- ##### FUNCTION gconf_change_set_set_nocopy ##### -->
 214 <para>
 215 Like gconf_change_set_set(), except that the #GConfChangeSet takes
 216 ownership of the #GConfValue. You should not use the value again.  It
 217 will be destroyed when the change is removed from the #GConfChangeSet,
 218 the change is modified, or the #GConfChangeSet is destroyed.
 219 </para>
 220
 221 @cs: a #GConfChangeSet.
 222 @key: the key to change.
 223 @value: the new value of @key.
 224
 225
 226 <!-- ##### FUNCTION gconf_change_set_unset ##### -->
 227 <para>
 228 Adds an "unset" operation to a #GConfChangeSet. This function
 229 schedules a gconf_engine_unset().
 230 </para>
 231
 232 @cs: a #GConfChangeSet.
 233 @key: the key to unset.
 234
 235
 236 <!-- ##### FUNCTION gconf_change_set_set_float ##### -->
 237 <para>
 238 Adds a "set" operation; takes a #gdouble argument, so you can avoid
 239 creating a #GConfValue.
 240 </para>
 241
 242 @cs: a #GConfChangeSet.
 243 @key: the key to set.
 244 @val: the new value of @key.
 245
 246
 247 <!-- ##### FUNCTION gconf_change_set_set_int ##### -->
 248 <para>
 249 Adds a "set" operation; takes a #gint argument, so you can avoid
 250 creating a #GConfValue.
 251 </para>
 252
 253 @cs: a #GConfChangeSet.
 254 @key: the key to set.
 255 @val: the new value of @key.
 256
 257
 258 <!-- ##### FUNCTION gconf_change_set_set_string ##### -->
 259 <para>
 260 Adds a "set" operation; takes a #gchar* argument, so you can avoid
 261 creating a #GConfValue.
 262 </para>
 263
 264 @cs: a #GConfChangeSet.
 265 @key: the key to set.
 266 @val: the new value of @key.
 267
 268
 269 <!-- ##### FUNCTION gconf_change_set_set_bool ##### -->
 270 <para>
 271 Adds a "set" operation; takes a #gboolean argument, so you can avoid
 272 creating a #GConfValue.
 273 </para>
 274
 275 @cs: a #GConfChangeSet.
 276 @key: the key to set.
 277 @val: the new value of @key.
 278
 279
 280 <!-- ##### FUNCTION gconf_change_set_set_schema ##### -->
 281 <para>
 282 Adds a "set" operation; takes a #GConfSchema argument, so you can
 283 avoid creating a #GConfValue. The schema is copied, @val is left
 284 unmodified.
 285 </para>
 286
 287 @cs: a #GConfChangeSet.
 288 @key: the key to set.
 289 @val: the new value of @key.
 290
 291
 292 <!-- ##### FUNCTION gconf_change_set_set_list ##### -->
 293 <para>
 294 Adds a "set" operation; takes a #GList argument and the type of the
 295 list, so you can avoid creating a #GConfValue. This results in the
 296 list of values being set for the key.
 297 </para>
 298
 299 @cs: a #GConfChangeSet.
 300 @key: the key to set.
 301 @list_type: the type of the list.
 302 @list: a #GList containing the values to be set.
 303
 304
 305 <!-- ##### FUNCTION gconf_change_set_set_pair ##### -->
 306 <para>
 307 Adds a "set" operation; takes a pointer to the addresses of the pair
 308 of values, so you can avoid creating a #GConfValue. This results in
 309 the pair of values being set for the key.
 310 </para>
 311
 312 @cs: a #GConfChangeSet.
 313 @key: the key to set.
 314 @car_type: the type of the pair's first field. (car)
 315 @cdr_type: the type of the pair's second field. (cdr)
 316 @address_of_car: address of the car.
 317 @address_of_cdr: address of the cdr.
 318
 319
 320 <!-- ##### FUNCTION gconf_change_set_set_user_data ##### -->
 321 <para>
 322 Sets the user_data and the destroy notification function fields of the
 323 #GConfChangeSet.
 324 </para>
 325
 326 @cs: a #GConfChangeSet.
 327 @data: a #gpointer.
 328 @dnotify: a pointer to the function to be called during destroy.
 329
 330
 331 <!-- ##### FUNCTION gconf_change_set_get_user_data ##### -->
 332 <para>
 333 Returns the user_data field of the #GConfChangeSet.
 334 </para>
 335
 336 @cs: a #GConfChangeSet.
 337 @Returns: a pointer to the user_data.
 338
 339