# gsettings 0.1.1

GSettings provides a convenient API for storing and retrieving application settings.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add 'gsettings:0.1.1'
```
Published: 2021-04-05T15:53:33.622079Z
Expected archive SHA-256: 57bc9eadd896abbc8f2a2376e72c159b0a6bc8410c2db60edf2e59e46006c566

Available in cache; verification: upstream_checksum
## Direct dependencies
- dylib: ^0.3.2
- equatable: ^2.0.0
- ffi: ^1.0.0
- meta: ^1.3.0
- more: ^3.0.1

## Package README (untrusted upstream documentation)
# GSettings for Dart

[![pub](https://img.shields.io/pub/v/gsettings.svg)](https://pub.dev/packages/gsettings)
[![license: LGPL3+](https://img.shields.io/badge/license-LGPL3+-magenta.svg)](https://opensource.org/licenses/LGPL-3.0)
[![style: lint](https://img.shields.io/badge/style-lint-4BC0F5.svg)](https://pub.dev/packages/lint)
![CI](https://github.com/jpnurmi/gsettings.dart/workflows/CI/badge.svg)
[![codecov](https://codecov.io/gh/jpnurmi/gsettings.dart/branch/master/graph/badge.svg?token=Xmk3Tx4f1O)](https://codecov.io/gh/jpnurmi/gsettings.dart)

GSettings provides a convenient API for storing and retrieving
application settings.

| **NOTE:** This package is based on FFI bindings to [GSettings](https://developer.gnome.org/gio/stable/GSettings.html) from the GIO library. |
| --- |

Reads and writes can be considered to be non-blocking. Reading settings
with GSettings is typically extremely fast: on approximately the same orde
of magnitude (but slower than) a hash-table 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.


## Example

```dart
import 'package:gsettings/gsettings.dart';

void main() {
  final settings = GSettings(schemaId: 'org.gnome.desktop.interface');
  final theme = settings.stringValue('gtk-theme');
  print(theme); // e.g. 'Yaru'
  settings.dispose();
}
```

## Schemas

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, 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 an
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
`<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
 <!-- Translators: A list of words which are not allowed to be typed, in
      GVariant serialization syntax.
      See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
 <default l10n='messages' context='Banned words'>['bad', 'words']</default>
```

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](https://developer.gnome.org/gio/stable/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](https://gitlab.gnome.org/GNOME/glib/-/blob/master/gio/gschema.dtd)

The [glib-compile-schemas](https://developer.gnome.org/gio/stable/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 IDshould 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. The underlying type of such a key is string, but you can use
`GSettings.enumValue()` and `GSettings.flagsValue()` to 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="box" type="(ii)">
      <default>(20,30)</default>
    </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>
  <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](https://developer.gnome.org/gio/stable/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 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`.

## Relocatable schemas

A relocatable schema is one with no `path` attribute specified on its
`<schema>` element. A relocatable GSettings object can be instantiated by
passing a path to GSettings constructor. Paths are typically 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>
```

## Changelog
## 0.1.1

* Added support for enums & flags.

## 0.1.0

* Added missing APIs, docs, example, tests...

## 0.0.1

* Initial draft release