path: root/doc/gconf/tmpl/gconf-changeset.sgml

<!-- ##### SECTION Title ##### -->
GConfChangeSet

<!-- ##### SECTION Short_Description ##### -->

a set of configuration changes to be made.

<!-- ##### SECTION Long_Description ##### -->
<para>
a #GConfChangeSet allows you to collect a set of changes to
configuration keys (set/unset operations). You can then commit 
all the changes at once. This is convenient for something like a
preferences dialog; you can collect all the pending changes in a
#GConfChangeSet, then when the user clicks "apply" send them all to
the configuration database. The #GConfChangeSet allows you to avoid
sending every preferences setting when "apply" is clicked; you only 
have to send the settings the user changed.
</para>

<para>
In the future, GConf may also have optimizations so that
changing a group of values with #GConfChangeSet is faster than calling 
gconf_engine_set () for each value. In the future, #GConfChangeSet may also
represent an atomic transaction, where all or none of the values are
set; however, for now the operation is <emphasis>not</emphasis>
atomic.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### STRUCT GConfChangeSet ##### -->
<para>
An opaque data type representing a set of changes to be made. 
A change set can contain "set" and "unset" operations.
</para>


<!-- ##### USER_FUNCTION GConfChangeSetForeachFunc ##### -->
<para>
The type of a function passed to gconf_change_set_foreach(). 
The @cs argument is the #GConfChangeSet you're iterating over. @key is
a key in the change set. @value is the value the key will be set to,
or <symbol>NULL</symbol> if the key will be unset. @user_data is the
user data passed to gconf_change_set_foreach().
</para>

@cs: the #GConfChangeSet being iterated over.
@key: the current key.
@value: the current value, or <symbol>NULL</symbol>.
@user_data: user data passed to gconf_change_set_foreach().


<!-- ##### FUNCTION gconf_engine_commit_change_set ##### -->
<para>
Applies the changes in the change set to the #GConfEngine passed as
the first argument. If @remove_committed is <symbol>TRUE</symbol>,
then any successfully-committed changes are removed from the change
set. If @remove_committed is <symbol>FALSE</symbol>, the
#GConfChangeSet is left unmodified.
</para>

<para>
If any set or unset operation results in an error, then processing
terminates and the error is returned in @err (unless @err was
<symbol>NULL</symbol>). If @remove_committed was
<symbol>TRUE</symbol>, then all the changes committed before the error
occurred will have been removed from the set. If any error occurs,
<symbol>FALSE</symbol> is returned.
</para>

@conf: a #GConfEngine.
@cs: a #GConfChangeSet.
@remove_committed: whether to remove successfully-committed changes from the set
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> if an error occurs.


<!-- ##### FUNCTION gconf_engine_reverse_change_set ##### -->
<para>
Creates a change set that would reverse @cs. That is, for each change in @cs,
save the current state of that key in the returned change set.
</para>

@conf: a #GConfEngine.
@cs: the #GConfChangeSet to be reverted.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the modified #GConfChangeSet.


<!-- ##### FUNCTION gconf_engine_change_set_from_currentv ##### -->
<para>
Creates a change set that will change the keys in 
<symbol>NULL</symbol>terminated array @keys to their current state.
</para>

@conf: a #GConfEngine.
@keys: <symbol>NULL</symbol>terminated array of key names.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@Returns: the newly allocated #GConfChangeSet.


<!-- ##### FUNCTION gconf_engine_change_set_from_current ##### -->
<para>
Convenient Varags version of gconf_engine_change_set_from_current().
</para>

@conf: a #GConfEngine.
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
@first_key: the first key, a char* value.
@Varargs: the keys to be set.
@Returns: the newly allocated #GConfChangeSet.


<!-- ##### FUNCTION gconf_change_set_new ##### -->
<para>
Creates a new, empty #GConfChangeSet. The caller assumes one reference
count, and must call gconf_change_set_unref() eventually.
</para>

@void: 
@Returns: a new #GConfChangeSet.


<!-- ##### FUNCTION gconf_change_set_ref ##### -->
<para>
Increases the reference count of a #GConfChangeSet by one.
</para>

@cs: a #GConfChangeSet.


<!-- ##### FUNCTION gconf_change_set_unref ##### -->
<para>
Decreases the reference count of a #GConfChangeSet by one. If the
reference count reaches 0, destroys the #GConfChangeSet.
</para>

@cs: a #GConfChangeSet.


<!-- ##### FUNCTION gconf_change_set_clear ##### -->
<para>
Clears all changes from a #GConfChangeSet, so that committing the
change set would have no effect.
</para>

@cs: a #GConfChangeSet.


<!-- ##### FUNCTION gconf_change_set_size ##### -->
<para>
Returns the size of the changeset, a #guint value.
</para>

@cs: a #GConfChangeSet.
@Returns: the size, a #guint value.


<!-- ##### FUNCTION gconf_change_set_remove ##### -->
<para>
Removes a change from a #GConfChangeSet. The key given as the @key
argument will not be modified if this change set is committed.
If @key is not in the change set, this function has no effect.
</para>

@cs: a #GConfChangeSet.
@key: key to remove from the change set.


<!-- ##### FUNCTION gconf_change_set_foreach ##### -->
<para>
Iterates over a #GConfChangeSet by calling a
#GConfChangeSetForeachFunc for each change in the set. See the
description of #GConfChangeSetForeachFunc for details.  You may not
call gconf_change_set_remove() during the iteration, because you'll
confuse the internal data structures and cause memory corruption.
</para>

@cs: a #GConfChangeSet.
@func: function to call for each change in the change set.
@user_data: user data to pass to the #GConfChangeSetForeachFunc.


<!-- ##### FUNCTION gconf_change_set_check_value ##### -->
<para>
Looks up the hash table associated with the #GConfChangeSet for the key @key. If the key
is found , the value is set in value_retloc.
</para>

@cs: a #GConfChangeSet.
@key: the key to be searched in the changeset.
@value_retloc: a #GConfValue ** to hold the key, if found.
@Returns: <symbol>TRUE</symbol> on finding the key, <symbol>FALSE</symbol> if key is not found.


<!-- ##### FUNCTION gconf_change_set_set ##### -->
<para>
Adds a "set" operation to a change set. This function is similar to
gconf_engine_set (), except that no errors can occur (errors occur later, when
you try to commit the change set).
</para>

@cs: a #GConfChangeSet.
@key: the key to change.
@value: the value to change the key to.


<!-- ##### FUNCTION gconf_change_set_set_nocopy ##### -->
<para>
Like gconf_change_set_set(), except that the #GConfChangeSet takes
ownership of the #GConfValue. You should not use the value again.  It
will be destroyed when the change is removed from the #GConfChangeSet,
the change is modified, or the #GConfChangeSet is destroyed.
</para>

@cs: a #GConfChangeSet.
@key: the key to change.
@value: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_unset ##### -->
<para>
Adds an "unset" operation to a #GConfChangeSet. This function
schedules a gconf_engine_unset().
</para>

@cs: a #GConfChangeSet.
@key: the key to unset.


<!-- ##### FUNCTION gconf_change_set_set_float ##### -->
<para>
Adds a "set" operation; takes a #gdouble argument, so you can avoid
creating a #GConfValue.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@val: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_set_int ##### -->
<para>
Adds a "set" operation; takes a #gint argument, so you can avoid
creating a #GConfValue.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@val: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_set_string ##### -->
<para>
Adds a "set" operation; takes a #gchar* argument, so you can avoid
creating a #GConfValue.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@val: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_set_bool ##### -->
<para>
Adds a "set" operation; takes a #gboolean argument, so you can avoid
creating a #GConfValue.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@val: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_set_schema ##### -->
<para>
Adds a "set" operation; takes a #GConfSchema argument, so you can
avoid creating a #GConfValue. The schema is copied, @val is left
unmodified.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@val: the new value of @key.


<!-- ##### FUNCTION gconf_change_set_set_list ##### -->
<para>
Adds a "set" operation; takes a #GList argument and the type of the
list, so you can avoid creating a #GConfValue. This results in the 
list of values being set for the key.  
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@list_type: the type of the list.
@list: a #GList containing the values to be set.


<!-- ##### FUNCTION gconf_change_set_set_pair ##### -->
<para>
Adds a "set" operation; takes a pointer to the addresses of the pair
of values, so you can avoid creating a #GConfValue. This results in 
the pair of values being set for the key.
</para>

@cs: a #GConfChangeSet.
@key: the key to set.
@car_type: the type of the pair's first field. (car)
@cdr_type: the type of the pair's second field. (cdr)
@address_of_car: address of the car.
@address_of_cdr: address of the cdr.


<!-- ##### FUNCTION gconf_change_set_set_user_data ##### -->
<para>
Sets the user_data and the destroy notification function fields of the 
#GConfChangeSet.
</para>

@cs: a #GConfChangeSet.
@data: a #gpointer.
@dnotify: a pointer to the function to be called during destroy.


<!-- ##### FUNCTION gconf_change_set_get_user_data ##### -->
<para>
Returns the user_data field of the #GConfChangeSet.
</para>

@cs: a #GConfChangeSet.
@Returns: a pointer to the user_data.