GSettingsSchemaKey: add introspection APIs

Add g_settings_schema_has_key() and _get_range(), _range_check(),
_get_value_type(), _get_default_value() methods on GSettingsSchemaKey.

Deprecate the equivalent APIs on GSettings.

https://bugzilla.gnome.org/show_bug.cgi?id=683017

docs/reference/gio/gio-sections.txt

@@ -2409,10 +2409,17 @@ g_settings_schema_get_path
 
 <SUBSECTION>
 GSettingsSchemaKey
+g_settings_schema_has_key
 g_settings_schema_get_key
 g_settings_schema_key_ref
 g_settings_schema_key_unref
 
+<SUBSECTION>
+g_settings_schema_key_get_value_type
+g_settings_schema_key_get_default_value
+g_settings_schema_key_get_range
+g_settings_schema_key_range_check
+
 <SUBSECTION>
 g_settings_schema_key_get_summary
 g_settings_schema_key_get_description

gio/gsettings.c

@@ -2315,80 +2315,22 @@ g_settings_list_children (GSettings *settings)
  *
  * Queries the range of a key.
  *
- * This function will return a #GVariant that fully describes the range
- * of values that are valid for @key.
- *
- * The type of #GVariant returned is <literal>(sv)</literal>.  The
- * string describes the type of range restriction in effect.  The type
- * and meaning of the value contained in the variant depends on the
- * string.
- *
- * If the string is <literal>'type'</literal> then the variant contains
- * an empty array.  The element type of that empty array is the expected
- * type of value and all values of that type are valid.
- *
- * If the string is <literal>'enum'</literal> then the variant contains
- * an array enumerating the possible values.  Each item in the array is
- * a possible valid value and no other values are valid.
- *
- * If the string is <literal>'flags'</literal> then the variant contains
- * an array.  Each item in the array is a value that may appear zero or
- * one times in an array to be used as the value for this key.  For
- * example, if the variant contained the array <literal>['x',
- * 'y']</literal> then the valid values for the key would be
- * <literal>[]</literal>, <literal>['x']</literal>,
- * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
- * <literal>['y', 'x']</literal>.
- *
- * Finally, if the string is <literal>'range'</literal> then the variant
- * contains a pair of like-typed values -- the minimum and maximum
- * permissible values for this key.
- *
- * This information should not be used by normal programs.  It is
- * considered to be a hint for introspection purposes.  Normal programs
- * should already know what is permitted by their own schema.  The
- * format may change in any way in the future -- but particularly, new
- * forms may be added to the possibilities described above.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings.
- *
- * You should free the returned value with g_variant_unref() when it is
- * no longer needed.
- *
- * Returns: a #GVariant describing the range
- *
  * Since: 2.28
+ *
+ * Deprecated:2.40:Use g_settings_schema_key_get_range() instead.
  **/
 GVariant *
 g_settings_get_range (GSettings   *settings,
                       const gchar *key)
 {
   GSettingsSchemaKey skey;
-  const gchar *type;
   GVariant *range;
 
   g_settings_schema_key_init (&skey, settings->priv->schema, key);
-
+  range = g_settings_schema_key_get_range (&skey);
-  if (skey.minimum)
-    {
-      range = g_variant_new ("(**)", skey.minimum, skey.maximum);
-      type = "range";
-    }
-  else if (skey.strinfo)
-    {
-      range = strinfo_enumerate (skey.strinfo, skey.strinfo_length);
-      type = skey.is_flags ? "flags" : "enum";
-    }
-  else
-    {
-      range = g_variant_new_array (skey.type, NULL, 0);
-      type = "type";
-    }
-
   g_settings_schema_key_clear (&skey);
 
-  return g_variant_ref_sink (g_variant_new ("(sv)", type, range));
+  return range;
 }
 
 /**
@@ -2400,16 +2342,11 @@ g_settings_get_range (GSettings   *settings,
  * Checks if the given @value is of the correct type and within the
  * permitted range for @key.
  *
- * This API is not intended to be used by normal programs -- they should
- * already know what is permitted by their own schemas.  This API is
- * meant to be used by programs such as editors or commandline tools.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings.
- *
  * Returns: %TRUE if @value is valid for @key
  *
  * Since: 2.28
+ *
+ * Deprecated:2.40:Use g_settings_schema_key_range_check() instead.
  **/
 gboolean
 g_settings_range_check (GSettings   *settings,
@@ -2420,8 +2357,7 @@ g_settings_range_check (GSettings   *settings,
   gboolean good;
 
   g_settings_schema_key_init (&skey, settings->priv->schema, key);
-  good = g_settings_schema_key_type_check (&skey, value) &&
+  good = g_settings_schema_key_range_check (&skey, value);
-         g_settings_schema_key_range_check (&skey, value);
   g_settings_schema_key_clear (&skey);
 
   return good;
@@ -3074,7 +3010,7 @@ g_settings_action_get_state_hint (GAction *action)
   GSettingsAction *gsa = (GSettingsAction *) action;
 
   /* no point in reimplementing this... */
-  return g_settings_get_range (gsa->settings, gsa->key.name);
+  return g_settings_schema_key_get_range (&gsa->key);
 }
 
 static void

gio/gsettings.h

@@ -96,10 +96,10 @@ GLIB_AVAILABLE_IN_ALL
 gchar **                g_settings_list_children                        (GSettings          *settings);
 GLIB_AVAILABLE_IN_ALL
 gchar **                g_settings_list_keys                            (GSettings          *settings);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_key_get_range)
 GVariant *              g_settings_get_range                            (GSettings          *settings,
                                                                          const gchar        *key);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_key_range_check)
 gboolean                g_settings_range_check                          (GSettings          *settings,
                                                                          const gchar        *key,
                                                                          GVariant           *value);

gio/gsettingsschema-internal.h

@@ -46,8 +46,6 @@ struct _GSettingsSchemaKey
 const gchar *           g_settings_schema_get_gettext_domain            (GSettingsSchema  *schema);
 GVariantIter *          g_settings_schema_get_value                     (GSettingsSchema  *schema,
                                                                          const gchar      *key);
-gboolean                g_settings_schema_has_key                       (GSettingsSchema  *schema,
-                                                                         const gchar      *key);
 const GQuark *          g_settings_schema_list                          (GSettingsSchema  *schema,
                                                                          gint             *n_items);
 const gchar *           g_settings_schema_get_string                    (GSettingsSchema  *schema,
@@ -59,8 +57,6 @@ void                    g_settings_schema_key_init                      (GSettin
 void                    g_settings_schema_key_clear                     (GSettingsSchemaKey *key);
 gboolean                g_settings_schema_key_type_check                (GSettingsSchemaKey *key,
                                                                          GVariant           *value);
-gboolean                g_settings_schema_key_range_check               (GSettingsSchemaKey *key,
-                                                                         GVariant           *value);
 GVariant *              g_settings_schema_key_range_fixup               (GSettingsSchemaKey *key,
                                                                          GVariant           *value);
 GVariant *              g_settings_schema_key_get_translated_default    (GSettingsSchemaKey *key);

gio/gsettingsschema.c

@@ -984,6 +984,17 @@ g_settings_schema_get_gettext_domain (GSettingsSchema *schema)
   return schema->gettext_domain;
 }
 
+/**
+ * g_settings_schema_has_key:
+ * @schema: a #GSettingsSchema
+ * @name: the name of a key
+ *
+ * Checks if @schema has a key named @name.
+ *
+ * Returns: %TRUE if such a key exists
+ *
+ * Since: 2.40
+ **/
 gboolean
 g_settings_schema_has_key (GSettingsSchema *schema,
                            const gchar     *key)
@@ -1204,39 +1215,6 @@ g_settings_schema_key_type_check (GSettingsSchemaKey *key,
   return g_variant_is_of_type (value, key->type);
 }
 
-gboolean
-g_settings_schema_key_range_check (GSettingsSchemaKey *key,
-                                   GVariant           *value)
-{
-  if (key->minimum == NULL && key->strinfo == NULL)
-    return TRUE;
-
-  if (g_variant_is_container (value))
-    {
-      gboolean ok = TRUE;
-      GVariantIter iter;
-      GVariant *child;
-
-      g_variant_iter_init (&iter, value);
-      while (ok && (child = g_variant_iter_next_value (&iter)))
-        {
-          ok = g_settings_schema_key_range_check (key, child);
-          g_variant_unref (child);
-        }
-
-      return ok;
-    }
-
-  if (key->minimum)
-    {
-      return g_variant_compare (key->minimum, value) <= 0 &&
-             g_variant_compare (value, key->maximum) <= 0;
-    }
-
-  return strinfo_is_string_valid (key->strinfo, key->strinfo_length,
-                                  g_variant_get_string (value, NULL));
-}
-
 GVariant *
 g_settings_schema_key_range_fixup (GSettingsSchemaKey *key,
                                    GVariant           *value)
@@ -1283,7 +1261,6 @@ g_settings_schema_key_range_fixup (GSettingsSchemaKey *key,
   return target ? g_variant_ref_sink (g_variant_new_string (target)) : NULL;
 }
 
-
 GVariant *
 g_settings_schema_key_get_translated_default (GSettingsSchemaKey *key)
 {
@@ -1560,3 +1537,170 @@ g_settings_schema_key_get_description (GSettingsSchemaKey *key)
 
   return descriptions ? g_hash_table_lookup (descriptions, key->name) : NULL;
 }
+
+/**
+ * g_settings_schema_key_get_value_type:
+ * @key: a #GSettingsSchemaKey
+ *
+ * Gets the #GVariantType of @key.
+ *
+ * Returns: (transfer none): the type of @key
+ *
+ * Since: 2.40
+ **/
+const GVariantType *
+g_settings_schema_key_get_value_type (GSettingsSchemaKey *key)
+{
+  g_return_val_if_fail (key, NULL);
+
+  return key->type;
+}
+
+/**
+ * g_settings_schema_key_get_default_value:
+ * @key: a #GSettingsSchemaKey
+ *
+ * Gets the default value for @key.
+ *
+ * Note that this is the default value according to the schema.  System
+ * administrator defaults and lockdown are not visible via this API.
+ *
+ * Returns: (transfer full): the default value for the key
+ *
+ * Since: 2.40
+ **/
+GVariant *
+g_settings_schema_key_get_default_value (GSettingsSchemaKey *key)
+{
+  GVariant *value;
+
+  g_return_val_if_fail (key, NULL);
+
+  value = g_settings_schema_key_get_translated_default (key);
+
+  if (!value)
+    value = g_variant_ref (key->default_value);
+
+  return value;
+}
+
+/**
+ * g_settings_schema_key_get_range:
+ * @key: a #GSettingsSchemaKey
+ *
+ * Queries the range of a key.
+ *
+ * This function will return a #GVariant that fully describes the range
+ * of values that are valid for @key.
+ *
+ * The type of #GVariant returned is <literal>(sv)</literal>.  The
+ * string describes the type of range restriction in effect.  The type
+ * and meaning of the value contained in the variant depends on the
+ * string.
+ *
+ * If the string is <literal>'type'</literal> then the variant contains
+ * an empty array.  The element type of that empty array is the expected
+ * type of value and all values of that type are valid.
+ *
+ * If the string is <literal>'enum'</literal> then the variant contains
+ * an array enumerating the possible values.  Each item in the array is
+ * a possible valid value and no other values are valid.
+ *
+ * If the string is <literal>'flags'</literal> then the variant contains
+ * an array.  Each item in the array is a value that may appear zero or
+ * one times in an array to be used as the value for this key.  For
+ * example, if the variant contained the array <literal>['x',
+ * 'y']</literal> then the valid values for the key would be
+ * <literal>[]</literal>, <literal>['x']</literal>,
+ * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
+ * <literal>['y', 'x']</literal>.
+ *
+ * Finally, if the string is <literal>'range'</literal> then the variant
+ * contains a pair of like-typed values -- the minimum and maximum
+ * permissible values for this key.
+ *
+ * This information should not be used by normal programs.  It is
+ * considered to be a hint for introspection purposes.  Normal programs
+ * should already know what is permitted by their own schema.  The
+ * format may change in any way in the future -- but particularly, new
+ * forms may be added to the possibilities described above.
+ *
+ * You should free the returned value with g_variant_unref() when it is
+ * no longer needed.
+ *
+ * Returns: (transfer full): a #GVariant describing the range
+ *
+ * Since: 2.40
+ **/
+GVariant *
+g_settings_schema_key_get_range (GSettingsSchemaKey *key)
+{
+  const gchar *type;
+  GVariant *range;
+
+  if (key->minimum)
+    {
+      range = g_variant_new ("(**)", key->minimum, key->maximum);
+      type = "range";
+    }
+  else if (key->strinfo)
+    {
+      range = strinfo_enumerate (key->strinfo, key->strinfo_length);
+      type = key->is_flags ? "flags" : "enum";
+    }
+  else
+    {
+      range = g_variant_new_array (key->type, NULL, 0);
+      type = "type";
+    }
+
+  return g_variant_ref_sink (g_variant_new ("(sv)", type, range));
+}
+
+/**
+ * g_settings_schema_key_range_check:
+ * @key: a #GSettingsSchemaKey
+ * @value: the value to check
+ *
+ * Checks if the given @value is of the correct type and within the
+ * permitted range for @key.
+ *
+ * It is a programmer error if @value is not of the correct type -- you
+ * must check for this first.
+ *
+ * Returns: %TRUE if @value is valid for @key
+ *
+ * Since: 2.40
+ **/
+gboolean
+g_settings_schema_key_range_check (GSettingsSchemaKey *key,
+                                   GVariant           *value)
+{
+  if (key->minimum == NULL && key->strinfo == NULL)
+    return TRUE;
+
+  if (g_variant_is_container (value))
+    {
+      gboolean ok = TRUE;
+      GVariantIter iter;
+      GVariant *child;
+
+      g_variant_iter_init (&iter, value);
+      while (ok && (child = g_variant_iter_next_value (&iter)))
+        {
+          ok = g_settings_schema_key_range_check (key, child);
+          g_variant_unref (child);
+        }
+
+      return ok;
+    }
+
+  if (key->minimum)
+    {
+      return g_variant_compare (key->minimum, value) <= 0 &&
+             g_variant_compare (value, key->maximum) <= 0;
+    }
+
+  return strinfo_is_string_valid (key->strinfo, key->strinfo_length,
+                                  g_variant_get_string (value, NULL));
+}

gio/gsettingsschema.h

@@ -73,6 +73,9 @@ const gchar *           g_settings_schema_get_path                      (GSettin
 GLIB_AVAILABLE_IN_2_40
 GSettingsSchemaKey *    g_settings_schema_get_key                       (GSettingsSchema        *schema,
                                                                          const gchar            *key);
+GLIB_AVAILABLE_IN_2_40
+gboolean                g_settings_schema_has_key                       (GSettingsSchema        *schema,
+                                                                         const gchar            *key);
 
 #define                 G_TYPE_SETTINGS_SCHEMA_KEY                      (g_settings_schema_key_get_type ())
 GLIB_AVAILABLE_IN_2_40
@@ -83,6 +86,16 @@ GSettingsSchemaKey *    g_settings_schema_key_ref                       (GSettin
 GLIB_AVAILABLE_IN_2_40
 void                    g_settings_schema_key_unref                     (GSettingsSchemaKey     *key);
 
+GLIB_AVAILABLE_IN_2_40
+const GVariantType *    g_settings_schema_key_get_value_type            (GSettingsSchemaKey     *key);
+GLIB_AVAILABLE_IN_2_40
+GVariant *              g_settings_schema_key_get_default_value         (GSettingsSchemaKey     *key);
+GLIB_AVAILABLE_IN_2_40
+GVariant *              g_settings_schema_key_get_range                 (GSettingsSchemaKey     *key);
+GLIB_AVAILABLE_IN_2_40
+gboolean                g_settings_schema_key_range_check               (GSettingsSchemaKey     *key,
+                                                                         GVariant               *value);
+
 GLIB_AVAILABLE_IN_2_40
 const gchar *           g_settings_schema_key_get_summary               (GSettingsSchemaKey     *key);
 GLIB_AVAILABLE_IN_2_40