MozillaZine

Preferences bindings

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 08:39, 8 July 2005
Asqueella (Talk | contribs)
(onpreferenceread/onpreferencewrite -> onsyncfrompreference/onsynctopreference)
<-- Previous diff
Revision as of 03:01, 9 July 2005
Asqueella (Talk | contribs)
(New elements - moving to devmo)
Next diff -->
Line 22: Line 22:
* ... * ...
-= New elements = 
-== <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 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 === 
-; <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. 
- 
-=== Properties === 
-; <code>preferencePanes</code> (readonly) : A <code>NodeList</code> of <code><prefpane></code> elements. 
-; <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>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>.) 
- 
-=== Methods === 
-; <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>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. 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> : 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> == 
-<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. (Changing this attribute at runtime does not update the pane button image). 
-; <code>label</code> : The label for the pane button. 
-; <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. 
- 
-=== 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>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. (Setting this property at runtime does not have effect). 
-; <code>label</code> : Gets and sets the value of the <code>label</code> attribute. (Setting this property at runtime does not have effect). 
-; <code>preferenceElements</code> (readonly) : A <code>NodeList</code> of child elements with <code>preference</code> attribute. 
-; <code>preferences</code> (readonly) : A <code>NodeList</code> of all child <code><preference></code> elements. 
-; <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> (readonly) : The height (in pixels) of current pane's content. 
- 
-=== Methods === 
-; <code>writePreferences(flushToDisk)</code> : Saves all <code><preference></code>s of the pane in user preferences, optionally flushes to the disk (updating <tt>prefs.js</tt>) if <code>aFlushToDisk</code> is <code>true</code>. 
-; <code>preferenceForElement(element)</code> : Returns the <code><preference></code> element, which is being observed by the supplied element (i.e. which is specified in <code>aElement</code>'s <code>preference</code> attribute.) 
-; <code>getPreferenceElement(startElement)</code> : ?? 
-; <code>userChangedValue(element)</code> : ?? 
- 
-=== Events === 
-; <code>paneload</code> : This event is fired on the pane element when the pane is loaded (e.g. after the overlay is merged.) You can put the handler for the event in <code>onpaneload</code> attribute on the element. 
- 
-== <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> 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 === 
-; <code>fireChangedEvent(preference)</code> : Creates and dispatches a <code>changed</code> (non-bubbling) event to the specified <code>preference</code> element. Also executes code specified in <code>onchanged</code> attribute of the element. See also the description of <code>change</code> event of <code><preference></code>. 
- 
-=== Fields === 
-; <code>service</code> : The preferences service (<code>nsIPrefService</code>). 
-; <code>rootBranch</code> : The root prefs branch (<code>nsIPrefBranch</code>). 
-; <code>defaultBranch</code> : The root branch with default values (<code>nsIPrefBranch</code>). 
-; <code>rootBranchInternal</code> : The root prefs branch (<code>nsIPrefBranch2</code>). 
- 
-== <preference> == 
-<code><preference></code> is an element that is used as an intermediary between UI elements and items in user preferences. It must be a direct child of <code><preferences></code>. 
- 
-=== Attributes === 
-; <code>id</code> : The id of the element, it's used as a value of <code>preference</code> attribute on UI elements. 
-; <code>name</code> : The preference it controls (e.g. <tt>browser.preferences.instantApply</tt>). 
-; <code>type</code> : The type of the preference. Possible values are: <code>int</code>, <code>bool</code>, <code>string</code> (for non-unicode (ASCII) strings), <code>wstring</code> (like [[Dev_:_Using_preferences#nsIPrefLocalizedString|<code>nsIPrefLocalizedString</code>]]), <code>unichar</code> (unicode string), <code>file</code> (<code>nsIFile</code>). 
-; <code>inverted</code> : (Applies only to prefs with <code>type="bool"</code>.) When this is set to <code>true</code>, the value on the associated UI element is a negation of the value stored in user preferences. 
-; <code>readonly</code> : ?? 
-; <code>instantApply</code> : You can set this attribute to <code>true</code> to make the preference apply instantly, even when the global setting is not to use instant apply. 
- 
-=== Properties === 
-; <code>instantApply</code> (readonly) : Whether to use ''instant apply'' for this preference. This is <code>true</code> if either the element has an <code>instantApply</code> attribute set to <code>true</code>, or the <code><prefwindow></code>'s <code>instantApply</code> property is <code>true</code>. (But note [https://bugzilla.mozilla.org/show_bug.cgi?id=293439 bug 293439].) 
-; <code>preferences</code> (readonly) : Parent <code><preferences></code> element. 
-; <code>name</code> : Gets and sets the value of the <code>name</code> attribute. 
-; <code>type</code> : Gets and sets the value of the <code>type</code> attribute. 
-; <code>inverted</code> : Gets and sets the value of the <code>inverted</code> attribute. 
-; <code>readonly</code> : Gets and sets the value of the <code>readonly</code> attribute. 
-; <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> (readonly) : Returns <code>true</code> if the preference is ''locked''. 
-; <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> : 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> (readonly) : Returns <code>true</code> if the preference has a user value set. 
-; <code>defaultValue</code> (readonly) : Returns the default value of the preference. 
-; <code>valueFromPreferences</code> : Gets and sets the value stored in the user preference, specified in <code>name</code>. 
- 
-=== Methods === 
-; <code>getElementValue(element)</code> : Retrieves the value that should be written to preferences based on the current state of the supplied element. This function calls <code>onpreferencewrite</code>. 
-; <code>isElementEditable(element)</code> : Returns <code>true</code>, if the given element is "editable" (see below). 
-; <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(element)</code> : Initializes the supplied element from the value stored in the preference. This function calls <code>onpreferenceread</code>. 
-; <code>updateElements()</code> : Update all elements that observe this preference. 
- 
-=== Events === 
-; <code>change</code> : This event is dispatched to the <code><preference></code> element, when its value (according to preferences service) changes. The <code>onchange</code> attribute may be used to handle the event. 
= New attributes = = New attributes =

Revision as of 03:01, 9 July 2005

Work in progress See also this forum thread.

This document describes the new XBL bindings introduced in Deer Park Alpha 1 (aka Firefox 1.1a 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:

  • sort alphabetically
  • review the doc, do something about things marked '??'.
  • describe platform specific features:
    • instant apply
    • animation
  • (maybe) 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 attributes

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

  • onsyncfrompreference/onsynctopreference (onpreferenceread/onpreferencewrite in Deer Park Alpha 1) [1]
  • preference-editable
  • preference

Example(s)

See the forum thread for now.