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
<!-- ##### STRUCT GConfChangeSet ##### -->
36
An opaque data type representing a set of changes to be made.
37
A change set can contain "set" and "unset" operations.
41
<!-- ##### USER_FUNCTION GConfChangeSetForeachFunc ##### -->
43
The type of a function passed to gconf_change_set_foreach().
44
The @cs argument is the #GConfChangeSet you're iterating over. @key is
45
a key in the change set. @value is the value the key will be set to,
46
or <symbol>NULL</symbol> if the key will be unset. @user_data is the
47
user data passed to gconf_change_set_foreach().
50
@cs: the #GConfChangeSet being iterated over.
51
@key: the current key.
52
@value: the current value, or <symbol>NULL</symbol>.
53
@user_data: user data passed to gconf_change_set_foreach().
56
<!-- ##### FUNCTION gconf_engine_commit_change_set ##### -->
58
Applies the changes in the change set to the #GConfEngine passed as
59
the first argument. If @remove_committed is <symbol>TRUE</symbol>,
60
then any successfully-committed changes are removed from the change
61
set. If @remove_committed is <symbol>FALSE</symbol>, the
62
#GConfChangeSet is left unmodified.
66
If any set or unset operation results in an error, then processing
67
terminates and the error is returned in @err (unless @err was
68
<symbol>NULL</symbol>). If @remove_committed was
69
<symbol>TRUE</symbol>, then all the changes committed before the error
70
occurred will have been removed from the set. If any error occurs,
71
<symbol>FALSE</symbol> is returned.
74
@conf: a #GConfEngine.
75
@cs: a #GConfChangeSet.
76
@remove_committed: whether to remove successfully-committed changes from the set
77
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
78
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> if an error occurs.
81
<!-- ##### FUNCTION gconf_change_set_new ##### -->
83
Creates a new, empty #GConfChangeSet. The caller assumes one reference
84
count, and must call gconf_change_set_unref() eventually.
87
@Returns: a new #GConfChangeSet.
90
<!-- ##### FUNCTION gconf_change_set_ref ##### -->
92
Increases the reference count of a #GConfChangeSet by one.
95
@cs: a #GConfChangeSet.
98
<!-- ##### FUNCTION gconf_change_set_unref ##### -->
100
Decreases the reference count of a #GConfChangeSet by one. If the
101
reference count reaches 0, destroys the #GConfChangeSet.
104
@cs: a #GConfChangeSet.
107
<!-- ##### FUNCTION gconf_change_set_clear ##### -->
109
Clears all changes from a #GConfChangeSet, so that committing the
110
change set would have no effect.
113
@cs: a #GConfChangeSet.
116
<!-- ##### FUNCTION gconf_change_set_size ##### -->
125
<!-- ##### FUNCTION gconf_change_set_remove ##### -->
127
Removes a change from a #GConfChangeSet. The key given as the @key
128
argument will not be modified if this change set is committed.
129
If @key is not in the change set, this function has no effect.
132
@cs: a #GConfChangeSet.
133
@key: key to remove from the change set.
136
<!-- ##### FUNCTION gconf_change_set_foreach ##### -->
138
Iterates over a #GConfChangeSet by calling a
139
#GConfChangeSetForeachFunc for each change in the set. See the
140
description of #GConfChangeSetForeachFunc for details. You may not
141
call gconf_change_set_remove() during the iteration, because you'll
142
confuse the internal data structures and cause memory corruption.
145
@cs: a #GConfChangeSet.
146
@func: function to call for each change in the change set.
147
@user_data: user data to pass to the #GConfChangeSetForeachFunc.
150
<!-- ##### FUNCTION gconf_change_set_set ##### -->
152
Adds a "set" operation to a change set. This function is similar to
153
gconf_engine_set (), except that no errors can occur (errors occur later, when
154
you try to commit the change set).
157
@cs: a #GConfChangeSet.
158
@key: the key to change.
159
@value: the value to change the key to.
162
<!-- ##### FUNCTION gconf_change_set_set_nocopy ##### -->
164
Like gconf_change_set_set(), except that the #GConfChangeSet takes
165
ownership of the #GConfValue. You should not use the value again. It
166
will be destroyed when the change is removed from the #GConfChangeSet,
167
the change is modified, or the #GConfChangeSet is destroyed.
170
@cs: a #GConfChangeSet.
171
@key: the key to change.
172
@value: the new value of @key.
175
<!-- ##### FUNCTION gconf_change_set_unset ##### -->
177
Adds an "unset" operation to a #GConfChangeSet. This function
178
schedules a gconf_engine_unset().
181
@cs: a #GConfChangeSet.
182
@key: the key to unset.
185
<!-- ##### FUNCTION gconf_change_set_set_float ##### -->
187
Adds a "set" operation; takes a #gdouble argument, so you can avoid
188
creating a #GConfValue.
191
@cs: a #GConfChangeSet.
192
@key: the key to set.
193
@val: the new value of @key.
196
<!-- ##### FUNCTION gconf_change_set_set_int ##### -->
198
Adds a "set" operation; takes a #gint argument, so you can avoid
199
creating a #GConfValue.
202
@cs: a #GConfChangeSet.
203
@key: the key to set.
204
@val: the new value of @key.
207
<!-- ##### FUNCTION gconf_change_set_set_string ##### -->
209
Adds a "set" operation; takes a #gchar* argument, so you can avoid
210
creating a #GConfValue.
213
@cs: a #GConfChangeSet.
214
@key: the key to set.
215
@val: the new value of @key.
218
<!-- ##### FUNCTION gconf_change_set_set_bool ##### -->
220
Adds a "set" operation; takes a #gboolean argument, so you can avoid
221
creating a #GConfValue.
224
@cs: a #GConfChangeSet.
225
@key: the key to set.
226
@val: the new value of @key.
229
<!-- ##### FUNCTION gconf_change_set_set_schema ##### -->
231
Adds a "set" operation; takes a #GConfSchema argument, so you can
232
avoid creating a #GConfValue. The schema is copied, @val is left
236
@cs: a #GConfChangeSet.
237
@key: the key to set.
238
@val: the new value of @key.
241
<!-- ##### FUNCTION gconf_change_set_set_list ##### -->
252
<!-- ##### FUNCTION gconf_change_set_set_pair ##### -->
265
<!-- ##### FUNCTION gconf_change_set_check_value ##### -->
276
<!-- ##### FUNCTION gconf_engine_change_set_from_currentv ##### -->
287
<!-- ##### FUNCTION gconf_engine_change_set_from_current ##### -->
299
<!-- ##### FUNCTION gconf_engine_reverse_change_set ##### -->
added
removed
doc/gconf/tmpl/gconf-changeset.sgml
