Description
The GSettingsSchemaSource and GSettingsSchema APIs provide a
mechanism for advanced control over the loading of schemas and a
mechanism for introspecting their content.
Plugin loading systems that wish to provide plugins a way to access
settings face the problem of how to make the schemas for these
settings visible to GSettings. Typically, a plugin will want to ship
the schema along with itself and it won't be installed into the
standard system directories for schemas.
GSettingsSchemaSource provides a mechanism for dealing with this by
allowing the creation of a new 'schema source' from which schemas can
be acquired. This schema source can then become part of the metadata
associated with the plugin and queried whenever the plugin requires
access to some settings.
Consider the following example:
The code above shows how hooks should be added to the code that
initialises (or enables) the plugin to create the schema source and
how an API can be added to the plugin system to provide a convenient
way for the plugin to access its settings, using the schemas that it
ships.
From the standpoint of the plugin, it would need to ensure that it
ships a gschemas.compiled file as part of itself, and then simply do
the following:
It's also possible that the plugin system expects the schema source
files (ie: .gschema.xml files) instead of a gschemas.compiled file.
In that case, the plugin loading system must compile the schemas for
itself before attempting to create the settings source.
Functions
g_settings_schema_source_get_default ()
GSettingsSchemaSource *
g_settings_schema_source_get_default (void);
Gets the default system schema source.
This function is not required for normal uses of GSettings but it
may be useful to authors of plugin management systems or to those who
want to introspect the content of schemas.
If no schemas are installed, NULL will be returned.
The returned source may actually consist of multiple schema sources
from different directories, depending on which directories were given
in XDG_DATA_DIRS and GSETTINGS_SCHEMA_DIR. For this reason, all
lookups performed against the default source should probably be done
recursively.
Returns
the default schema source.
[transfer none][nullable]
Since: 2.32
g_settings_schema_source_ref ()
GSettingsSchemaSource *
g_settings_schema_source_ref (GSettingsSchemaSource *source);
Increase the reference count of source
, returning a new reference.
Returns
a new reference to source
Since: 2.32
g_settings_schema_source_unref ()
void
g_settings_schema_source_unref (GSettingsSchemaSource *source);
Decrease the reference count of source
, possibly freeing it.
Since: 2.32
g_settings_schema_source_new_from_directory ()
GSettingsSchemaSource *
g_settings_schema_source_new_from_directory
(const gchar *directory,
GSettingsSchemaSource *parent,
gboolean trusted,
GError **error);
Attempts to create a new schema source corresponding to the contents
of the given directory.
This function is not required for normal uses of GSettings but it
may be useful to authors of plugin management systems.
The directory should contain a file called gschemas.compiled as
produced by the glib-compile-schemas tool.
If trusted
is TRUE then gschemas.compiled is trusted not to be
corrupted. This assumption has a performance advantage, but can result
in crashes or inconsistent behaviour in the case of a corrupted file.
Generally, you should set trusted
to TRUE for files installed by the
system and to FALSE for files in the home directory.
In either case, an empty file or some types of corruption in the file will
result in G_FILE_ERROR_INVAL being returned.
If parent
is non-NULL then there are two effects.
First, if g_settings_schema_source_lookup() is called with the
recursive
flag set to TRUE and the schema can not be found in the
source, the lookup will recurse to the parent.
Second, any references to other schemas specified within this
source (ie: child or extends) references may be resolved
from the parent
.
For this second reason, except in very unusual situations, the
parent
should probably be given as the default schema source, as
returned by g_settings_schema_source_get_default().
Since: 2.32
g_settings_schema_source_list_schemas ()
void
g_settings_schema_source_list_schemas (GSettingsSchemaSource *source,
gboolean recursive,
gchar ***non_relocatable,
gchar ***relocatable);
Lists the schemas in a given source.
If recursive
is TRUE then include parent sources. If FALSE then
only include the schemas from one source (ie: one directory). You
probably want TRUE.
Non-relocatable schemas are those for which you can call
g_settings_new(). Relocatable schemas are those for which you must
use g_settings_new_with_path().
Do not call this function from normal programs. This is designed for
use by database editors, commandline tools, etc.
Since: 2.40
g_settings_schema_source_lookup ()
GSettingsSchema *
g_settings_schema_source_lookup (GSettingsSchemaSource *source,
const gchar *schema_id,
gboolean recursive);
Looks up a schema with the identifier schema_id
in source
.
This function is not required for normal uses of GSettings but it
may be useful to authors of plugin management systems or to those who
want to introspect the content of schemas.
If the schema isn't found directly in source
and recursive
is TRUE
then the parent sources will also be checked.
If the schema isn't found, NULL is returned.
Since: 2.32
g_settings_schema_ref ()
GSettingsSchema *
g_settings_schema_ref (GSettingsSchema *schema);
Increase the reference count of schema
, returning a new reference.
Returns
a new reference to schema
Since: 2.32
g_settings_schema_unref ()
void
g_settings_schema_unref (GSettingsSchema *schema);
Decrease the reference count of schema
, possibly freeing it.
Since: 2.32
g_settings_schema_get_id ()
const gchar *
g_settings_schema_get_id (GSettingsSchema *schema);
Get the ID of schema
.
Returns
the ID.
[transfer none]
g_settings_schema_get_path ()
const gchar *
g_settings_schema_get_path (GSettingsSchema *schema);
Gets the path associated with schema
, or NULL.
Schemas may be single-instance or relocatable. Single-instance
schemas correspond to exactly one set of keys in the backend
database: those located at the path returned by this function.
Relocatable schemas can be referenced by other schemas and can
therefore describe multiple sets of keys at different locations. For
relocatable schemas, this function will return NULL.
Returns
the path of the schema, or NULL.
[transfer none]
Since: 2.32
g_settings_schema_has_key ()
gboolean
g_settings_schema_has_key (GSettingsSchema *schema,
const gchar *name);
Checks if schema
has a key named name
.
Returns
TRUE if such a key exists
Since: 2.40
g_settings_schema_key_ref ()
GSettingsSchemaKey *
g_settings_schema_key_ref (GSettingsSchemaKey *key);
Increase the reference count of key
, returning a new reference.
Returns
a new reference to key
Since: 2.40
g_settings_schema_key_unref ()
void
g_settings_schema_key_unref (GSettingsSchemaKey *key);
Decrease the reference count of key
, possibly freeing it.
Since: 2.40
g_settings_schema_list_children ()
gchar **
g_settings_schema_list_children (GSettingsSchema *schema);
Gets the list of children in schema
.
You should free the return value with g_strfreev() when you are done
with it.
Returns
a list of the children on
settings
, in no defined order.
[transfer full][element-type utf8]
Since: 2.44
g_settings_schema_list_keys ()
gchar **
g_settings_schema_list_keys (GSettingsSchema *schema);
Introspects the list of keys on schema
.
You should probably not be calling this function from "normal" code
(since you should already know what keys are in your schema). This
function is intended for introspection reasons.
Returns
a list of the keys on
schema
, in no defined order.
[transfer full][element-type utf8]
Since: 2.46
g_settings_schema_key_get_value_type ()
const GVariantType *
g_settings_schema_key_get_value_type (GSettingsSchemaKey *key);
Gets the GVariantType of key
.
Returns
the type of key
.
[transfer none]
Since: 2.40
g_settings_schema_key_get_default_value ()
GVariant *
g_settings_schema_key_get_default_value
(GSettingsSchemaKey *key);
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
the default value for the key.
[transfer full]
Since: 2.40
g_settings_schema_key_get_range ()
GVariant *
g_settings_schema_key_get_range (GSettingsSchemaKey *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 (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
a GVariant describing the range.
[transfer full]
Since: 2.40
g_settings_schema_key_range_check ()
gboolean
g_settings_schema_key_range_check (GSettingsSchemaKey *key,
GVariant *value);
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
g_settings_schema_key_get_name ()
const gchar *
g_settings_schema_key_get_name (GSettingsSchemaKey *key);
Gets the name of key
.
Returns
the name of key
.
Since: 2.44
g_settings_schema_key_get_summary ()
const gchar *
g_settings_schema_key_get_summary (GSettingsSchemaKey *key);
Gets the summary for key
.
If no summary has been provided in the schema for key
, returns
NULL.
The summary is a short description of the purpose of the key; usually
one short sentence. Summaries can be translated and the value
returned from this function is is the current locale.
This function is slow. The summary and description information for
the schemas is not stored in the compiled schema database so this
function has to parse all of the source XML files in the schema
directory.
Returns
the summary for key
, or NULL
Since: 2.34
g_settings_schema_key_get_description ()
const gchar *
g_settings_schema_key_get_description (GSettingsSchemaKey *key);
Gets the description for key
.
If no description has been provided in the schema for key
, returns
NULL.
The description can be one sentence to several paragraphs in length.
Paragraphs are delimited with a double newline. Descriptions can be
translated and the value returned from this function is is the
current locale.
This function is slow. The summary and description information for
the schemas is not stored in the compiled schema database so this
function has to parse all of the source XML files in the schema
directory.
Returns
the description for key
, or NULL
Since: 2.34