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.
120
@Returns: the newly allocated #GConfChangeSet.
121
<!-- # Unused Parameters # -->
122
@Varargs: the keys to be set.
125
<!-- ##### FUNCTION gconf_change_set_new ##### -->
127
Creates a new, empty #GConfChangeSet. The caller assumes one reference
128
count, and must call gconf_change_set_unref() eventually.
132
@Returns: a new #GConfChangeSet.
135
<!-- ##### FUNCTION gconf_change_set_ref ##### -->
137
Increases the reference count of a #GConfChangeSet by one.
140
@cs: a #GConfChangeSet.
141
@Returns: the referenced #GConfChangeSet.
144
<!-- ##### FUNCTION gconf_change_set_unref ##### -->
146
Decreases the reference count of a #GConfChangeSet by one. If the
147
reference count reaches 0, destroys the #GConfChangeSet.
150
@cs: a #GConfChangeSet.
153
<!-- ##### FUNCTION gconf_change_set_clear ##### -->
155
Clears all changes from a #GConfChangeSet, so that committing the
156
change set would have no effect.
159
@cs: a #GConfChangeSet.
162
<!-- ##### FUNCTION gconf_change_set_size ##### -->
164
Returns the size of the changeset, a #guint value.
167
@cs: a #GConfChangeSet.
168
@Returns: the size, a #guint value.
171
<!-- ##### FUNCTION gconf_change_set_remove ##### -->
173
Removes a change from a #GConfChangeSet. The key given as the @key
174
argument will not be modified if this change set is committed.
175
If @key is not in the change set, this function has no effect.
178
@cs: a #GConfChangeSet.
179
@key: key to remove from the change set.
182
<!-- ##### FUNCTION gconf_change_set_foreach ##### -->
192
<!-- ##### FUNCTION gconf_change_set_check_value ##### -->
194
Looks up the hash table associated with the #GConfChangeSet for the key @key. If the key
195
is found , the value is set in value_retloc.
198
@cs: a #GConfChangeSet.
199
@key: the key to be searched in the changeset.
200
@value_retloc: a #GConfValue ** to hold the key, if found.
201
@Returns: <symbol>TRUE</symbol> on finding the key, <symbol>FALSE</symbol> if key is not found.
204
<!-- ##### FUNCTION gconf_change_set_set ##### -->
206
Adds a "set" operation to a change set. This function is similar to
207
gconf_engine_set (), except that no errors can occur (errors occur later, when
208
you try to commit the change set).
211
@cs: a #GConfChangeSet.
212
@key: the key to change.
213
@value: the value to change the key to.
216
<!-- ##### FUNCTION gconf_change_set_set_nocopy ##### -->
218
Like gconf_change_set_set(), except that the #GConfChangeSet takes
219
ownership of the #GConfValue. You should not use the value again. It
220
will be destroyed when the change is removed from the #GConfChangeSet,
221
the change is modified, or the #GConfChangeSet is destroyed.
224
@cs: a #GConfChangeSet.
225
@key: the key to change.
226
@value: the new value of @key.
229
<!-- ##### FUNCTION gconf_change_set_unset ##### -->
231
Adds an "unset" operation to a #GConfChangeSet. This function
232
schedules a gconf_engine_unset().
235
@cs: a #GConfChangeSet.
236
@key: the key to unset.
239
<!-- ##### FUNCTION gconf_change_set_set_float ##### -->
241
Adds a "set" operation; takes a #gdouble argument, so you can avoid
242
creating a #GConfValue.
245
@cs: a #GConfChangeSet.
246
@key: the key to set.
247
@val: the new value of @key.
250
<!-- ##### FUNCTION gconf_change_set_set_int ##### -->
252
Adds a "set" operation; takes a #gint argument, so you can avoid
253
creating a #GConfValue.
256
@cs: a #GConfChangeSet.
257
@key: the key to set.
258
@val: the new value of @key.
261
<!-- ##### FUNCTION gconf_change_set_set_string ##### -->
263
Adds a "set" operation; takes a #gchar* argument, so you can avoid
264
creating a #GConfValue.
267
@cs: a #GConfChangeSet.
268
@key: the key to set.
269
@val: the new value of @key.
272
<!-- ##### FUNCTION gconf_change_set_set_bool ##### -->
274
Adds a "set" operation; takes a #gboolean argument, so you can avoid
275
creating a #GConfValue.
278
@cs: a #GConfChangeSet.
279
@key: the key to set.
280
@val: the new value of @key.
283
<!-- ##### FUNCTION gconf_change_set_set_schema ##### -->
285
Adds a "set" operation; takes a #GConfSchema argument, so you can
286
avoid creating a #GConfValue. The schema is copied, @val is left
290
@cs: a #GConfChangeSet.
291
@key: the key to set.
292
@val: the new value of @key.
295
<!-- ##### FUNCTION gconf_change_set_set_list ##### -->
297
Adds a "set" operation; takes a #GList argument and the type of the
298
list, so you can avoid creating a #GConfValue. This results in the
299
list of values being set for the key.
302
@cs: a #GConfChangeSet.
303
@key: the key to set.
304
@list_type: the type of the list.
305
@list: a #GList containing the values to be set.
308
<!-- ##### FUNCTION gconf_change_set_set_pair ##### -->
310
Adds a "set" operation; takes a pointer to the addresses of the pair
311
of values, so you can avoid creating a #GConfValue. This results in
312
the pair of values being set for the key.
315
@cs: a #GConfChangeSet.
316
@key: the key to set.
317
@car_type: the type of the pair's first field. (car)
318
@cdr_type: the type of the pair's second field. (cdr)
319
@address_of_car: address of the car.
320
@address_of_cdr: address of the cdr.
323
<!-- ##### FUNCTION gconf_change_set_set_user_data ##### -->
333
<!-- ##### FUNCTION gconf_change_set_get_user_data ##### -->
added
removed
doc/gconf/tmpl/gconf-changeset.sgml
