Toolkit Preferences System

Introduction

This document describes the Aviary Toolkit's new <preferences> system. Using this system it is possible to create preferences windows that display and operate appropriately on various platforms: (Windows, MacOS X and GNOME)

Use

Code for a typical preferences window may look something like this:

        <prefwindow id="appPreferences"
                       xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
          <prefpane id="pane1" label="&pane1.title;">
            <preferences>
              <preference id="pref1" name="pref.name" type="bool"/>
            </preferences>
            
            .. UI elements that refer to the preferences above
          </prefpane>
          <prefpane id="pane2" label="&pane2.title;" src="chrome://url/to/pane.xul"/>
        </prefwindow>
      

Pane content can be specified inline or an external chrome URI supplied for pane content to be loaded in via a dynamic overlay. You should be careful to read the HIGs for the platforms you are targeting and use the XUL preprocessor if necessary to set different window titles as appropriate. You should also be careful to specify the width of the window (in em) as appropriate using the preprocessor for each targeted platform, as well as the height (in em) for platforms where the window size does not change as the selected panel is changed (e.g. Windows).

Reference

<preferences>

<preferences> is a container for <preference> elements.

Interface Methods/Properties

See preferences.xml for a full listing

<preference>

<preference> is a representation of a preference.

XUL Syntax

See Firefox usage for examples.

Interface Methods/Properties

See preferences.xml for a full listing

void setElementValue(in DOMElement element); - initializes the supplied element from the value stored in the preference. This function calls onpreferenceread

type getElementValue(in DOMElement element); - retrieves the value that should be written to preferences based on the current state of the supplied element. This function calls onpreferencewrite

void updateElements(); - update all elements that observe this preference.

onpreferenceread/onpreferencewrite

Often you will have UI whose construction does not map easily to a given preference type. For example, you may have a checkbox that is checked when an integer preference value is 3 and not when it's 2. To initialize this UI element you can't rely on the default initialization routine, since both values are meaningless to the checkbox element. You need to write translation functions to translate the preference value into an initialization value for the UI element, and to translate the UI element's value into something to write to the preferences file. This is what onpreferenceread/ onpreferencewrite are for.

onpreferenceread is called when an element is initialized from preferences. If you supply an implementation of this event, your implementation will be invoked during initialization and you can return the value with which to initialize the UI element with, or undefined to tell the preferences system to initialize the UI element with the default value (i.e. to attempt to initialize with the preference value). In the above example, you might write the checkbox like this:

        <checkbox preference="foo.bar" onpreferenceread="return onPreferenceRead();"/>
        
        .. script:
        
        function onPreferenceRead()
        {
          var preference = document.getElementById("foo.bar");
          return preference.value == 3;
          
          // If foo.bar was boolean and we wanted to use its value to initialize 
          // the checkbox, we could still implement this method if we wanted to
          // perform any other initialization actions at this time. 
        }
       

        <checkbox preference="foo.bar" onpreferencewrite="return onPreferenceWrite();"/>
        
        .. script:
        
        function onPreferenceWrite()
        {
          var checkbox = document.getElementById("checkbox");
          return checkbox.checked ? 3 : 2;
        }
        
        // If foo.bar was boolean and we wanted to use its value to write to
        // preferences, we could still implement this method if we wanted to 
        // perform any other initialization actions at this time.