GI.Gio.Structs.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:

C code

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:

C code

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

Since: 2.32

Exported types

newtype SettingsSchema

Memory-managed wrapper type.

Constructors

SettingsSchema (ManagedPtr SettingsSchema)

Instances

Eq SettingsSchema

Defined in GI.Gio.Structs.SettingsSchema

Methods

(==) :: SettingsSchema -> SettingsSchema -> Bool

(/=) :: SettingsSchema -> SettingsSchema -> Bool

BoxedObject SettingsSchema

Defined in GI.Gio.Structs.SettingsSchema

Methods

boxedType :: SettingsSchema -> IO GType

IsGValue SettingsSchema

Convert SettingsSchema to and from GValue with toGValue and fromGValue.

Defined in GI.Gio.Structs.SettingsSchema

Methods

toGValue :: SettingsSchema -> IO GValue

fromGValue :: GValue -> IO SettingsSchema

noSettingsSchema :: Maybe SettingsSchema

A convenience alias for Nothing :: Maybe SettingsSchema.

Methods

Overloaded methods

getId

settingsSchemaGetId

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m Text

Returns: the ID

Get the ID of schema.

getKey

settingsSchemaGetKey

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> Text

name: the name of a key

-> m SettingsSchemaKey

Returns: the SettingsSchemaKey for name

Gets the key named name from schema.

It is a programmer error to request a key that does not exist. See settingsSchemaListKeys.

Since: 2.40

getPath

settingsSchemaGetPath

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m Text

Returns: the path of the schema, or Nothing

Gets the path associated with schema, or Nothing.

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 threfore describe multiple sets of keys at different locations. For relocatable schemas, this function will return Nothing.

Since: 2.32

hasKey

settingsSchemaHasKey

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> Text

name: the name of a key

-> m Bool

Returns: True if such a key exists

Checks if schema has a key named name.

Since: 2.40

listChildren

settingsSchemaListChildren

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m [Text]

Returns: a list of the children on settings

Gets the list of children in schema.

You should free the return value with strfreev when you are done with it.

Since: 2.44

listKeys

settingsSchemaListKeys

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m [Text]

Returns: a list of the keys on 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.

Since: 2.46

ref

settingsSchemaRef

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m SettingsSchema

Returns: a new reference to schema

Increase the reference count of schema, returning a new reference.

Since: 2.32

unref

settingsSchemaUnref

Arguments

:: (HasCallStack, MonadIO m)

=> SettingsSchema

schema: a SettingsSchema

-> m ()

Decrease the reference count of schema, possibly freeing it.

Since: 2.32