« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

A single preference panel in a prefwindow. A prefpane is made up of two parts, the preferences descriptions, which specify the set of preferences that will be modified, and the user interface for adjusting those preferences. The former is specified using a preferences element while the latter may be specified using other XUL elements.

Both may be specified directly as children of the prefpane element, or the src attribute may be used to put a pane in a separate file. In this latter case, the separate file should use an overlay tag as its root tag since it will be loaded as an overlay to the main preferences window.

More information is available in the Preferences System article.

Attributes
helpURI, image, label, onpaneload, selected, src
Properties
image, label, preferenceElements, preferences, selected, src

Examples

Methods
preferenceForElement
<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>

Attributes

helpURI
Type: URI
The URI of the help page associated with a preference panel. The URI will be opened using the help viewer when the help button is pressed.
image
Type: URI
The URI of the image to appear on the element. If this attribute is empty or left out, no image appears. The position of the image is determined by the dir and orient attributes.
label
Type: string
The label that will appear on the element. If this is left out, no text appears. For an editable menuitem element the value of this attribute is copied to the menulist.value property upon user selection of the menuitem.
onpaneload
Type: script code
Code defined here is called when the pane has been loaded, much like the load event for a window.
selected
Type: boolean
This attribute will be set to true for the currently selected prefpane. To change the selected pane, use the prefwindow's showPane method.
src
Type: URI
The URI of the overlay contents of preference pane. If this is not specified, the contents of the prefpane element is used.

Properties

contentHeight (readonly)
The height (in pixels) of current pane's content.
image
Type: image URL
Gets and sets the value of the image attribute.
label
Type: string
Gets and sets the value of the label attribute.
loaded
Indicates whether the pane is fully loaded.
preferenceElements
Type: DOM Nodelist
Holds a list of the UI elements in the pane that are attached to preferences.
preferences
Type: DOM Nodelist
Holds a list of the preference elements in the pane.
selected
Type: boolean
This property's value is true if this element is selected, or false if it is not. This property is read only. This property is available for menuitem and menuseparator elements in Firefox 3.
src
Type: URL
Gets and sets the value of the src attribute.

Methods

DOMElement getPreferenceElement(in DOMElement startElement)
preferenceForElement( uielement )
Return type: preference element
Returns the preference element to which a user interface element is attached.
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.

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

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.

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");

Preferences System documentation: