Settings

Settings

Object Hierarchy:

Description:

public class Settings : Object

The Settings class provides a convenient API for storing and retrieving application settings.

Reads and writes can be considered to be non-blocking. Reading settings with Settings is typically extremely fast: on approximately the same order of magnitude (but slower than) a GenericSet 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 Settings 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 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 as fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be '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 Variant, and allows any 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 <key> element.

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 <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 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 example. The underlying type of such a key is string, but you can use get_enum, set_enum, get_flags, set_flags access the numeric values corresponding to the string value of enum and flags keys.

An example for default value:

<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="box" type="(ii)">
      <default>(20,30)</default>
    </key>

  </schema>
</schemalist>

An example for ranges, choices and enumerated types:

<schemalist>

  <enum id="org.gtk.Test.myenum">
    <value nick="first" value="1"/>
    <value nick="second" value="2"/>
  </enum>

  <flags id="org.gtk.Test.myflags">
    <value nick="flag1" value="1"/>
    <value nick="flag2" value="2"/>
    <value nick="flag3" value="4"/>
  </flags>

  <schema id="org.gtk.Test">

    <key name="key-with-range" type="i">
      <range min="1" max="100"/>
      <default>10</default>
    </key>

    <key name="key-with-choices" type="s">
      <choices>
        <choice value='Elisabeth'/>
        <choice value='Annabeth'/>
        <choice value='Joe'/>
      </choices>
      <aliases>
        <alias value='Anna' target='Annabeth'/>
        <alias value='Beth' target='Elisabeth'/>
      </aliases>
      <default>'Joe'</default>
    </key>

    <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 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 Object properties directly to settings, using 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 NO_SENSITIVITY flag.

Namespace: GLib

Package: gio-2.0

Content:

Properties:

public SettingsBackend backend { construct; owned get; }
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 { construct; owned get; }
The path within the backend where the settings are stored.
public string schema { construct; owned get; }
The name of the schema that describes the types of keys for this Settings object.
public string schema_id { construct; owned get; }
The name of the schema that describes the types of keys for this Settings object.
public SettingsSchema settings_schema { construct; owned get; }
The SettingsSchema describing the types of keys for this Settings object.

Static methods:

public static unowned string[] list_relocatable_schemas ()
public static unowned string[] list_schemas ()
public static void sync ()
Ensures that all pending operations for the given 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 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 void @get (string key, string format, ...)
Gets the value that is stored at key in this.
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 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 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 (string key, string format, ...)
Sets key in this to value.
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_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_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