gi-gio-2.0.35: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.Gio.Structs.SettingsSchema

Contents

- Exported types
- Methods
  - getId
  - getKey
  - getPath
  - hasKey
  - listChildren
  - listKeys
  - ref
  - unref

Description

The [struct`gio`.SettingsSchemaSource] 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.

struct`gio`.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

Synopsis

- newtype SettingsSchema = SettingsSchema (ManagedPtr SettingsSchema)
- settingsSchemaGetId :: (HasCallStack, MonadIO m) => SettingsSchema -> m Text
- settingsSchemaGetKey :: (HasCallStack, MonadIO m) => SettingsSchema -> Text -> m SettingsSchemaKey
- settingsSchemaGetPath :: (HasCallStack, MonadIO m) => SettingsSchema -> m (Maybe Text)
- settingsSchemaHasKey :: (HasCallStack, MonadIO m) => SettingsSchema -> Text -> m Bool
- settingsSchemaListChildren :: (HasCallStack, MonadIO m) => SettingsSchema -> m [Text]
- settingsSchemaListKeys :: (HasCallStack, MonadIO m) => SettingsSchema -> m [Text]
- settingsSchemaRef :: (HasCallStack, MonadIO m) => SettingsSchema -> m SettingsSchema
- settingsSchemaUnref :: (HasCallStack, MonadIO m) => SettingsSchema -> m ()

# Exported types

newtype SettingsSchema Source #

Memory-managed wrapper type.

Constructors

SettingsSchema (ManagedPtr SettingsSchema) |

#### Instances

Instances details

Eq SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema Methods (==) :: SettingsSchema -> SettingsSchema -> Bool Source # (/=) :: SettingsSchema -> SettingsSchema -> Bool Source #
GBoxed SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema
ManagedPtrNewtype SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema Methods toManagedPtr :: SettingsSchema -> ManagedPtr SettingsSchema Source #
TypedObject SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema Methods glibType :: IO GType Source #
HasParentTypes SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema
IsGValue (Maybe SettingsSchema) Source # | Convert `SettingsSchema` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Structs.SettingsSchema Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe SettingsSchema -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe SettingsSchema) Source #
type ParentTypes SettingsSchema Source # |
Instance details Defined in GI.Gio.Structs.SettingsSchema type ParentTypes SettingsSchema = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

hasKey, listChildren, listKeys, ref, unref.

#### Getters

getId, getKey, getPath.

#### Setters

None.

## getId

settingsSchemaGetId Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> SettingsSchema | `schema`: a `SettingsSchema`
-> m Text | Returns: the ID

Get the ID of `schema`.

## getKey

settingsSchemaGetKey Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> SettingsSchema | `schema`: a `SettingsSchema`
-> m (Maybe 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 therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return `Nothing`.

Since: 2.32

## hasKey

settingsSchemaHasKey Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> SettingsSchema | `schema`: a `SettingsSchema`
-> m [Text] | Returns: a list of the children on `settings`, in no defined order

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> SettingsSchema | `schema`: a `SettingsSchema`
-> m [Text] | Returns: a list of the keys on `schema`, in no defined order

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> SettingsSchema | `schema`: a `SettingsSchema`
-> m () |

Decrease the reference count of `schema`, possibly freeing it.

Since: 2.32