Guidelines/GSettings

From Apertis
Jump to: navigation, search

Contents

GSettings

GSettings is a GLib API for storing persistent application settings (but not large amounts of data or user documents). It is the successor to GConf, and is similar in use to the Windows Registry. GSettings is used by Apertis for application preferences and configuration data. Its main advantages over databases or configuration files are its support for structured data (using GVariant), and its fast reads. It has good integration with GObject, with powerful features such as binding to object properties with g_settings_bind().

Due to its tight integration with other GLib utilities, it should be used in preference to (e.g.) SQLite for configuration data (but not for user data or documents, or high volumes of data).

Summary

Schema design

GSettings uses compiled schemas, which describe the available settings and their types. A single schema should contain a group of related settings, such as the settings for a single application. Every setting used by an application must be in a schema, and that schema must be compiled and installed. This can be done using the @GSETTINGS_RULES@ automake macro provided by GLib.

Schemas should be named appropriately, using an Apertis namespace and a project-specific namespace, then the schema name, e.g. org.apertis.ProjectName.gschema.xml.

All schemas should be translatable, which allows for configuration key default values to differ for different locales. This can be useful for settings which are known to be different in different countries. For example, a setting specifying which is the first day of the week. Schemas are automatically marked as translatable if intltool 0.50.1 is in use, and the schema is listed in po/POTFILES.in as:

[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml

Schema installation

All schemas should be installed on the system. This is automatically handled by the @GSETTINGS_RULES@ automake macro, simply by listing the schema file in gsettings_SCHEMAS in Makefile.am:

gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
EXTRA_DIST = $(gsettings_SCHEMAS)
@GSETTINGS_RULES@

Note that the GLIB_GSETTINGS macro must have been used in configure.ac for this to work.

By installing schemas, there is no need to check for schema or key availability at run time, as all keys have default values provided by the schema. Calls to g_settings_list_schemas() and g_settings_list_keys() are almost always unnecessary except when using #Relocatable schemas. Instead, schema keys should be retrieved on the assumption that they exist, simply by calling (e.g.) g_settings_get_string() without any checks.

Relocatable schemas

GSettings has a feature called ‘relocatable schemas’ which is designed specifically for situations where an unknown set of applications need to use a common schema template — where one schema is used multiple times at different GSettings paths. Each path has an instance of the schema and all its keys, and represents the configuration for a single app.

In such specific situations, a single relocatable schema should be used rather than copying the schema for each application. g_settings_list_relocatable_schemas() should be used with g_settings_new_with_path() to instantiate the schema for each path.

See the GSettings documentation for more information.

Schema overrides

GSettings override files are designed for vendors to be able to override upstream-provided GSettings schema defaults, allowing for customisation of their distributions of software. If used, they should be added by the vendors using custom patches, and should not be added upstream in Apertis.

Debugging

The GSettings database for the current environment can be explored and modified using the gsettings command line tool. See gsettings --help for more information. Note that the tool needs to be run in the same environment as the application in order to see the same GSettings database.

External links

Personal tools
Namespaces

Variants
Actions
Navigation
Tools