SettingsSchema

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:

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

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

...

plugin->schema_source = g_settings_new_schema_source_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:

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

class SettingsSchema {

protected

GSettingsSchema* gSettingsSchema;

protected

bool ownedRef;

GSettingsSchema* getSettingsSchemaStruct(bool transferOwnership);

void* getStruct();

this(GSettingsSchema* gSettingsSchema, bool ownedRef);

~this();

static GType getType();

string getId();

SettingsSchemaKey getKey(string name);

string getPath();

bool hasKey(string name);

string[] listChildren();

string[] listKeys();

SettingsSchema doref();

void unref();

}

Constructors

this this(GSettingsSchema* gSettingsSchema, bool ownedRef): Sets our main struct and passes it to the parent class.

Destructor

~this ~this(): Undocumented in source.

Members

Functions

doref SettingsSchema doref(): Increase the reference count of @schema, returning a new reference.
getId string getId(): Get the ID of @schema.
getKey SettingsSchemaKey getKey(string name): Gets the key named @name from @schema.
getPath string getPath(): Gets the path associated with @schema, or %NULL.
getSettingsSchemaStruct GSettingsSchema* getSettingsSchemaStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
hasKey bool hasKey(string name): Checks if @schema has a key named @name.
listChildren string[] listChildren(): Gets the list of children in @schema.
listKeys string[] listKeys(): Introspects the list of keys on @schema.
unref void unref(): Decrease the reference count of @schema, possibly freeing it.

Static functions

getType GType getType()

Variables

gSettingsSchema GSettingsSchema* gSettingsSchema;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.