Apps should automatically save their state in elementary OS, allowing a user to re-open a closed app and pick up right where they left off. To do so, we utilize GSettings
via GLib.Settings
. GSettings allows your app to save certain stateful information in the form of booleans, strings, arrays, and more. It's a great solution for window size and position as well as whether certain modes are enabled or not. Note that GSettings is ideal for small amounts of configuration or stateful data, but user data (i.e. documents) should be stored on the disk.
For the simplest example, let's create a switch in your app, and save its state.
First, you need to define what settings your app will use so they can be accessed by your app. In your data/
folder, create a new file named gschema.xml
. Inside it, let's define a key for the switch:
The schema's path
and id
attributes are your app's ID (path
in a /
format while id
is the standard dot-separated format). Note the key's name
and type
attributes: the name is a string to reference the setting, while in this case type="b"
defines the setting as a boolean. The key's summary and description are developer-facing and are exposed in developer tools like dconf Editor.
In order to interact with the settings key we just defined, we need to create a GLib.Settings object in our application. Building on previous examples, you can create a Gtk.Switch, add it to your window, create a Settings object, and bind the switch to a settings key like so:
You can read more about GLib.Settings.bind ()
on Valadoc, but for now this will bind the active
property of the switch to the value of useless-setting
in GSettings. When one changes, the other will stay in sync to reflect it.
We need to add the new GSchema XML file to our build system so it is included at install time. Create a file data/meson.build
and type the following:
This ensures your gschema.xml file is installed, and renames it with your app's ID to avoid filename conflicts.
Be sure to add the following lines to the end of the meson.build file in your source root so that Meson will compile the installed schemas:
Compile and install your app to see it in action!
GSettings are installed at install time, not compile time. So you'll need to run ninja install
to avoid crashes from not-yet-installed settings.
To see the state saving functionality in action, you can open your app, toggle the switch, close it, then re-open it. The switch should retain its previous state. To see it under the hood, open dconf Editor, navigate to your app's settings at io.github.yourusername.yourrepositoryname, and watch the useless-setting
update in real time when you toggle your switch.
If you're having trouble, you can view the full example code here on GitHub