Application Settings

We just learned how to save application data to files. While this is appropriate for storing data relevant to the user's activities and any user-generated content, application-level settings should utilize the built-in GSettings APIs.

Defining a Schema

Before we can store any settings we must inform GSettings what we want to store. We do this with a schema file.

In your template or GNOME Builder Project you should find a file named [your.app.id].gschema.xml.

Its contents should look roughly like this:

<?xml version="1.0" encoding="UTF-8"?>
<schemalist gettext-domain="[App Name]">
	<schema id="[your.app.id]" path="[your/app/path]">
	</schema>
</schemalist>

Adding a setting

To add a setting you must add a <key> to <schema>.

A typical key looks like this:

<key name="is-running" type="b">
    <default>false</default>
    <summary>Running state</summary>
    <description>Describes if it is running</description>
</key>

name= sets the name of the setting. This is used to retrieve and modify the setting's value. type= sets the type of the setting. A complete list of types is available here. <default> lists the default value of the setting. <summary> briefly describes the purpose of the setting. <description> provides a longer, more detailed explanation of the setting.

Once added, your settings file should look like this:

<<?xml version="1.0" encoding="UTF-8"?>
<schemalist gettext-domain="[app-name]">
	<schema id="[your.app.id]" path="[your/app/path]">
        <key name="is-running" type="b">
            <default>false</default>
            <summary>Running state</summary>
            <description>Describes if it is running</description>
        </key>
	</schema>
</schemalist>

Accessing settings

To access settings in your app you need a Gio.Settings instance:

const settings = new Gio.Settings({ settings_id: '[your.app.id]' });

Now you can retrieve settings with settings.get_{type}(name).

For example:

const isRunning = settings.get_boolean('is-running');

You can find a complete list of getters here.

Setting, a setting.

Setting your new setting's value is quite similar to getting it. Simply call settings.set_{type}(name, value).