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
This commit is contained in:
Ryan Lortie 2013-10-27 17:03:04 -07:00
parent c0865fbaf2
commit bcb030a474
6 changed files with 208 additions and 112 deletions

View File

@ -2409,10 +2409,17 @@ g_settings_schema_get_path
<SUBSECTION> <SUBSECTION>
GSettingsSchemaKey GSettingsSchemaKey
g_settings_schema_has_key
g_settings_schema_get_key g_settings_schema_get_key
g_settings_schema_key_ref g_settings_schema_key_ref
g_settings_schema_key_unref 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> <SUBSECTION>
g_settings_schema_key_get_summary g_settings_schema_key_get_summary
g_settings_schema_key_get_description g_settings_schema_key_get_description

View File

@ -2315,80 +2315,22 @@ g_settings_list_children (GSettings *settings)
* *
* Queries the range of a key. * 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 * Since: 2.28
*
* Deprecated:2.40:Use g_settings_schema_key_get_range() instead.
**/ **/
GVariant * GVariant *
g_settings_get_range (GSettings *settings, g_settings_get_range (GSettings *settings,
const gchar *key) const gchar *key)
{ {
GSettingsSchemaKey skey; GSettingsSchemaKey skey;
const gchar *type;
GVariant *range; GVariant *range;
g_settings_schema_key_init (&skey, settings->priv->schema, key); 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); 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 * Checks if the given @value is of the correct type and within the
* permitted range for @key. * 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 * Returns: %TRUE if @value is valid for @key
* *
* Since: 2.28 * Since: 2.28
*
* Deprecated:2.40:Use g_settings_schema_key_range_check() instead.
**/ **/
gboolean gboolean
g_settings_range_check (GSettings *settings, g_settings_range_check (GSettings *settings,
@ -2420,8 +2357,7 @@ g_settings_range_check (GSettings *settings,
gboolean good; gboolean good;
g_settings_schema_key_init (&skey, settings->priv->schema, key); 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); g_settings_schema_key_clear (&skey);
return good; return good;
@ -3074,7 +3010,7 @@ g_settings_action_get_state_hint (GAction *action)
GSettingsAction *gsa = (GSettingsAction *) action; GSettingsAction *gsa = (GSettingsAction *) action;
/* no point in reimplementing this... */ /* 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 static void

View File

@ -96,10 +96,10 @@ GLIB_AVAILABLE_IN_ALL
gchar ** g_settings_list_children (GSettings *settings); gchar ** g_settings_list_children (GSettings *settings);
GLIB_AVAILABLE_IN_ALL GLIB_AVAILABLE_IN_ALL
gchar ** g_settings_list_keys (GSettings *settings); 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, GVariant * g_settings_get_range (GSettings *settings,
const gchar *key); 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, gboolean g_settings_range_check (GSettings *settings,
const gchar *key, const gchar *key,
GVariant *value); GVariant *value);

View File

@ -46,8 +46,6 @@ struct _GSettingsSchemaKey
const gchar * g_settings_schema_get_gettext_domain (GSettingsSchema *schema); const gchar * g_settings_schema_get_gettext_domain (GSettingsSchema *schema);
GVariantIter * g_settings_schema_get_value (GSettingsSchema *schema, GVariantIter * g_settings_schema_get_value (GSettingsSchema *schema,
const gchar *key); const gchar *key);
gboolean g_settings_schema_has_key (GSettingsSchema *schema,
const gchar *key);
const GQuark * g_settings_schema_list (GSettingsSchema *schema, const GQuark * g_settings_schema_list (GSettingsSchema *schema,
gint *n_items); gint *n_items);
const gchar * g_settings_schema_get_string (GSettingsSchema *schema, 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); void g_settings_schema_key_clear (GSettingsSchemaKey *key);
gboolean g_settings_schema_key_type_check (GSettingsSchemaKey *key, gboolean g_settings_schema_key_type_check (GSettingsSchemaKey *key,
GVariant *value); GVariant *value);
gboolean g_settings_schema_key_range_check (GSettingsSchemaKey *key,
GVariant *value);
GVariant * g_settings_schema_key_range_fixup (GSettingsSchemaKey *key, GVariant * g_settings_schema_key_range_fixup (GSettingsSchemaKey *key,
GVariant *value); GVariant *value);
GVariant * g_settings_schema_key_get_translated_default (GSettingsSchemaKey *key); GVariant * g_settings_schema_key_get_translated_default (GSettingsSchemaKey *key);

View File

@ -984,6 +984,17 @@ g_settings_schema_get_gettext_domain (GSettingsSchema *schema)
return schema->gettext_domain; 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 gboolean
g_settings_schema_has_key (GSettingsSchema *schema, g_settings_schema_has_key (GSettingsSchema *schema,
const gchar *key) const gchar *key)
@ -1204,39 +1215,6 @@ g_settings_schema_key_type_check (GSettingsSchemaKey *key,
return g_variant_is_of_type (value, key->type); 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 * GVariant *
g_settings_schema_key_range_fixup (GSettingsSchemaKey *key, g_settings_schema_key_range_fixup (GSettingsSchemaKey *key,
GVariant *value) 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; return target ? g_variant_ref_sink (g_variant_new_string (target)) : NULL;
} }
GVariant * GVariant *
g_settings_schema_key_get_translated_default (GSettingsSchemaKey *key) 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; 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));
}

View File

@ -73,6 +73,9 @@ const gchar * g_settings_schema_get_path (GSettin
GLIB_AVAILABLE_IN_2_40 GLIB_AVAILABLE_IN_2_40
GSettingsSchemaKey * g_settings_schema_get_key (GSettingsSchema *schema, GSettingsSchemaKey * g_settings_schema_get_key (GSettingsSchema *schema,
const gchar *key); 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 ()) #define G_TYPE_SETTINGS_SCHEMA_KEY (g_settings_schema_key_get_type ())
GLIB_AVAILABLE_IN_2_40 GLIB_AVAILABLE_IN_2_40
@ -83,6 +86,16 @@ GSettingsSchemaKey * g_settings_schema_key_ref (GSettin
GLIB_AVAILABLE_IN_2_40 GLIB_AVAILABLE_IN_2_40
void g_settings_schema_key_unref (GSettingsSchemaKey *key); 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 GLIB_AVAILABLE_IN_2_40
const gchar * g_settings_schema_key_get_summary (GSettingsSchemaKey *key); const gchar * g_settings_schema_key_get_summary (GSettingsSchemaKey *key);
GLIB_AVAILABLE_IN_2_40 GLIB_AVAILABLE_IN_2_40