Skip to main content

Visit Mozilla.org

Preferences System:prefwindow

From MDC


Contents

[edit] Overview

<prefwindow> is the documentElement (i.e. top-level element like <window> or <dialog>) of preferences windows.

This element should contain one or more <prefpane> elements.

[edit] XUL Syntax

TBD 

<prefwindow xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
       id="window-id" windowtype="window:type" title="Options"
       style=" TBD ">
  one or more prefpane elements
</prefwindow>

[edit] Attributes

lastSelected 
The id of the last selected pane. Used to re-open that pane when the preferences window is opened next time.
type 
Must be either "prefwindow" or "child".
type="child" indicates a sub dialog of a top level preferences window, usually modal. In instant-apply conditions (MacOS X, GNOME), when this sub dialog is confirmed, its preferences are written. In non-instant-apply conditions (Windows) when this sub dialog is confirmed, changes made in it are saved in the calling window's <preferences> set and are saved when the calling window is confirmed. Child prefwindows can't have multiple panes.
dlgbuttons 
Same as the dialog element.

[edit] Properties

currentPane (readonly) 
Currently selected <prefpane> element. Use showPane() method to select another pane. (Same comment as for instantApply.)
instantApply (readonly) 
Indicates whether the window is in "instant apply" mode. The value is read from browser.preferences.instantApply boolean user preference. (?? It's declared as a <field>, so you can set the value, however I don't believe it's valid to do that.)
lastSelected (readonly) 
Returns the value of the lastSelected attribute.
preferencePanes (readonly) 
A NodeList of <prefpane> elements.
type (readonly) 
Returns the value of the type attribute.

[edit] Methods

void addPane(in DOMElement pane); 
Adds the specified <prefpane> element to the preferences window. You can use this method to append dynamically created panes to the dialog.
animate(aOldPane, aNewPane) 
This probably isn't a public method (?)
DOMWindow openSubDialog(in string url, in string features, in object params); 
Opens a modal sub dialog as a child of the preferences window. Similar to window.openDialog, except you don't have to specify modal and centerscreen features when using this method, they are added automatically. Use this method to open a modal subdialog, like Connection Settings in Firefox.
DOMWindow openWindow(in string windowType, in string url, in string features, in object params); 
Opens a non-modal sub window as a child of the preferences window. You can supply a window type so that any existing open windows of this type will be focused instead of opening a new one. An example of such sub window is the Exceptions window in Firefox Options.
void showPane(in DOMElement paneElement) 
Selects given pane, loading it dynamically, if necessary. paneElement must be a <prefpane> element from the same window.

Note that you can define an initWithParams() function in your sub window - to handle parameters passed using openWindow() in case the window was already open. For example the Permissions Manager UI in Firefox uses the same window for three dialogs: Images, Software installation and Popups. It uses initWithParams() to change the dialog type without closing and re-opening it.

The suggested usage pattern is as follows: 

// subwindow.js
function onLoad(ev) {
  // do some initialization...

  initWithParams(window.arguments[0]); // we expect a single parameter to be passed to the window
}

function initWithParams(aParams) {
  // this will also get called when an already open window is activated using openWindow()
}

[edit] Notes

[edit] Opening a modal sub dialog

A sub dialog can only be opened via document.documentElement and not via window. Therefore, an example call to openSubDialog() would look like this: 

document.documentElement.openSubDialog("chrome://myextension/content/options-sub.xul", "", null)

[edit] Issues when using prefpanes in prefwindow

When you wish to put non-<prefpane> elements to prefwindow, you should place them after all of <prefpane>s. If you put other elements before the first <prefpane>, you possibly see strange behaviors about switching panes. This is due to bug 296418.

Should not: 

<prefwindow>
  <script src="config.js"/>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
</prefwindow>

Should: 

<prefwindow>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
  <script src="config.js"/>
</prefwindow>

Preferences System documentation:

Retrieved from "http://developer.mozilla.org/en/docs/Preferences_System:prefwindow"