Settings

Object Hierarchy:

Description:

[ CCode ( type_id = "g_settings_get_type ()" ) ]
public class Settings : Object

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 [struct@GLib.HashTable] 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 [method@Gio.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 ‘[relocatable](relocatable-schemas)’, 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 [struct@GLib.Variant], and allows any [type@GLib.VariantType] 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 `<schemalist>` or `<schema>` elements and the category that is specified in the `l10n` attribute of the `<default>` element. The string which is translated includes all text in the `< default>` element, including any surrounding quotation marks.

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; use `time` for translatable date or time formats. A translation comment can be added as an XML comment immediately above the `< default>` element — 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 the `<default>` element to disambiguate multiple defaults which use the same string.

For example: ```xml  <default l10n='messages' context='Banned words'>['bad', 'words']< /default> ```

Translations of default values must remain syntactically valid serialized [struct@GLib.Variant]s (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`](glib-compile-schemas.html) 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`](glib-compile-schemas.html) 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 `<schema>` element). The convention for schema IDs is to use a dotted name, similar in style to a D-Bus bus name, e.g. `org.gnome.SessionManager`. In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name and schema ID should match. For schemas which deal with settings not associated with one named application, the ID should not use StudlyCaps, e.g. `org.gnome.font-rendering`.

In addition to [struct@GLib.Variant] types, keys can have types that have enumerated types. These can be described by a `<choice>`, `< enum>` or `<flags>` element, as seen in the second example below. The underlying type of such a key is string, but you can use [ method@Gio.Settings.get_enum], [method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags], [method@Gio.Settings.set_flags] access the numeric values corresponding to the string value of enum and flags keys.

An example for default value: ```xml <schemalist> <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">

<key name="greeting" type="s"> <default l10n="messages">"Hello, earthlings"</default> <summary>A greeting</summary > <description> Greeting of the invading martians </description> </key>

<key name="empty-string" type="s"> <default>""</default> <summary>Empty strings have to be provided in GVariant form </summary> </key>

</schema> </schemalist> ```

An example for ranges, choices and enumerated types: ```xml <schemalist>

<key name='enumerated-key' enum='org.gtk.Test.myenum'> <default>'first'</default> </key>

<key name='flags-key' flags='org.gtk.Test.myflags'> <default>["flag1","flag2"]</default> </key> </schema> < /schemalist> ```

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`]( glib-compile-schemas.html) 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 [ struct@GLib.Variant] 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 [class@GObject.Object] properties directly to settings, using [method@Gio.Settings.bind]. Once a [class@GObject.Object] property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between [class@GObject.Object] and [struct@GLib.Variant] 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

A relocatable schema is one with no `path` attribute specified on its `<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings` object can be instantiated for a relocatable schema, assigning a path to the instance. Paths passed to [ ctor@Gio.Settings.new_with_path] will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a dependency library.

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 `<child>` elements in the parent schema, e.g.: ```xml <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> <child name="main" schema="org.foo.MyApp.Window"/> </schema> ```

Build system integration

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)

GSETTINGS_RULES@ ```

No changes are needed to the build system to mark a schema XML file for translation. Assuming it sets the `gettext-domain` attribute, a schema may be marked for translation by adding it to `POTFILES.in`, assuming gettext 0.19 is in use (the preferred method for translation): ``` data/org.foo.MyApp.gschema.xml ```

Alternatively, if intltool 0.50.1 is in use: ``` [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml ```

GSettings will use gettext to look up translations for the `<summary>` and `<description>` elements, and also any `<default>` elements which have a `l10n` attribute set. Translations must not be included in the `.gschema.xml` file by the build system, for example by using intltool XML rules with a `.gschema.xml.in` template.

If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant `Makefile.am`: ``` gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h ```

`gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, which are specified in `gsettings_ENUM_FILES`. This will generate a `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included in `EXTRA_DIST`.

Example: GSettings:

Note:

Use glib-compile-schemas [directory] to compile the gschema.

Note:

Use Control-C to quit the program.

<schemalist>
	<schema id="org.example.glib-settings-schema-source" path="/org/example/my-app/" gettext-domain="my-app">

		<key name="greeting" type="s">
			<default l10n="messages">"Hello, earthlings"</default>
			<summary>A greeting</summary>
			<description>
				Greeting of the invading martians
			</description>
		</key>

		<key name="bottles-of-beer" type="i">
			<default>99</default>
			<summary>Bottles of beer</summary>
			<description>
				Number of bottles of beer on the wall
			</description>
		</key>

		<key name="lighting" type="b">
			<default>false</default>
			<summary>Is the light switched on?</summary>
			<description>
				State of an imaginary light switch.
			</description>
		</key>

	</schema>
</schemalist>

glib-compile-schemas .

public static int main (string[] args) {
	try {
		// Custom location:
		string settings_dir = Path.get_dirname (args[0]);
		SettingsSchemaSource sss = new SettingsSchemaSource.from_directory (settings_dir, null, false);
		SettingsSchema schema = sss.lookup ("org.example.glib-settings-schema-source", false);
		if (sss.lookup == null) {
			print ("ID not found.");
			return 0;
		}

		Settings settings = new Settings.full (schema, null, null);

		// Default location: (XDG_DATA_DIRS)
		// Settings settings = new Settings ("org.example.glib-settings-schema-source");



		// Output: ``Hello, earthlings``
		string greeting = settings.get_string ("greeting");
		print ("%s\n", greeting);

		// Output: ``99``
		int bottles = settings.get_int ("bottles-of-beer");
		print ("%d\n", bottles);

		// Output: ``false``
		bool lighting = settings.get_boolean ("lighting");
		print ("%s\n", lighting.to_string ());



		// Change notification for any key in the schema
		settings.changed.connect ((key) => {
			print ("Key '%s' changed\n", key);
		});

		// Change notification for a single key
		settings.changed["greeting"].connect (() => {
			print ("New greeting: %s\n", settings.get_string ("greeting"));
		});


		// Setting keys

		// Output:
		//  ``Key 'bottles-of-beer' changed``
		//  ``Key 'lighting' changed``
		//  ``Key 'greeting' changed``
		//  ``New greeting: hello, world``
		settings.set_int ("bottles-of-beer", bottles - 1);
		settings.set_boolean ("lighting", !lighting);
		settings.set_string ("greeting", "hello, world");


		print ("\nPlease start 'dconf-editor' and edit keys in /org/example/my-app/\n");
		new MainLoop ().run ();
	} catch (Error e) {
		print ("Error: %s\n", e.message);
	}
	return 0;
}

valac --pkg gio-2.0 GLib.Settings.vala

Namespace: GLib

Package: gio-2.0

Content:

Properties:

public SettingsBackend backend { owned get; construct; }
The name of the context that the settings are stored in.
public bool delay_apply { get; }
Whether the Settings object is in 'delay-apply' mode.
public bool has_unapplied { get; }
If this property is true, the Settings object has outstanding changes that will be applied when apply is called.
public string path { owned get; construct; }
The path within the backend where the settings are stored.
public string schema { owned get; construct; }
The name of the schema that describes the types of keys for this Settings object.
public string schema_id { owned get; construct; }
The name of the schema that describes the types of keys for this Settings object.
public SettingsSchema settings_schema { owned get; construct; }
The SettingsSchema describing the types of keys for this Settings object.

Static methods:

public static unowned string[] list_relocatable_schemas ()
Deprecated.
public static unowned string[] list_schemas ()
Deprecated.
public static void sync ()
Ensures that all pending operations are complete for the default backend.
public static void unbind (Object object, string property)
Removes an existing binding for property on object .

Creation methods:

public Settings (string schema_id)
Creates a new Settings object with the schema specified by schema_id.
public Settings.full (SettingsSchema schema, SettingsBackend? backend, string? path)
Creates a new Settings object with a given schema, backend and path.
public Settings.with_backend (string schema_id, SettingsBackend backend)
Creates a new Settings object with the schema specified by schema_id and a given SettingsBackend.
public Settings.with_backend_and_path (string schema_id, SettingsBackend backend, string path)
Creates a new Settings object with the schema specified by schema_id and a given SettingsBackend and path.
public Settings.with_path (string schema_id, string path)
Creates a new Settings object with the relocatable schema specified by schema_id and a given path.

Methods:

public void @get (string key, string format, ...)
Gets the value that is stored at key in this.
public bool @set (string key, string format, ...)
Sets key in this to value.
public void apply ()
Applies any changes that have been made to the settings.
public void bind (string key, Object object, string property, SettingsBindFlags flags)
Create a binding between the key in the this object and the property property of object.
public void bind_with_mapping (string key, Object object, string property, SettingsBindFlags flags, SettingsBindGetMappingShared get_mapping, SettingsBindSetMappingShared set_mapping, void* user_data, DestroyNotify? notify)
Create a binding between the key in the this object and the property property of object.
public void bind_writable (string key, Object object, string property, bool inverted)
Create a binding between the writability of key in the this object and the property property of object.
public Action create_action (string key)
Creates a Action corresponding to a given Settings key.
public void delay ()
Changes the Settings object into 'delay-apply' mode.
public bool get_boolean (string key)
Gets the value that is stored at key in this.
public Settings get_child (string name)
Creates a child settings object which has a base path of `base-path/name`, where `base-path` is the base path of this.
public Variant? get_default_value (string key)
Gets the "default value" of a key.
public double get_double (string key)
Gets the value that is stored at key in this.
public int get_enum (string key)
Gets the value that is stored in this for key and converts it to the enum value that it represents.
public uint get_flags (string key)
Gets the value that is stored in this for key and converts it to the flags value that it represents.
public bool get_has_unapplied ()
Returns whether the Settings object has any unapplied changes.
public int get_int (string key)
Gets the value that is stored at key in this.
public int64 get_int64 (string key)
Gets the value that is stored at key in this.
public void* get_mapped (string key, SettingsGetMapping mapping)
Gets the value that is stored at key in this, subject to application-level validation/mapping.
public Variant get_range (string key)
Queries the range of a key.
public string get_string (string key)
Gets the value that is stored at key in this.
public string[] get_strv (string key)
A convenience variant of @get for string arrays.
public uint get_uint (string key)
Gets the value that is stored at key in this.
public uint64 get_uint64 (string key)
Gets the value that is stored at key in this.
public Variant? get_user_value (string key)
Checks the "user value" of a key, if there is one.
public Variant get_value (string key)
Gets the value that is stored in this for key.
public bool is_writable (string name)
Finds out if a key can be written or not
public string[] list_children ()
Gets the list of children on this.
public string[] list_keys ()
Introspects the list of keys on this.
public bool range_check (string key, Variant value)
Checks if the given value is of the correct type and within the permitted range for key.
public void reset (string key)
Resets key to its default value.
public void revert ()
Reverts all non-applied changes to the settings.
public bool set_boolean (string key, bool value)
Sets key in this to value.
public bool set_double (string key, double value)
Sets key in this to value.
public bool set_enum (string key, int value)
Looks up the enumerated type nick for value and writes it to key, within this.
public bool set_flags (string key, uint value)
Looks up the flags type nicks for the bits specified by value, puts them in an array of strings and writes the array to key, within this.
public bool set_int (string key, int value)
Sets key in this to value.
public bool set_int64 (string key, int64 value)
Sets key in this to value.
public bool set_string (string key, string value)
Sets key in this to value.
public bool set_strv (string key, string[]? value)
Sets key in this to value.
public bool set_uint (string key, uint value)
Sets key in this to value.
public bool set_uint64 (string key, uint64 value)
Sets key in this to value.
public bool set_value (string key, Variant value)
Sets key in this to value.

Signals:

public virtual signal bool change_event (Quark[]? keys)
The "change-event" signal is emitted once per change event that affects this settings object.
public virtual signal void changed (string key)
The "changed" signal is emitted when a key has potentially changed.
public virtual signal bool writable_change_event (uint key)
The "writable-change-event" signal is emitted once per writability change event that affects this settings object.
public virtual signal void writable_changed (string key)
The "writable-changed" signal is emitted when the writability of a key has potentially changed.

Inherited Members:

All known members inherited from class GLib.Object