The Grail preferences infrastructure provides persistent, user-controllable settings for customizable Grail features. Things like browser geometry and personal home page are set using GUI panel dialogs, and custom settings are maintained in the user's personal preferences file. This document describes the preferences infrastructure. Refer to the Preference Panel Plug-in Reference Manual for more information.
ancillarysubdirectory of the Grail sources.
In addition, panel-specific definition modules are sought in a subdirectory named 'prefpanels' in the user's .grail directory and the Grail sources directory, in that order.
Grail respects two files dictating preference values:
The preferences API routines all take the group/component pair of names as a pair of arguments. In preference files, preferences names are a concatenation of the group name followed by a "--" and then the component name.
AllPreferences, in the variable
app.prefs. The instance reads the preferences files on initialization. It provides methods for programmatic access to preference settings:
prefs.Get(group, component, use_default=0)
prefs.GetInt(group, component, use_default=0)
prefs.GetFloat(group, component, use_default=0)
prefs.GetBoolean(group, component, use_default=0)
prefs.Get(), does not constrain the type and returns a string.
prefs.Set(group, name, value)
Any callback routines associated with the group of changed settings are invoked when the settings are saved to file. No callback is invoked more than once during a save, even if it has distinct associations with multiple groups that have changed.
def load_images_vis_prefs(app=app): app.load_images = app.prefs.GetBoolean('browser', 'load-images')and here is how it is registered so it will be invoked when a change to any preferences in the 'browser' group is saved:
load_images_vis_prefsroutine could be more elaborate - it could check for changes in the preference of concern, before taking any action, for instance - but such elaboration is not necessary for this setting.
$GRAILROOT/grail-defaults") and user ("~/.grail/grail-preferences") files have the same format, consisting of lines containing name/value pairs, delimited like
RFC 822(email message) header fields. The preference group and component are encoded a single name that corresponds to the RFC 822 header-field name, by concatenating them together with a "--" pair of dashes, and appending a ':' to delimit the name from the value. Typically, whitespace follows and then the value for that preference. There are also continuation lines, which begin with whitespace but also must contain non-whitespace. These lines continue the value for the most recent line with a preference name. Comment lines, which are lines with a "#" hash character in column 0, are ignored. The preference names are case insensitive.
Note that comments are not preserved when the file is written by the preferences interface. (Thus, the system defaults file should never be written by the interface, and the user preferences file should not be expected to retain comments.)
Here is an example fragment of a system preferences file:
landmarks--grail-home-page: http://monty.cnri.reston.va.us/grail-0.2/ # Pref ('landmarks', 'home-page') with empty value: landmarks--home-page: # Pref with value on continuation line: presentation--message-font: -*-helvetica-medium-r-normal-*-*-100-100-*-*-*-*-* browser--default-height: 40
PrefsPanels.py contains two components which are used externally:
PrefsPanelsMenuclass, by which the panels are incorporated to the Browser object.
Frameworkprovides a framework for individual panels. It is used, via inheritance, for the following features:
Refer to Preference Panel Plug-in Reference Manual for specifics.