Preferences subsystem

While reading this file, it's advisable to consult the Doxygen documentation for the Inkscape::Preferences class.

Where preferences are stored

Preferences are currently 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, much like a GConf database or the Windows Registry. In this file, element nodes correspond to keys (folders) and attributes to entries.

Currently this file is a mess, but some refactoring is underway. In future, there will be no guarantee that preferences are stored in an XML file.

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.

Here is a positive example:

<group id="tools">
  <eventcontext id="select"
       foo="1"
       bar="1.0" />
</group>

Do NOT do something like this:

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

This is because if you think about element nodes as folders and attributes as entries, you would get a path like "/options/nudgedistance/value", which is absurd. It's better to place your preference as an attribute of the options node. However, it would be ideal if you found a better place for your preference than the generic "options" hierarchy.

Some points of interest:

• Element names are irrelevant. 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=\"tools\">\n"
"  <eventcontext id=\"select\"\n"
"       foo=\"1\"\n"
"       bar=\"1.0\" />\n"
"</group>\n"

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 "preferences.h"

This header includes a singleton class that you can use to access the preferences. To get at the value of the preference, use its members methods. To receive an instance of this class, call the static function get(). Always name the pointer to this object "prefs", for consistency.

Inkscape::Preferences *prefs = Inkscape::Preferences::get();
double val = prefs->getDouble("tools.select", "bar", 1.0);

What this call does is it 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. Preferences are also saved in the crash handler, so changes to them should be preserved even if Inkscape crashes.

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 getDouble method 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->getDouble 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->setDouble("tools.select", "bar", new_bar); 

In addition to double values, you can also store and retrieve Glib::ustrings, ints and bools. Always choose the right type for your 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. To do this, use the methods getIntLimited and getDoubleLimited. Do not use these to store boolean preferences as integers limited to 0 and 1.

Add UI

In ui/dialogs/inkscape-preferences.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" section. For example, to add an integer-selecting spin-button (sb) you could add to inkscape-preferences.h the line

   PrefSpinButton  _steps_arrow,

And add to inkscape-preferences.cpp the lines:

   _steps_arrow.init ( "options.nudgedistance", "value", 0.0, 3000.0, 0.01, 1.0, 2.0, false, false);
   _page_steps.add_line( false, _("Arrow keys move by:"), _steps_arrow, _("px"), 
                         _("Pressing an arrow key moves selected object(s) or node(s) by this distance (in px units)"), false);

---

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

Please do not use the Windows registry. The beauty of having the preferences file is that Inkscape does not need an install or admin rights, and does not litter the OS (at least, i think that is what the registry does). It is very easy for a user that has problems to delete his preferences.xml and download a new one; much easier than fiddling in the registry. - Johan

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

I have implemented what mental and bulia suggested. There are however still some places which assume that prefs are stored as an XML file, and use things like sp_repr_css_attr_inherited on nodes retrieved from the prefs file using inkscape_get_repr. Those places need to be refactored to use the Preferences object. GConf has all the features needed to reimplement the prefs interface in it, and I'll try to do this after the refactoring of the preferences code is complete. GConf support would be enabled at compile time, so it wouldn't be present in Windows builds at all, and even then it would fall back to the flat XML file if it couldn't access the GConf database. Note also that GConf is not inherently based on XML, as it can store the data in a binary file, in an SQLite database, an LDAP server or even in a relational database. Additionally, it does the merging of system-wide and user configs for us. As for Apple plist support, it depends on whether it supports pref listeners. If it does, an implementation would be rather straightforward. If it doesn't, we would have to implement listeners ourselves in the Preferences object. --Tweenk