Back to Seed Clases

Gio


Classes

Interfaces

Structs

Unions

Enums

GObject.Object
parent-child marker Gio.Settings

Class Gio.Settings

Import line: Gio = imports.gi.Gio;
GIR File: Gio-2.0.gir
C documentation: GSettings
Class : Settings
Extends: GObject.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
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 settings 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 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.
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. Key names can
be up to 32 characters long.
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 that can be
described by the following DTD:
|[FIXME: MISSING XINCLUDE CONTENT]|
glib-compile-schemas 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 GVariant types, keys can have types that have enumerated
types. These can be described by a choice,
enum or flags element, see
. The underlying type of
such a key is string, but you can use g_settings_get_enum(),
g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
access the numeric values corresponding to the string value of enum
and flags keys.
Default values



"Hello, earthlings"
A greeting

Greeting of the invading martians



(20,30)



]]>
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.
Properties
Properties Defined By
Methods / Constructors
Method / Constructor Defined By
Events - usage syntax: this.signals.EVENTNAME.connect( Function )
Event Defined By
Used by These Methods / Signals / Properties- Nowhere other than here
Documentation generated by Introspection Doc Generator Loosely Based on JsDoc Toolkit on Sat Apr 16 2011 17:11:15 GMT+0800 (HKT)