[glibmm] Settings: Add get_user_value() and get_default_value().

[Murray Cumming <murrayc src gnome org>]

commit 2859d694d27b1b577d8d79690234344d67a47859
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri Apr 4 21:30:42 2014 +0200

    Settings: Add get_user_value() and get_default_value().

 gio/src/settings.ccg |   18 ++++++++++++++
 gio/src/settings.hg  |   63 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 0 deletions(-)
---
diff --git a/gio/src/settings.ccg b/gio/src/settings.ccg
index a32ad94..ca92f15 100644
--- a/gio/src/settings.ccg
+++ b/gio/src/settings.ccg
@@ -31,6 +31,24 @@ void Settings::get_value(const Glib::ustring& key, Glib::VariantBase& value) con
   value.init(g_value, false /* don't take a reference */);
 }
 
+bool Settings::get_user_value(const Glib::ustring& key, Glib::VariantBase& value) const
+{
+  GVariant* const g_value = g_settings_get_user_value(const_cast<GSettings*>(gobj()), key.c_str());
+  if(!g_value)
+    return false;
+
+  value.init(g_value, false /* don't take a reference */);
+  return true;
+}
+
+void Settings::get_default_value(const Glib::ustring& key, Glib::VariantBase& value) const
+{
+  GVariant* const g_value = g_settings_get_default_value(const_cast<GSettings*>(gobj()), key.c_str());
+  if(!g_value)
+    return;
+
+  value.init(g_value, false /* don't take a reference */);
+}
 void Settings::bind(const Glib::ustring& key,
                     const Glib::PropertyProxy_Base& property_proxy,
                     SettingsBindFlags flags)
diff --git a/gio/src/settings.hg b/gio/src/settings.hg
index 74554fa..4e45cee 100644
--- a/gio/src/settings.hg
+++ b/gio/src/settings.hg
@@ -51,8 +51,10 @@ public:
   //TODO: Requires SettingsBackend: _WRAP_CREATE(const Glib::ustring& schema, const 
Glib::RefPtr<SettingsBackend>& backend)
   //TODO: Requires SettingsBackend: _WRAP_CREATE(const Glib::ustring& schema, const 
Glib::RefPtr<SettingsBackend>& backend, const Glib::ustring& path)
 
+  //TODO: Rename these to get/set_*_value_variant() and add templated get/set_*_value() methods as elsewhere?
   _WRAP_METHOD(bool set_value(const Glib::ustring& key, const Glib::VariantBase& value),  
g_settings_set_value)
 
+
   /** Gets the value that is stored in the settings for a @a key.
    *
    * It is a programmer error to give a @a key that isn't contained in the
@@ -66,6 +68,67 @@ public:
   void get_value(const Glib::ustring& key, Glib::VariantBase& value) const;
   _IGNORE(g_settings_get_value)
 
+  //TODO: We've added a bool return to handle the NULL return value case,
+  //but maybe other get_value() methods can return NULLs too.
+
+  /** Checks the "user value" of a @a key, if there is one.
+   *
+   * The user value of a key is the last value that was set by the user.
+   *
+   * After calling reset() this function should always return
+   * false (assuming something is not wrong with the system
+   * configuration).
+   *
+   * It is possible that get_value() will return a different
+   * value than this method.  This can happen in the case that the user
+   * set a value for a key that was subsequently locked down by the system
+   * administrator -- this method will return the user's old value.
+   *
+   * This method may be useful for adding a "reset" option to a UI or
+   * for providing indication that a particular value has been changed.
+   *
+   * It is a programmer error to give a @a key that isn't contained in the
+   * schema for the settings.
+   *
+   * @param key The key to get the user value for.
+   * @param value A Variant of the expected type.
+   * @result true if a user value was found.
+   *
+   * @newin{2,40}
+   */
+  bool get_user_value(const Glib::ustring& key, Glib::VariantBase& value) const;
+  _IGNORE(g_settings_get_user_value)
+
+  /** Gets the "default value" of a key.
+   *
+   * This is the value that would be read if reset() were to be
+   * called on the key.
+   *
+   * Note that this may be a different value than returned by
+   * get_default_value() if the system administrator
+   * has provided a default value.
+   *
+   * Comparing the return values of get_default_value() and
+   * value() is not sufficient for determining if a value
+   * has been set because the user may have explicitly set the value to
+   * something that happens to be equal to the default.  The difference
+   * here is that if the default changes in the future, the user's key
+   * will still be set.
+   *
+   * This method may be useful for adding an indication to a UI of what
+   * the default value was before the user set it.
+   *
+   * It is a programmer error to give a @a key that isn't contained in the
+   * schema for the settings.
+   *
+   * @param key The key to get the default value for.
+   * @param value A Variant of the expected type.
+   *
+   * @newin{2,40}
+   */
+  void get_default_value(const Glib::ustring& key, Glib::VariantBase& value) const;
+  _IGNORE(g_settings_get_default_value)
+
   _WRAP_METHOD(int get_int(const Glib::ustring& key) const, g_settings_get_int)
   _WRAP_METHOD(void set_int(const Glib::ustring& key, int value), g_settings_set_int)
   _WRAP_METHOD(guint get_uint(const Glib::ustring& key) const, g_settings_get_uint)