Preferences System:prefpane

From MDC

Contents 1 Overview 2 XUL Syntax 3 Attributes 4 Properties 5 Methods 6 Events 7 Using multiple prefpanes

[edit] Overview

<prefpane> is an element representing a pane (tab) in a preferences window. It must be a child of the <prefwindow> element.

Typically a <prefpane> contains a child <preferences> element in addition to the UI elements.

The <prefpane> element may contain all of its content inline, or it may refer to an external overlay chrome URI, which will be loaded when the pane is selected, using the src="chrome://uri/to/overlay.xul" attribute. The latter method can be used to reduce time needed to load your preferences window if it's very large, as only a single pane needs to be loaded before the window is shown to user.

[edit] XUL Syntax

<prefpane id="paneGeneral" label="General" src="chrome://path/to/paneOverlay.xul"/>

or

<prefpane id="paneGeneral" label="General" onpaneload="onGeneralPaneLoad(event);">
  <preferences>
    <preference id="pref_one" name="extensions.myextension.one" type="bool"/>
     ... more preferences ...
  </preferences>

  <checkbox label="Number one?" preference="pref_one"/>
  ... more UI elements ...
</prefpane>

[edit] Attributes

id 

The id of the pane. This may be used to match the element from a dynamic overlay, but you must provide an id for all your <prefpane> elements, even if you don't use dynamic pane loading.

image 

Specifies the URL of image to be used on the pane button. (Changing this attribute at runtime does not update the pane button image).

label 

The label for the pane button.

selected 

Indicates whether the pane is currently selected (active). (Setting this at design-time doesn't work, use lastSelected attribute of <prefwindow> instead.)

src 

See above, the URL of the overlay which provides content for the pane.

[edit] Properties

(todo: check what happens if you set these attributes/properties at runtime. I don't think all of them have effect at runtime.)

contentHeight (readonly) 

The height (in pixels) of current pane's content.

image 

Gets and sets the value of the image attribute. (Setting this property at runtime does not have effect).

label 

Gets and sets the value of the label attribute. (Setting this property at runtime does not have effect).

loaded 

Indicates whether the pane is fully loaded.

preferenceElements (readonly) 

A NodeList of child elements with preference attribute.

preferences (readonly) 

A NodeList of all child <preference> elements.

selected 

Gets and sets the value of the selected attribute.

src 

Gets and sets the value of the src attribute.

[edit] Methods

DOMElement getPreferenceElement(in DOMElement startElement) 

 ??

DOMElement preferenceForElement(in DOMElement element); 

Obtains the <preference> element that the supplied element observes (i.e. the element specified in element's preference attribute).

void userChangedValue(in DOMElement element); 

The user changed the value in a widget that the preferences system does not automatically track state changes for (1) and the preference element associated with the widget should be updated based on the state held by the widget. For example, if you are using a listbox and the user changes the contents of the listbox (such as adding or removing an item) and you want to sync the changes back to a preference, you must write an onsynctopreference handler for your listbox that returns the value to be written to the preference element, and then call the userChangedValue function every time you edit the list in a way that should cause the preference's value to change.

(1) an example of a widget that has state changes tracked for it includes the checkbox element, whose state is tracked automatically when the "command" event fires.

void writePreferences(in boolean flushToDisk); 

Writes all changes in this pane to preferences, optionally flushes to disk.

[edit] Events

paneload 

This event is fired on the pane element when the pane is fully loaded (e.g. after the overlay is merged.) You can put the handler for this event in the onpaneload attribute on the element.

[edit] Using multiple prefpanes

Note that when using multiple prefpanes in the same prefwindow, you must not put the <script> elements above the prefpane elements, but instead below them. Otherwise the dialog will show erratic behavior and not display correctly.

Place the <script> tags as in the following example for preference dialogs to work correctly:

<prefwindow>
  <prefpane id="paneGeneral" label="General">
    ...
  </prefpane>

  <prefpane id="paneSecurity" label="Security">
    ...
  </prefpane>

  <script type="application/javascript" src="chrome://myext/content/script0.js">
  <script type="application/javascript" src="chrome://myext/content/script1.js">
</prefwindow>

When opening a dialog with multiple panes you must include the toolbar feature in the call to openDialog, for example:

window.openDialog("chrome//example/content/prefwin.xul", "", "chrome,toolbar");