Settings
The #GSettings class provides a convenient API for storing and retrieving application settings.
Reads and writes can be considered to be non-blocking. Reading settings with #GSettings is typically extremely fast: on approximately the same order of magnitude (but slower than) a #GHashTable lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service doesn't even need to be started in this case. For this reason, you should only ever modify #GSettings keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup -- for example, when setting the initial value of preferences widgets. The built-in g_settings_bind() functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets.
When creating a GSettings instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information.
Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be 'gsettings-relocatable', i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an 'account', and you want to be able to store a arbitrary number of accounts.
Paths must start with and end with a forward slash character ('/') and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". Paths should not start with "/apps/", "/desktop/" or "/system/" as they often did in GConf.
Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores values as #GVariant, and allows any #GVariantType for keys. Key names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes.
Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the gettext-domain
attribute of the l10n
attribute of the
The l10n
attribute must be set to messages
or time
, and sets the [locale category for
translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). The
messages
category should be used by default; usetime
for translatable date or time formats. A translation comment can be added as an XML comment immediately above theelement — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation context
attribute can be set on theelement to disambiguate multiple defaults which use the same string.
For example: |[
Translations of default values must remain syntactically valid serialized #GVariants (e.g. retaining any surrounding quotation marks) or runtime errors will occur.
GSettings uses schemas in a compact binary form that is created by the glib-compile-schemas utility. The input is a schema description in an XML format.
A DTD for the gschema XML format can be found here: gschema.dtd
The glib-compile-schemas tool expects schema files to have the extension .gschema.xml
.
At runtime, schemas are identified by their id (as specified in the id attribute of the
In addition to #GVariant types, keys can have types that have enumerated types. These can be described by a
An example for default value: |[
"Hello, earthlings" A greeting
Greeting of the invading martians
(20,30) "" Empty strings have to be provided in GVariant form
An example for ranges, choices and enumerated types: |[
10 'Joe' 'first' ["flag1","flag2"]
Vendor overrides
Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, glib-compile-schemas reads so-called vendor override' files. These are keyfiles in the same directory as the XML schema sources which can override default values. The schema id serves as the group name in the key file, and the values are expected in serialized GVariant form, as in the following example: |[ org.gtk.Example key1='string' key2=1.5 ]|
glib-compile-schemas expects schema files to have the extension .gschema.override
.
Binding
A very convenient feature of GSettings lets you bind #GObject properties directly to settings, using g_settings_bind(). Once a GObject property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between GObject and GVariant types, and preventing infinite cycles.
This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings looks for a boolean property with the name "sensitivity" and automatically binds it to the writability of the bound setting. If this 'magic' gets in the way, it can be suppressed with the %G_SETTINGS_BIND_NO_SENSITIVITY flag.
Relocatable schemas # {#gsettings-relocatable}
A relocatable schema is one with no path
attribute specified on its
For example, a relocatable schema could be used to store geometry information for different windows in an application. If the schema ID was org.foo.MyApp.Window
, it could be instantiated for paths /org/foo/MyApp/main/
, /org/foo/MyApp/document-1/
, /org/foo/MyApp/document-2/
, etc. If any of the paths are well-known they can be specified as
Build system integration # {#gsettings-build-system}
GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your configure.ac
: |
GLIB_GSETTINGS
|
In the appropriate Makefile.am
, use the following snippet to compile and install the named schema: |[ gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS)
Constructors
Creates a new #GSettings object with the schema specified by
Creates a new #GSettings object with a given schema, backend and path.
Creates a new #GSettings object with the schema specified by
Creates a new #GSettings object with the schema specified by
Creates a new #GSettings object with the relocatable schema specified by @schema_id and a given path.
Properties
Functions
Create a binding between the @key in the @settings object and the property @property of @object.
Create a binding between the writability of @key in the
The "changed" signal is emitted when a key has potentially changed. You should call one of the g_settings_get() calls to check the new value.
The "writable-changed" signal is emitted when the writability of a key has potentially changed. You should call g_settings_is_writable() in order to determine the new status.
The "writable-change-event" signal is emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the "writable-changed" signal. For most use cases it is more appropriate to use the "writable-changed" signal.
Creates a #GAction corresponding to a given #GSettings key.
Gets the value that is stored at @key in @settings.
Gets the "default value" of a key.
Returns whether the #GSettings object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode.
Checks the "user value" of a key, if there is one.
Finds out if a key can be written or not
Gets the list of children on @settings.
Checks if the given @value is of the correct type and within the permitted range for @key.
Sets @key in @settings to @value.