1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
6
a set of configuration changes to be made.
8
<!-- ##### SECTION Long_Description ##### -->
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.
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>
29
<!-- ##### SECTION See_Also ##### -->
34
<!-- ##### SECTION Stability_Level ##### -->
37
<!-- ##### SECTION Image ##### -->
40
<!-- ##### STRUCT GConfChangeSet ##### -->
42
An opaque data type representing a set of changes to be made.
43
A change set can contain "set" and "unset" operations.
47
<!-- ##### USER_FUNCTION GConfChangeSetForeachFunc ##### -->
49
The type of a function passed to gconf_change_set_foreach().
50
The @cs argument is the #GConfChangeSet you're iterating over. @key is
51
a key in the change set. @value is the value the key will be set to,
52
or <symbol>NULL</symbol> if the key will be unset. @user_data is the
53
user data passed to gconf_change_set_foreach().
56
@cs: the #GConfChangeSet being iterated over.
57
@key: the current key.
58
@value: the current value, or <symbol>NULL</symbol>.
59
@user_data: user data passed to gconf_change_set_foreach().
62
<!-- ##### FUNCTION gconf_engine_commit_change_set ##### -->
64
Applies the changes in the change set to the #GConfEngine passed as
65
the first argument. If @remove_committed is <symbol>TRUE</symbol>,
66
then any successfully-committed changes are removed from the change
67
set. If @remove_committed is <symbol>FALSE</symbol>, the
68
#GConfChangeSet is left unmodified.
72
If any set or unset operation results in an error, then processing
73
terminates and the error is returned in @err (unless @err was
74
<symbol>NULL</symbol>). If @remove_committed was
75
<symbol>TRUE</symbol>, then all the changes committed before the error
76
occurred will have been removed from the set. If any error occurs,
77
<symbol>FALSE</symbol> is returned.
80
@conf: a #GConfEngine.
81
@cs: a #GConfChangeSet.
82
@remove_committed: whether to remove successfully-committed changes from the set
83
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
84
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> if an error occurs.
87
<!-- ##### FUNCTION gconf_engine_reverse_change_set ##### -->
89
Creates a change set that would reverse @cs. That is, for each change in @cs,
90
save the current state of that key in the returned change set.
93
@conf: a #GConfEngine.
94
@cs: the #GConfChangeSet to be reverted.
95
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
96
@Returns: the modified #GConfChangeSet.
99
<!-- ##### FUNCTION gconf_engine_change_set_from_currentv ##### -->
101
Creates a change set that will change the keys in
102
<symbol>NULL</symbol>terminated array @keys to their current state.
105
@conf: a #GConfEngine.
106
@keys: <symbol>NULL</symbol>terminated array of key names.
107
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
108
@Returns: the newly allocated #GConfChangeSet.
111
<!-- ##### FUNCTION gconf_engine_change_set_from_current ##### -->
113
Convenient Varags version of gconf_engine_change_set_from_current().
116
@conf: a #GConfEngine.
117
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
118
@first_key: the first key, a char* value.
119
@Varargs: the keys to be set.
120
@Returns: the newly allocated #GConfChangeSet.
123
<!-- ##### FUNCTION gconf_change_set_new ##### -->
125
Creates a new, empty #GConfChangeSet. The caller assumes one reference
126
count, and must call gconf_change_set_unref() eventually.
130
@Returns: a new #GConfChangeSet.
133
<!-- ##### FUNCTION gconf_change_set_ref ##### -->
135
Increases the reference count of a #GConfChangeSet by one.
138
@cs: a #GConfChangeSet.
139
@Returns: the referenced #GConfChangeSet.
142
<!-- ##### FUNCTION gconf_change_set_unref ##### -->
144
Decreases the reference count of a #GConfChangeSet by one. If the
145
reference count reaches 0, destroys the #GConfChangeSet.
148
@cs: a #GConfChangeSet.
151
<!-- ##### FUNCTION gconf_change_set_clear ##### -->
153
Clears all changes from a #GConfChangeSet, so that committing the
154
change set would have no effect.
157
@cs: a #GConfChangeSet.
160
<!-- ##### FUNCTION gconf_change_set_size ##### -->
162
Returns the size of the changeset, a #guint value.
165
@cs: a #GConfChangeSet.
166
@Returns: the size, a #guint value.
169
<!-- ##### FUNCTION gconf_change_set_remove ##### -->
171
Removes a change from a #GConfChangeSet. The key given as the @key
172
argument will not be modified if this change set is committed.
173
If @key is not in the change set, this function has no effect.
176
@cs: a #GConfChangeSet.
177
@key: key to remove from the change set.
180
<!-- ##### FUNCTION gconf_change_set_foreach ##### -->
190
<!-- ##### FUNCTION gconf_change_set_check_value ##### -->
192
Looks up the hash table associated with the #GConfChangeSet for the key @key. If the key
193
is found , the value is set in value_retloc.
196
@cs: a #GConfChangeSet.
197
@key: the key to be searched in the changeset.
198
@value_retloc: a #GConfValue ** to hold the key, if found.
199
@Returns: <symbol>TRUE</symbol> on finding the key, <symbol>FALSE</symbol> if key is not found.
202
<!-- ##### FUNCTION gconf_change_set_set ##### -->
204
Adds a "set" operation to a change set. This function is similar to
205
gconf_engine_set (), except that no errors can occur (errors occur later, when
206
you try to commit the change set).
209
@cs: a #GConfChangeSet.
210
@key: the key to change.
211
@value: the value to change the key to.
214
<!-- ##### FUNCTION gconf_change_set_set_nocopy ##### -->
216
Like gconf_change_set_set(), except that the #GConfChangeSet takes
217
ownership of the #GConfValue. You should not use the value again. It
218
will be destroyed when the change is removed from the #GConfChangeSet,
219
the change is modified, or the #GConfChangeSet is destroyed.
222
@cs: a #GConfChangeSet.
223
@key: the key to change.
224
@value: the new value of @key.
227
<!-- ##### FUNCTION gconf_change_set_unset ##### -->
229
Adds an "unset" operation to a #GConfChangeSet. This function
230
schedules a gconf_engine_unset().
233
@cs: a #GConfChangeSet.
234
@key: the key to unset.
237
<!-- ##### FUNCTION gconf_change_set_set_float ##### -->
239
Adds a "set" operation; takes a #gdouble argument, so you can avoid
240
creating a #GConfValue.
243
@cs: a #GConfChangeSet.
244
@key: the key to set.
245
@val: the new value of @key.
248
<!-- ##### FUNCTION gconf_change_set_set_int ##### -->
250
Adds a "set" operation; takes a #gint argument, so you can avoid
251
creating a #GConfValue.
254
@cs: a #GConfChangeSet.
255
@key: the key to set.
256
@val: the new value of @key.
259
<!-- ##### FUNCTION gconf_change_set_set_string ##### -->
261
Adds a "set" operation; takes a #gchar* argument, so you can avoid
262
creating a #GConfValue.
265
@cs: a #GConfChangeSet.
266
@key: the key to set.
267
@val: the new value of @key.
270
<!-- ##### FUNCTION gconf_change_set_set_bool ##### -->
272
Adds a "set" operation; takes a #gboolean argument, so you can avoid
273
creating a #GConfValue.
276
@cs: a #GConfChangeSet.
277
@key: the key to set.
278
@val: the new value of @key.
281
<!-- ##### FUNCTION gconf_change_set_set_schema ##### -->
283
Adds a "set" operation; takes a #GConfSchema argument, so you can
284
avoid creating a #GConfValue. The schema is copied, @val is left
288
@cs: a #GConfChangeSet.
289
@key: the key to set.
290
@val: the new value of @key.
293
<!-- ##### FUNCTION gconf_change_set_set_list ##### -->
295
Adds a "set" operation; takes a #GList argument and the type of the
296
list, so you can avoid creating a #GConfValue. This results in the
297
list of values being set for the key.
300
@cs: a #GConfChangeSet.
301
@key: the key to set.
302
@list_type: the type of the list.
303
@list: a #GList containing the values to be set.
306
<!-- ##### FUNCTION gconf_change_set_set_pair ##### -->
308
Adds a "set" operation; takes a pointer to the addresses of the pair
309
of values, so you can avoid creating a #GConfValue. This results in
310
the pair of values being set for the key.
313
@cs: a #GConfChangeSet.
314
@key: the key to set.
315
@car_type: the type of the pair's first field. (car)
316
@cdr_type: the type of the pair's second field. (cdr)
317
@address_of_car: address of the car.
318
@address_of_cdr: address of the cdr.
321
<!-- ##### FUNCTION gconf_change_set_set_user_data ##### -->
331
<!-- ##### FUNCTION gconf_change_set_get_user_data ##### -->
added
removed
doc/gconf/tmpl/gconf-changeset.sgml
