Struct gio::SettingsSchema

pub struct SettingsSchema(_);

The SettingsSchemaSource and SettingsSchema 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.

SettingsSchemaSource 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 following code is in C ⚠️

typedef struct
{
   ...
   GSettingsSchemaSource *schema_source;
   ...
} Plugin;

Plugin *
initialise_plugin (const gchar *dir)
{
  Plugin *plugin;

  ...

  plugin->schema_source =
    g_settings_schema_source_new_from_directory (dir,
      g_settings_schema_source_get_default (), FALSE, NULL);

  ...

  return plugin;
}

...

GSettings *
plugin_get_settings (Plugin      *plugin,
                     const gchar *schema_id)
{
  GSettingsSchema *schema;

  if (schema_id == NULL)
    schema_id = plugin->identifier;

  schema = g_settings_schema_source_lookup (plugin->schema_source,
                                            schema_id, FALSE);

  if (schema == NULL)
    {
      ... disable the plugin or abort, etc ...
    }

  return g_settings_new_full (schema, NULL, NULL);
}

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:

⚠️ The following code is in C ⚠️

{
  GSettings *settings;
  gint some_value;

  settings = plugin_get_settings (self, NULL);
  some_value = g_settings_get_int (settings, "some-value");
  ...
}

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.

Implementations

impl SettingsSchema

pub fn id(&self) -> GString

Get the ID of self.

Returns

the ID

pub fn key(&self, name: &str) -> SettingsSchemaKey

Gets the key named name from self.

It is a programmer error to request a key that does not exist. See list_keys().

name

the name of a key

Returns

the SettingsSchemaKey for name

pub fn path(&self) -> Option<GString>

Gets the path associated with self, or None.

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 None.

Returns

the path of the schema, or None

pub fn has_key(&self, name: &str) -> bool

Checks if self has a key named name.

name

the name of a key

Returns

true if such a key exists

pub fn list_children(&self) -> Vec<GString>

Gets the list of children in self.

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

pub fn list_keys(&self) -> Vec<GString>

Introspects the list of keys on self.

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 self, in no defined order

Trait Implementations

impl Clone for SettingsSchema

fn clone(&self) -> SettingsSchema

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SettingsSchema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for SettingsSchema

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for SettingsSchema

fn cmp(&self, other: &SettingsSchema) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<SettingsSchema> for SettingsSchema

fn eq(&self, other: &SettingsSchema) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &SettingsSchema) -> bool

This method tests for !=.

impl PartialOrd<SettingsSchema> for SettingsSchema

fn partial_cmp(&self, other: &SettingsSchema) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for SettingsSchema

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for SettingsSchema

impl StructuralEq for SettingsSchema

impl StructuralPartialEq for SettingsSchema