MozillaZine

Preferences bindings

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 15:33, 10 May 2005
Asqueella (Talk | contribs)

<-- Previous diff
Revision as of 23:20, 29 May 2005
Asqueella (Talk | contribs)
(some progress)
Next diff -->
Line 1: Line 1:
-'''Work in progress''' See also [http://forums.mozillazine.org/viewtopic.php?t=263028].+: '''''Work in progress''' See also [http://forums.mozillazine.org/viewtopic.php?t=263028 this forum thread] for the general description and list of available elements/attributes.''
-This is about new bindings introduced in Toolkit used in Firefox/Thunderbird 1.1. The new binding allow you write preferences UI faster, using less JavaScript code.+This document describes the new [[XBL]] bindings introduced in Toolkit 1.1, which allow you write preferences UI faster, using less [[JavaScript]] code.
 +== todo ==
Todo: Todo:
Line 14: Line 15:
** instant apply ** instant apply
** animation ** animation
-* possible use of dynamic overlays for panes+* examples
 +__TOC__
== <prefwindow> == == <prefwindow> ==
-extends chrome://global/content/bindings/dialog.xml#dialog+<code><prefwindow></code> is a top-level element, like <code><window></code> or <code><dialog</code>. You should use it when creating Options dialog for Toolkit 1.1+ application.
 + 
 +The following attributes, properties and methods are available.
 + 
 +=== Attributes ===
 +Please see [http://forums.mozillazine.org/viewtopic.php?t=263028]
=== Properties === === Properties ===
-; <code>preferencePanes</code> : A <code>NodeList</code> of <code><prefpane></code> elements.+; <code>preferencePanes</code> (readonly) : A <code>NodeList</code> of <code><prefpane></code> elements.
-; <code>type</code> : Gets and sets the value of the <code>type</code> attribute.+; <code>type</code> (readonly) : Returns the value of the <code>type</code> attribute.
-; <code>lastSelected</code> : Used to get the value of the <code>lastSelected</code> attribute.+; <code>lastSelected</code> (readonly) : Returns the value of the <code>lastSelected</code> attribute.
-; <code>instantApply</code> : Indicates whether the window is in "instant apply" mode.+; <code>instantApply</code> (readonly) : Indicates whether the window is in "instant apply" mode. The value is read from <code>browser.preferences.instantApply</code> boolean user preference. (?? It's declared as a <cope><field></code>, so you ''can'' set the value, however I don't believe it's valid to do that.)
-; <code>currentPane</code> : Currently selected <code><prefpane></code> element. Use <code>showPane()</code> method to select another pane.+; <code>currentPane</code> (readonly) : Currently selected <code><prefpane></code> element. Use <code>showPane()</code> method to select another pane. (Same comment as for <code>instantApply</code>.)
=== Methods === === Methods ===
-; <code>showPane(aPaneElement)</code> : Selects given pane.+; <code>showPane(aPaneElement)</code> : Selects given pane, loading it dynamically, if necessary. <code>aPaneElement</code> must be a <code><prefpane></code> element from the same window.
-; <code>animate(aOldPane, aNewPane)</code> : ? is this a public method ?+; <code>animate(aOldPane, aNewPane)</code> : ?? is this a public method
-; <code>addPane(aPaneElement)</code> : Adds a specified prefpane to the window.+; <code>addPane(aPaneElement)</code> : Adds the specified <code><prefpane></code> element to the dialog. You can use this method to append dynamically created panes to the dialog.
-; <code>openSubDialog(aURL, aFeatures, aParams)</code> : Opens a modal sub-dialog.+; <code>openSubDialog(aURL, aFeatures, aParams)</code> : Opens a modal sub-dialog. Similar to <code>window.openDialog</code>, except you don't have to specify <code>modal</code> and <code>centerscreen</code> features when using this method, they are added automatically. Use this method to open a modal subdialog, like Connection Settings in Firefox.
-; <code>openWindow(aWindowType, aURL, aFeatures, aParams)</code> : +; <code>openWindow(aWindowType, aURL, aFeatures, aParams)</code> : Opens the specified window or focuses an already open one with given window type. Use this method to open a non-modal window, like Exceptions window in Firefox Options.
 +Note that you can define an <code>initWithParams()</code> function in your window - to handle parameters passed using <code>openWindow()</code> 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 <code>initWithParams()</code> to change the dialog type without closing and re-opening it.
 +
 +The suggested pattern is as follows:
 +<pre>
 +function onLoad(ev) {
 + // do some initialization...
 +
 + initWithParams(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()
 +}
 +</pre>
== <prefpane> == == <prefpane> ==
 +<code><prefpane></code> is an element representing a ''pane'' (tab) in the Options window. It must be a child of the <code><prefwindow></code> element.
 +
 +<code><prefpane></code> can have a <code>src</code> attribute specifying the overlay which provides the real content for it, or it can contain arbitrary XUL elements as its content. Using the first method can reduce time needed to load your Options window, if it's very large, as only a single pane needs to be loaded before the window can be shown to user.
 +
 +=== Attributes ===
 +; <code>id</code> : 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 <code><prefpane></code> elements, even if you don't use dynamic pane loading.
 +; <code>image</code> : Specifies the URL of an image to be used on the pane button. (does setting this at runtime have any effect??)
 +; <code>label</code> : The label for the pane button.
 +; <code>selected</code> : Indicates whether the pane is currently selected (active).
 +; <code>src</code> : See above, the URL of the overlay which provides content for the pane.
 +
=== Properties === === Properties ===
 +(todo: figure out what happens if you set these attributes/properties at runtime. I don't think all of them have effect at runtime.)
; <code>src</code> : Gets and sets the value of the <code>src</code> attribute. ; <code>src</code> : Gets and sets the value of the <code>src</code> attribute.
; <code>selected</code> : Gets and sets the value of the <code>selected</code> attribute. ; <code>selected</code> : Gets and sets the value of the <code>selected</code> attribute.
; <code>image</code> : Gets and sets the value of the <code>image</code> attribute. ; <code>image</code> : Gets and sets the value of the <code>image</code> attribute.
; <code>label</code> : Gets and sets the value of the <code>label</code> attribute. ; <code>label</code> : Gets and sets the value of the <code>label</code> attribute.
-; <code>preferenceElements</code> : A <code>NodeList</code> of child elements with <code>preference</code> attribute.+; <code>preferenceElements</code> (readonly) : A <code>NodeList</code> of child elements with <code>preference</code> attribute.
-; <code>preferences</code> : A <code>NodeList</code> of all child <code><preference></code> elements.+; <code>preferences</code> (readonly) : A <code>NodeList</code> of all child <code><preference></code> elements.
-; <code>loaded</code> : Indicates whether the pane is fully loaded.+; <code>loaded</code> (readonly) : Indicates whether the pane is fully loaded. (?? while it's possible to set the value of the property, it's not recommended to do so. The property really ought to be readonly)
-; <code>contentHeight</code> : +; <code>contentHeight</code> (readonly) : The height (in pixels) of current pane's content.
=== Methods === === Methods ===
-; <code>writePreferences(aFlushToDisk)</code> : +; <code>writePreferences(aFlushToDisk)</code> : Saves all <code><preference></code>s of the pane in user preferences, flushes to the disk (updating <tt>prefs.js</tt>) if <code>aFlushToDisk</code> is <code>true</code>.
-; <code>preferenceForElement(aElement)</code> : +; <code>preferenceForElement(aElement)</code> : Returns the <code><preference></code> element, which is specified in <code>aElement</code>'s <code>preference</code> attribute.
-; <code>getPreferenceElement(aStartElement)</code> : +; <code>getPreferenceElement(aStartElement)</code> : ??
-; <code>userChangedValue(aElement)</code> : +; <code>userChangedValue(aElement)</code> : ??
- +
== <preferences> == == <preferences> ==

Revision as of 23:20, 29 May 2005

Work in progress See also this forum thread for the general description and list of available elements/attributes.

This document describes the new XBL bindings introduced in Toolkit 1.1, which allow you write preferences UI faster, using less JavaScript code.

todo

Todo:

  • list attributes too
  • more detailed descriptions
  • mark readonly properties as such
  • sort alphabetically
  • check correctness
  • platform specific issues:
    • instant apply
    • animation
  • examples

Contents

<prefwindow>

<prefwindow> is a top-level element, like <window> or <dialog. You should use it when creating Options dialog for Toolkit 1.1+ application.

The following attributes, properties and methods are available.

Attributes

Please see [1]

Properties

preferencePanes (readonly) 
A NodeList of <prefpane> elements.
type (readonly) 
Returns the value of the type attribute.
lastSelected (readonly) 
Returns the value of the lastSelected attribute.
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 <cope><field></code>, so you can set the value, however I don't believe it's valid to do that.)
currentPane (readonly) 
Currently selected <prefpane> element. Use showPane() method to select another pane. (Same comment as for instantApply.)

Methods

showPane(aPaneElement) 
Selects given pane, loading it dynamically, if necessary. aPaneElement must be a <prefpane> element from the same window.
animate(aOldPane, aNewPane) 
 ?? is this a public method
addPane(aPaneElement) 
Adds the specified <prefpane> element to the dialog. You can use this method to append dynamically created panes to the dialog.
openSubDialog(aURL, aFeatures, aParams) 
Opens a modal sub-dialog. 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.
openWindow(aWindowType, aURL, aFeatures, aParams) 
Opens the specified window or focuses an already open one with given window type. Use this method to open a non-modal window, like Exceptions window in Firefox Options.

Note that you can define an initWithParams() function in your 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 pattern is as follows:

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

  initWithParams(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()
}

<prefpane>

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

<prefpane> can have a src attribute specifying the overlay which provides the real content for it, or it can contain arbitrary XUL elements as its content. Using the first method can reduce time needed to load your Options window, if it's very large, as only a single pane needs to be loaded before the window can be shown to user.

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 an image to be used on the pane button. (does setting this at runtime have any effect??)
label 
The label for the pane button.
selected 
Indicates whether the pane is currently selected (active).
src 
See above, the URL of the overlay which provides content for the pane.

Properties

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

src 
Gets and sets the value of the src attribute.
selected 
Gets and sets the value of the selected attribute.
image 
Gets and sets the value of the image attribute.
label 
Gets and sets the value of the label attribute.
preferenceElements (readonly) 
A NodeList of child elements with preference attribute.
preferences (readonly) 
A NodeList of all child <preference> elements.
loaded (readonly) 
Indicates whether the pane is fully loaded. (?? while it's possible to set the value of the property, it's not recommended to do so. The property really ought to be readonly)
contentHeight (readonly) 
The height (in pixels) of current pane's content.

Methods

writePreferences(aFlushToDisk) 
Saves all <preference>s of the pane in user preferences, flushes to the disk (updating prefs.js) if aFlushToDisk is true.
preferenceForElement(aElement) 
Returns the <preference> element, which is specified in aElement's preference attribute.
getPreferenceElement(aStartElement) 
 ??
userChangedValue(aElement) 
 ??

<preferences>

Methods

fireChangedEvent(aPreference) 

Fields

service 
The preferences service (nsIPrefService).
rootBranch 
The root prefs branch (nsIPrefBranch).
defaultBranch 
The root branch with default values (nsIPrefBranch).
rootBranchInternal 
The root prefs branch (nsIPrefBranch2).


<preference>

Properties

instantApply 
preferences 
name 
type 
inverted 
readonly 
value 
locked 
disabled 
tabIndex 
hasUserValue 
defaultValue 
valueFromPreferences 

Methods

reset() 
setElementValue(aElement) 
getElementValue(aElement) 
isElementEditable(aElement) 
updateElements()