From bcb030a4745d9d88a6150146a37e732a5c7c5d4f Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 27 Oct 2013 17:03:04 -0700 Subject: [PATCH] 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 | 7 + gio/gsettings.c | 80 ++--------- gio/gsettings.h | 4 +- gio/gsettingsschema-internal.h | 4 - gio/gsettingsschema.c | 212 +++++++++++++++++++++++----- gio/gsettingsschema.h | 13 ++ 6 files changed, 208 insertions(+), 112 deletions(-) diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt index 5ed836bc4..67afe3ef9 100644 --- a/docs/reference/gio/gio-sections.txt +++ b/docs/reference/gio/gio-sections.txt @@ -2409,10 +2409,17 @@ g_settings_schema_get_path GSettingsSchemaKey +g_settings_schema_has_key g_settings_schema_get_key g_settings_schema_key_ref g_settings_schema_key_unref + +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 + g_settings_schema_key_get_summary g_settings_schema_key_get_description diff --git a/gio/gsettings.c b/gio/gsettings.c index dca65d90f..49b199229 100644 --- a/gio/gsettings.c +++ b/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 (sv). 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 'type' 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 'enum' 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 'flags' 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 ['x', - * 'y'] then the valid values for the key would be - * [], ['x'], - * ['y'], ['x', 'y'] and - * ['y', 'x']. - * - * Finally, if the string is 'range' 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); - - 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"; - } - + range = g_settings_schema_key_get_range (&skey); 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) && - g_settings_schema_key_range_check (&skey, value); + good = 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 diff --git a/gio/gsettings.h b/gio/gsettings.h index 7cb26fd01..cf3607a26 100644 --- a/gio/gsettings.h +++ b/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); diff --git a/gio/gsettingsschema-internal.h b/gio/gsettingsschema-internal.h index d701f5ce2..9745a2b01 100644 --- a/gio/gsettingsschema-internal.h +++ b/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); diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c index fa9f9da07..33ecd72ae 100644 --- a/gio/gsettingsschema.c +++ b/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 (sv). 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 'type' 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 'enum' 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 'flags' 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 ['x', + * 'y'] then the valid values for the key would be + * [], ['x'], + * ['y'], ['x', 'y'] and + * ['y', 'x']. + * + * Finally, if the string is 'range' 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)); +} diff --git a/gio/gsettingsschema.h b/gio/gsettingsschema.h index 229ed0d48..90ef37a2a 100644 --- a/gio/gsettingsschema.h +++ b/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