MozillaZine

Preferences bindings

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 00:00, 30 May 2005
Asqueella (Talk | contribs)
(<preference>)
<-- Previous diff
Revision as of 22:21, 30 May 2005
Asqueella (Talk | contribs)

Next diff -->
Line 1: Line 1:
: '''''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.'' : '''''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 document describes the new [[XBL]] bindings introduced in Toolkit 1.1, which allow you write preferences UI faster, using less [[JavaScript]] code.+This document describes the new [[XBL]] bindings introduced in [[Deer Park|Firefox 1.1a]] (<small>aka Deer Park Alpha 1 and Firefox 1.1 Developer Preview Release</small>) and other Toolkit 1.1 applications, which allow you write Options (Preferences) UI faster, using less [[JavaScript]] code.
-== todo ==+This is not official yet. May be incomplete, contain any kinds of mistakes and typos etc. Please, if you see one, either fix it or note it on the [[Talk:Preferences bindings|talk page]].
 + 
 += To-do =
Todo: Todo:
-* list attributes too+* document new common attributes
* more detailed descriptions * more detailed descriptions
-* mark readonly properties as such 
* sort alphabetically * sort alphabetically
* check correctness * check correctness
- +* Review notes marked with '??'. File bugs as needed
-* platform specific issues: +* describe platform specific features:
** instant apply ** instant apply
** animation ** animation
-* examples+* simple example(s)
__TOC__ __TOC__
 += Why =
 +Describe the benefits of the new system:
 +* Use of declarative language (XUL elements/attributes) to associate UI controls with user preferences, less JS is needed
 +* More natural feel on Linux/Mac OS: instantapply/animation
 +* ...
 +
 += New elements =
 +
== <prefwindow> == == <prefwindow> ==
-<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.+<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 applications based on Toolkit 1.1 or later (e.g. Firefox 1.1 or Thunderbird 1.1).
The following attributes, properties and methods are available. The following attributes, properties and methods are available.
=== Attributes === === Attributes ===
-Please see [http://forums.mozillazine.org/viewtopic.php?t=263028]+; <code>type</code> : Must be either <code>"prefwindow"</code> or <code>"child"</code>. Use the former on the main prefwindow, and the latter for the subdialogs.<br/> Child prefwindows read initial values for their preferences from their opener, not from the preferences service. They also don't save the preferences to the preferences service when closed - only clicking OK on the main prefwindow does that. (Can child windows have prefpanes??)
 +; <code>lastSelected</code> : The <code>id</code> of the last selected pane. Used to reopen that pane when the Options window is opened next time. (interCaps in an attribute??)
=== Properties === === Properties ===
Line 30: Line 40:
; <code>type</code> (readonly) : Returns the value of the <code>type</code> attribute. ; <code>type</code> (readonly) : Returns the value of the <code>type</code> attribute.
; <code>lastSelected</code> (readonly) : Returns the value of the <code>lastSelected</code> attribute. ; <code>lastSelected</code> (readonly) : Returns the value of the <code>lastSelected</code> attribute.
-; <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>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 <code><field></code>, so you ''can'' set the value, however I don't believe it's valid to do that.)
; <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>.) ; <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>.)
Line 64: Line 74:
; <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>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>label</code> : The label for the pane button.
-; <code>selected</code> : Indicates whether the pane is currently selected (active).+; <code>selected</code> : Indicates whether the pane is currently selected (active). (?? Setting this at design-time doesn't work, use <code>lastSelected</code> attribute of <code><prefwindow></code> instead.)
; <code>src</code> : See above, the URL of the overlay which provides content for the pane. ; <code>src</code> : See above, the URL of the overlay which provides content for the pane.
Line 86: Line 96:
== <preferences> == == <preferences> ==
<code><preferences></code> is a container element for <code><preference></code> elements. It's supposed to be a child of <code><prefpane></code> element. <code><preferences></code> is a container element for <code><preference></code> elements. It's supposed to be a child of <code><prefpane></code> element.
 +
 +<code><preferences></code> element should contain one or more <code><preference></code> elements.
 +
 +=== Attributes ===
 +This element doesn't offer any additional attributes over those common to all XUL elements.
=== Methods === === Methods ===
Line 107: Line 122:
=== Properties === === Properties ===
-; <code>instantApply</code> : +; <code>instantApply</code> (readonly) : Indicates whether the Options window is in "instant apply" mode. The value is read from <code>browser.preferences.instantApply</code> boolean user preference.
-; <code>preferences</code> : +; <code>preferences</code> (readonly) : Parent <code><preferences></code> element.
-; <code>name</code> : +; <code>name</code> : Gets and sets the value of the <code>name</code> attribute.
-; <code>type</code> : +; <code>type</code> : Gets and sets the value of the <code>type</code> attribute.
-; <code>inverted</code> : +; <code>inverted</code> : Gets and sets the value of the <code>inverted</code> attribute.
-; <code>readonly</code> : +; <code>readonly</code> : Gets and sets the value of the <code>readonly</code> attribute.
-; <code>value</code> : +; <code>value</code> : The current value of the preference. If instantApply is on, this is always equal to <code>valueFromPreferences</code>. Otherwise, it's the current value of associated UI elements, i.e. what user currently sees.
-; <code>locked</code> : +; <code>locked</code> (readonly) : Returns <code>true</code> if the preference is ''locked''.
-; <code>disabled</code> : +; <code>disabled</code> : Gets/sets the value of <code>disabled</code> attribute, also updating <code>disabled</code> property of associated UI elements. (but initial value of attribute doesn't seem to have any effect??)
-; <code>tabIndex</code> : +; <code>tabIndex</code> : Gets/sets the value of <code>tabindex</code> attribute, also updating tab index of associated UI elements. (?? same comment as for <code>disabled</code>)
-; <code>hasUserValue</code> : +; <code>hasUserValue</code> (readonly) : Returns <code>true</code> if the preference has a user value set.
-; <code>defaultValue</code> : +; <code>defaultValue</code> (readonly) : Returns the default value of the preference.
-; <code>valueFromPreferences</code> : +; <code>valueFromPreferences</code> : Gets and sets the value stored in the user preference, specified in <code>name</code>.
=== Methods === === Methods ===
-; <code>reset()</code> : +; <code>reset()</code> : Resets the preference to its default value. '''Note:''' this method throws an exception if the preference doesn't have a user value set yet. (Is this intended behavior??)
-; <code>setElementValue(aElement)</code> : +; <code>setElementValue(aElement)</code> : Updates the <code>value</code> of given UI element <code>aElement</code>. See Notes section below. You shouldn't need to call this method manually. (Is this a public method??)
-; <code>getElementValue(aElement)</code> : +; <code>getElementValue(aElement)</code> : Returns the value of given UI element <code>aElement</code> to be saved to the preferences. See Notes section below. You shouldn't need to call this method manually. (Is this a public method??)
-; <code>isElementEditable(aElement)</code> : +; <code>isElementEditable(aElement)</code> : Returns <code>true</code>, if the given element is "editable" (see below).
-; <code>updateElements()</code> :+; <code>updateElements()</code> : Calls <code>setElementValue()</code> for all elements associated with this preference. You shouldn't need to call this method manually. (Is this a public method??)
 + 
 += New attributes =
 +The following attributes may be put on any element in the prefwindow:
 +* onpreferenceread/write [https://bugzilla.mozilla.org/show_bug.cgi?id=287111]
 +* preference-editable
 +* preference
 + 
 += Example(s) =
 +See the forum thread for now.

Revision as of 22:21, 30 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 Firefox 1.1a (aka Deer Park Alpha 1 and Firefox 1.1 Developer Preview Release) and other Toolkit 1.1 applications, which allow you write Options (Preferences) UI faster, using less JavaScript code.

This is not official yet. May be incomplete, contain any kinds of mistakes and typos etc. Please, if you see one, either fix it or note it on the talk page.

To-do

Todo:

  • document new common attributes
  • more detailed descriptions
  • sort alphabetically
  • check correctness
  • Review notes marked with '??'. File bugs as needed
  • describe platform specific features:
    • instant apply
    • animation
  • simple example(s)

Contents

Why

Describe the benefits of the new system:

  • Use of declarative language (XUL elements/attributes) to associate UI controls with user preferences, less JS is needed
  • More natural feel on Linux/Mac OS: instantapply/animation
  • ...

New elements

<prefwindow>

<prefwindow> is a top-level element, like <window> or <dialog. You should use it when creating Options dialog for applications based on Toolkit 1.1 or later (e.g. Firefox 1.1 or Thunderbird 1.1).

The following attributes, properties and methods are available.

Attributes

type 
Must be either "prefwindow" or "child". Use the former on the main prefwindow, and the latter for the subdialogs.
Child prefwindows read initial values for their preferences from their opener, not from the preferences service. They also don't save the preferences to the preferences service when closed - only clicking OK on the main prefwindow does that. (Can child windows have prefpanes??)
lastSelected 
The id of the last selected pane. Used to reopen that pane when the Options window is opened next time. (interCaps in an attribute??)

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 <field>, 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). (?? 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.

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>

<preferences> is a container element for <preference> elements. It's supposed to be a child of <prefpane> element.

<preferences> element should contain one or more <preference> elements.

Attributes

This element doesn't offer any additional attributes over those common to all XUL elements.

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>

<preference> is an element that is used as an intermediary between UI elements and items in user preferences. It must be a direct child of <preferences>.

Attributes

id 
The id of the element, it's used as a value of preference attribute on UI elements.
name 
The preference it controls (e.g. browser.preferences.instantApply).
type 
The type of the preference. Possible values are: int, bool, string (for non-unicode (ASCII) strings), wstring (like nsIPrefLocalizedString), unichar (unicode string), file (nsIFile).
inverted 
(Applies only to prefs with type="bool".) When this is set to true, the value on the associated UI element is a negation of the value stored in user preferences.
readonly 
 ??

Properties

instantApply (readonly) 
Indicates whether the Options window is in "instant apply" mode. The value is read from browser.preferences.instantApply boolean user preference.
preferences (readonly) 
Parent <preferences> element.
name 
Gets and sets the value of the name attribute.
type 
Gets and sets the value of the type attribute.
inverted 
Gets and sets the value of the inverted attribute.
readonly 
Gets and sets the value of the readonly attribute.
value 
The current value of the preference. If instantApply is on, this is always equal to valueFromPreferences. Otherwise, it's the current value of associated UI elements, i.e. what user currently sees.
locked (readonly) 
Returns true if the preference is locked.
disabled 
Gets/sets the value of disabled attribute, also updating disabled property of associated UI elements. (but initial value of attribute doesn't seem to have any effect??)
tabIndex 
Gets/sets the value of tabindex attribute, also updating tab index of associated UI elements. (?? same comment as for disabled)
hasUserValue (readonly) 
Returns true if the preference has a user value set.
defaultValue (readonly) 
Returns the default value of the preference.
valueFromPreferences 
Gets and sets the value stored in the user preference, specified in name.

Methods

reset() 
Resets the preference to its default value. Note: this method throws an exception if the preference doesn't have a user value set yet. (Is this intended behavior??)
setElementValue(aElement) 
Updates the value of given UI element aElement. See Notes section below. You shouldn't need to call this method manually. (Is this a public method??)
getElementValue(aElement) 
Returns the value of given UI element aElement to be saved to the preferences. See Notes section below. You shouldn't need to call this method manually. (Is this a public method??)
isElementEditable(aElement) 
Returns true, if the given element is "editable" (see below).
updateElements() 
Calls setElementValue() for all elements associated with this preference. You shouldn't need to call this method manually. (Is this a public method??)

New attributes

The following attributes may be put on any element in the prefwindow:

  • onpreferenceread/write [1]
  • preference-editable
  • preference

Example(s)

See the forum thread for now.