Package org.gnome.gio

Class SettingsSchema

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gio.SettingsSchema

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class SettingsSchema
extends ProxyInstance

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

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:

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:

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

Constructor Summary

Constructors

Constructor	Description
SettingsSchema(MemorySegment address)	Create a SettingsSchema proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
String	getId()	Get the ID of this SettingsSchema.
SettingsSchemaKey	getKey(String name)	Gets the key named name from this SettingsSchema.
String	getPath()	Gets the path associated with this SettingsSchema, or null.
static Type	getType()	Get the GType of the SettingsSchema class
boolean	hasKey(String name)	Checks if this SettingsSchema has a key named name.
String[]	listChildren()	Gets the list of children in this SettingsSchema.
String[]	listKeys()	Introspects the list of keys on this SettingsSchema.
SettingsSchema	ref()	Increase the reference count of this SettingsSchema, returning a new reference.
void	unref()	Decrease the reference count of this SettingsSchema, possibly freeing it.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SettingsSchema

public SettingsSchema(MemorySegment address)

Create a SettingsSchema proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the SettingsSchema class

Returns:

the GType

getId

public String getId()

Get the ID of this SettingsSchema.

Returns:

the ID

getKey

public SettingsSchemaKey getKey(String name)

Gets the key named name from this SettingsSchema.

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

Parameters:

name - the name of a key

Returns:

the GSettingsSchemaKey for name

getPath

public String getPath()

Gets the path associated with this SettingsSchema, 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

hasKey

public boolean hasKey(String name)

Checks if this SettingsSchema has a key named name.

Parameters:

name - the name of a key

Returns:

true if such a key exists

listChildren

public String[] listChildren()

Gets the list of children in this SettingsSchema.

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

listKeys

public String[] listKeys()

Introspects the list of keys on this SettingsSchema.

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

ref

public SettingsSchema ref()

Increase the reference count of this SettingsSchema, returning a new reference.

Returns:

a new reference to this SettingsSchema

unref

public void unref()

Decrease the reference count of this SettingsSchema, possibly freeing it.