Ubuntu – The schema XML file in the data/glib-2.0 folder of the Quickly application

application-developmentpygtkquickly

I created an Ubuntu application with Quickly, and I can see an XML file in the folder data/glib-2.0 of my project root and I am not exactly sure what this is for. The XML looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<schemalist gettext-domain="sample-application">
  <schema id="net.launchpad.sample-application" path="/net/launchpad/sample-application/">
    <key name="example" type="s">
      <default>''</default>
      <summary>Sample setting</summary>
      <description>Longer description of this sample setting.  Talk about allowed values and what it does.</description>
    </key>
  </schema>
</schemalist>

Furthermore, in the default preferences dialog code that is created with a new application, I can see the following code:

settings = Gio.Settings("net.launchpad.sample-application")
widget = self.builder.get_object('example_entry')
settings.bind("example", widget, "text", Gio.SettingsBindFlags.DEFAULT)

and I am not sure what this is doing.

Best Answer

The XML file defines a set of keys you can use throughout your application to store user preferences.

In the element schema, you will notice two attributes: id and path. The id is what you use to refer to the schema in the code when instantiating the settings object. The path is where the keys are stored.

You can find the settings by installing the dconf-tools package, and running dconf-editor. Then navigating to the node defined above. The node in the XML in the question (/net/launchpad/sample-application) would be here:

dconf-editor window at the path /net/launchpad/sample-application

The schema is used against the GSettings API. You can see the GTK C based docs here: http://developer.gnome.org/gio/stable/GSettings.html. This is a part of the Gio module

As for the code.

settings = Gio.Settings("net.launchpad.sample-application")

This creates the GSettings object, that you can use to bind widgets to for storing settings. The parameter needs to match exactly the id attribute of the schema element in the XML.

settings.bind("example", widget, "text", Gio.SettingsBindFlags.DEFAULT)

This creates a binding between the example key in the schema, to the text property of the widget. The value that gets passed to the key is the text property of the specified widget. For GtkEntry, text is the most obvious property to use. Because it is being bound, whenever you change the value of the property in the preferences window, it is automatically updated. The final parameter determines which direction the binding works - see the docs for more information.

The type you specify in the XML for the key should match one of the available options. Generally a single character, which you will see against the defined constant. E.g. for a boolean:

#define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b")

So boolean equates to b.

So, just say you wanted a boolean key, you could add the following beneath schema element, alongside the other key:

<key name="complete" type="b">
  <default>false</default>
  <summary>Whether the task is complete</summary>
  <description>This key is used to determine if a particular part of the application is complete or not</description>
</key>

Then bind the active property like so:

# Get the widget (named chk_complete)
complete = self.ui.chk_complete
# Bind the property
settings.bind("complete", complete, "active", Gio.SettingsBindFlags.DEFAULT)

Settings can then just be accessed with the get function, specific to the data type. e.g.

settings = Gio.Settings("net.launchpad.sample-application")
example = settings.get_string("example")
complete = settings.get_boolean("complete")
Related Question