Preferences subsystem

Where preferences are stored

Preferences are stored in an XML file called

~/.inkscape/preferences.xml 

on Linux or

Documents and Settings/USER/Application Data/Inkscape/preferences.xml

on Windows. Note that the Windows path is supposed to be relative to Inkscape program directory.

This file stores the hierarchy of values. Each value is in an attribute belonging to one of the elements, and elements with attributes are usually grouped together by top-level elements. Note that all elements have unique id attributes.

Find a place for your value

When creating a new preference value, start by examining this file and finding a logical place for the new value. For example, if I want to add a value for some option related to the selector tool, I find the group element with id="tools" and inside I find <eventcontext id="select"/>. Now this element is empty, but I can store my value in a new attribute. If you have added a new object to the program, such as a new tool or dialog, add a new element in an appropriate top-level element. If you want to store something entirely new and not yet taken care of, you can even add a new top-level element.

This is what I did when I decided to store a value of the nudge distance (the distance of one arrow-key jump). This value is not local to any single tool; it is used in selector and node editor and will likely be used in other tools as well. So I created a new top-level element for all such global options and put my value there like so:

 <group id="options">
   <group id="nudgedistance" value="2.8346457"/>
 </group>

Here, 2.8346457 is the distance in points that is equal to 1 mm. Note:

• Element names actually do not matter. What matters for finding the value is the id attribute values. So you can use group elements or any others, whatever seems more logical.

• Values are stored in attributes. No text within elements is allowed (except whitespace).

Add the value to the skeleton

When no preferences file exists, a new one is created based on src/preferences-skeleton.h. Moreover, if the preferences file lacks some values, the defaults are taken from the same file. So, I edit this file adding

"  <group id=\"options\">"
"    <group id=\"nudgedistance\" value=\"2.8346457\"/>"
"  </group>"

before the closing

"</inkscape>";

Don't forget to escape quotes. The value given in this file is the default; if the user has changed it, his/her value in preferences.xml takes precedence over src/preferences-skeleton.h.

Now when you recompile, run, and exit Inkscape, the new elements with the default values will be added to your local preferences.xml (without affecting other values there).

Access the value in the program

Now for the interesting part. If you want to access your value in the program, start by adding

#include "prefs-utils.h"

to the header. Now, create a variable:

double nudge;

and right before it is going to be used, update it from the preferences like so:

nudge = prefs_get_double_attribute ("options.nudgedistance", "value", 2.8346457); 

What this call does is reads the value from the memory representation of preferences.xml. This representation was created on program start, may be used or modified by changing any values in it, and will be written back into preferences.xml when the program exits. (FIXME: do we need a menu command for saving preferences?)

To pinpoint the value we need, you pass to this function a text string in a syntax that is vaguely reminiscent of XPath, except that it uses id attribute values instead of element names and a dot instead of / as a separator. That is, options.nudgedistance means, find top-level element with id="options" and within it, an element with id="nudgedistance". The second argument to the prefs_get_double_attribute is the name of the attribute that we are interested in. The third argument is the default value which will be returned if no such value is stored in the preferences.

It is important that this prefs_get_double_attribute call is done before each use of the value, and not just once upon program launch, because the preferences may be edited by the user via a dialog (see below for more on that) and we want the interface to respond to these changes immediately.

Similarly, to write a new value back into the preferences' memory representation, use

prefs_set_double_attribute ("options.nudgedistance", "value", new_nudge); 

Instead of double values, you can store and retrieve ints (more precisely, gints) by

gint prefs_get_int_attribute (gchar *path, gchar *attr, default); 
void prefs_set_int_attribute (gchar *path, gchar *attr, new_value); 

or strings by

gchar const *prefs_get_string_attribute (gchar const *path, gchar const *attr);
void prefs_set_string_attribute (gchar const *path, gchar const *attr, gchar const *value);

Guard against screw-ups

Sometimes there may be very weird values stored in the preferences file, which may cause trouble to the program. It is wise to guard against them by providing min and max bounds for your value. Here's how:

gint prefs_get_int_attribute_limited (gchar *path, gchar *attr, gint def, gint min, gint max);
double prefs_get_double_attribute_limited (gchar *path, gchar *attr, double def, double min, double max);

These functions will return def if the value stored in the preferences is less than min or greater than max. Be generous in setting limits, but be sure to test that with the value set to any of the limits program does not crash.

Add a UI

In dialogs/display-settings.cpp is the code that attaches a GUI to any given preference. If your option doesn't already have a logical place to go, add it under the "Misc" tab. See the defined "options_*" functions for adding a visible item. For example, to add an integer-selecting spin-button (sb) you could do:

       options_sb (
           _("Arrow keys move by:"),
           _("Pressing an arrow key moves selected object(s) or node(s) by this distance (in SVG pixels)"), tt,
           _("px"),
           vb,
           0.0, 3000.0, 0.01, 1.0, 1.0,
           "options.nudgedistance", "value", 2.0,
           false, false,
           options_changed_double
           );

---

The next section of this tutorial will be devoted to how a preference value can be edited in an options dialog. See related page: PreferencesDialog.

---

Discuss below:

I also think we should consider having a global preferences file in /etc/inkscape/preferences.xml, and similarly with markers.svg, that are installed during program installation, and merged with or overwritten by the user's settings. This is standard UNIX config file strategy. - bryce

Njh wonders whether you would be better off using gconf?

Maybe, but I'm not in a position to decide. Right now I'm interested in how I can use the existing preferences system to store and retrieve a value. -- bb

Looking further, it appears that gconf is indeed a similar XML system, so at some point it should be easy enough to switch over. --njh

Mental and I were discussing GConf, and he brought up the issue of Win32 compatibility. It would be nice if we could abstract a preferences interface that would work with both the windows registry and GConf. I think they have similar interfaces - so it shouldn't be impossible --ted

If this is going to be done, why not also look into implementing Apple's .plist support, it's a simple xml format defined: http://www.apple.com/DTDs/PropertyList-1.0.dtd These files are stored in ~/Library/Preferences/tld.<company>.<product>.plist - tom

Well, if we're looking around at existing approaches, the discussion probably wouldn't be complete without taking a look at the new Java preferences API added in 1.4. They currently store to a dir/dir/xml tree on Linux, and to the registry on Windows, so they do that exact abstraction we're looking at. (funny thing is, for some apps, I wrote a layer to abstract that for running in Java VM's prior to 1.4 - double indirection). --jon

• A nice Sun article about them
• An article by IBM about them