[glib/new-gsettings] Document binding api

[Matthias Clasen <matthiasc src gnome org>]

commit 741a4cb25f56e3ec6604a11bff59bc614cc53d3f
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Apr 16 15:21:22 2010 -0400

    Document binding api

 gio/gsettings.c |   58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 gio/gsettings.h |   33 +++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 0 deletions(-)
---
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 32a22e4..4a76b00 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -1477,6 +1477,27 @@ g_settings_get_mapping (GValue   *value,
   return FALSE;
 }
 
+/**
+ * g_settings_bind:
+ * @settings: a #GSettings object
+ * @key: the key to bind
+ * @object: a #GObject
+ * @property: the name of the property to bind
+ * @flags: flags for the binding
+ *
+ * Create a binding between the @key in the @settings object
+ * and the property @property of @object, using the default GIO
+ * mapping functions to map between the settings and property values.
+ *
+ * The default GIO mapping functions handle booleans, numeric and
+ * string types in a straightforward way. See g_settings_bind_with_mapping()
+ * if you need a custom mapping.
+ *
+ * Note that the lifecycle of the binding is tied to the
+ * object.
+ *
+ * Since: 2.26
+ */
 void
 g_settings_bind (GSettings          *settings,
                  const gchar        *key,
@@ -1488,6 +1509,30 @@ g_settings_bind (GSettings          *settings,
                                 flags, NULL, NULL, NULL);
 }
 
+/**
+ * g_settings_bind_with_mapping:
+ * @settings: a #GSettings object
+ * @key: the key to bind
+ * @object: a #GObject
+ * @property: the name of the property to bind
+ * @flags: flags for the binding
+ * @get_mapping: a function that gets called to convert values
+ *     from @settings to @object, or %NULL to use the default GIO mapping
+ * @set_mapping: a function that gets called to convert values
+ *     from @object to @settings, or %NULL to use the default GIO mapping
+ * @user_data: data that gets passed to @get_mapping and @set_mapping
+ *
+ * Create a binding between the @key in the @settings object
+ * and the property @property of @object, using the provided mapping
+ * functions to map between settings and property values.
+ *
+ * Note that the lifecycle of the binding is tied to the object,
+ * and that you can have only one binding per object property.
+ * If you bind the same property twice on the same object, the second
+ * binding overrides the first one.
+ *
+ * Since: 2.26
+ */
 void
 g_settings_bind_with_mapping (GSettings               *settings,
                               const gchar             *key,
@@ -1628,6 +1673,19 @@ g_settings_bind_with_mapping (GSettings               *settings,
                            binding, g_settings_binding_free);
 }
 
+/**
+ * g_settings_unbind:
+ * @object: the object
+ * @property: the property whose binding is removed
+ *
+ * Removes an existing binding for @property on @object.
+ *
+ * Note that bindings are automatically removed when the
+ * object is finalized, so it is rarely necessary to call this
+ * function.
+ *
+ * Since: 2.26
+ */
 void
 g_settings_unbind (gpointer     object,
                    const gchar *property)
diff --git a/gio/gsettings.h b/gio/gsettings.h
index 3fbe763..b8e7e1f 100644
--- a/gio/gsettings.h
+++ b/gio/gsettings.h
@@ -131,14 +131,47 @@ void                    g_settings_apply                                (GSettin
 void                    g_settings_revert                               (GSettings          *settings);
 gboolean                g_settings_get_has_unapplied                    (GSettings          *settings);
 
+/**
+ * GSettingsBindSetMapping:
+ * @value: a #GValue containing the property value to map
+ * @expected_type: the #GVariantType to create
+ * @user_data: user data that was specified when the binding was created
+ * @returns: a new #GVariant holding the data from @value,
+ *     or %NULL in case of an error
+ *
+ * The type for the function that is used to convert an object property
+ * value to a #GVariant for storing it in #GSettings.
+ */
 typedef GVariant *    (*GSettingsBindSetMapping)                        (const GValue       *value,
                                                                          const GVariantType *expected_type,
                                                                          gpointer            user_data);
 
+/**
+ * GSettingsBindGetMapping:
+ * @value: return location for the property value
+ * @variant: the #GVariant
+ * @user_data: user data that was specified when the binding was created
+ * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
+ *
+ * The type for the function that is used to convert from #GSettings to
+ * an object property. The @value is already initialized to hold values
+ * of the appropriate type.
+ */
 typedef gboolean      (*GSettingsBindGetMapping)                        (GValue             *value,
                                                                          GVariant           *variant,
                                                                          gpointer            user_data);
 
+/**
+ * GSettingsBindFlags:
+ * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
+ * @G_SETTINGS_BIND_GET: Update the #GObject property when the #GSettings key changes
+ * @G_SETTINGS_BIND_SET: Update the #GSettings key when the #GObject property changes
+ * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to #GSettings writability
+ *
+ * Flags used when creating a binding. These flags determine in which
+ * direction the binding works. The default is to synchronize in both
+ * directions.
+ */
 typedef enum
 {
   G_SETTINGS_BIND_DEFAULT,