mozilla

Compare Revisions

Preferences system

Change Revisions

Revision 94009:

Revision 94009 by Callek on

Revision 94010:

Revision 94010 by AsafRomano on

Title:
Preferences system
Preferences system
Slug:
Mozilla/Preferences/Preferences_system
Mozilla/Preferences/Preferences_system
Tags:
XUL, "Preferences system"
XUL, "Preferences system"
Content:

Revision 94009
Revision 94010
n74      <code>void setElementValue(in DOMElement element);</code> -n74      <code>void setElementValue(in DOMElement element);</code> -
> initializes the supplied element from the value stored in the pr> initializes the supplied element from the value stored in the pr
>eference. This function calls <code>onpreferenceread</code>>eference. This function calls <code>onsyncfrompreference</code>
75    </p>
76    <p>75    </p>
76    <p>
77      <code>type getElementValue(in DOMElement element);</code> -77      <code>type getElementValue(in DOMElement element);</code> -
> retrieves the value that should be written to preferences based > retrieves the value that should be written to preferences based 
>on the current state of the supplied element. This function calls>on the current state of the supplied element. This function calls
> <code>onpreferencewrite</code>> <code>onsynctopreference</code>
n82    <h5 name="onpreferenceread.2Fonpreferencewrite">n82    <h5 name="onsyncfrompreference.2Fonsynctopreference">
83      onpreferenceread/onpreferencewrite83      onsyncfrompreference/onsynctopreference
84    </h5>
85    <p>84    </h5>
85    <p>
86      Often you will have UI whose construction does not map easi86      Often you will have UI whose construction does not map easi
>ly to a given preference type. For example, you may have a checkb>ly to a given preference type. For example, you may have a checkb
>ox that is checked when an integer preference value is 3 and not >ox that is checked when an integer preference value is 3 and not 
>when it's 2. To initialize this UI element you can't rely on the >when it's 2. To initialize this UI element you can't rely on the 
>default initialization routine, since both values are meaningless>default initialization routine, since both values are meaningless
> to the checkbox element. You need to write translation functions> to the checkbox element. You need to write translation functions
> to translate the preference value into an initialization value f> to translate the preference value into an initialization value f
>or the UI element, and to translate the UI element's value into s>or the UI element, and to translate the UI element's value into s
>omething to write to the preferences file. This is what onprefere>omething to write to the preferences file. This is what onsyncfro
>nceread/ onpreferencewrite are for.>mpreference/ onsynctopreference are for.
87    </p>
88    <p>87    </p>
88    <p>
89      <code>onpreferenceread</code> is called when an element is 89      <code>onsyncfrompreference</code> is called when an element
>initialized from preferences. If you supply an implementation of > is initialized from preferences. If you supply an implementation
>this event, your implementation will be invoked during initializa> of this event, your implementation will be invoked during initia
>tion and you can return the value with which to initialize the UI>lization and you can return the value with which to initialize th
> element with, or <code>undefined</code> to tell the preferences >e UI element with, or <code>undefined</code> to tell the preferen
>system to initialize the UI element with the default value (i.e. >ces system to initialize the UI element with the default value (i
>to attempt to initialize with the preference value). In the above>.e. to attempt to initialize with the preference value). In the a
> example, you might write the checkbox like this:>bove example, you might write the checkbox like this:
n92<code>    &lt;checkbox preference="foo.bar" onpreferenceread="retn92<code>    &lt;checkbox preference="foo.bar" onsyncfrompreference=
>urn onPreferenceRead();"/&gt;>"return onsyncfrompreference();"/&gt;
n96    function onPreferenceRead()n96    function onsyncfrompreference()
n108      <code>onpreferencewrite</code> is called when preferences an108      <code>onsynctopreference</code> is called when preferences 
>re being written - the preferences system asks each element to tr>are being written - the preferences system asks each element to t
>anslate its current state into a value suitable for writing to th>ranslate its current state into a value suitable for writing to t
>e specified preference. You can return a special value or <code>u>he specified preference. You can return a special value or <code>
>ndefined</code> to tell the preferences system to use its standar>undefined</code> to tell the preferences system to use its standa
>d means for obtaining the value. In the above example:>rd means for obtaining the value. In the above example:
n111<code>    &lt;checkbox preference="foo.bar" onpreferencewrite="ren111<code>    &lt;checkbox preference="foo.bar" onsynctopreference="r
>turn onPreferenceWrite();"/&gt;>eturn onsynctopreference();"/&gt;
n116    function onPreferenceWrite()n116    function onsynctopreference()
t191      <code>void userChangedValue(in DOMElement element);</code> t191      <code>void userChangedValue(in DOMElement element);</code> 
>- The user changed the value in a widget that the preferences sys>- The user changed the value in a widget that the preferences sys
>tem does not automatically track state changes for (1) and the pr>tem does not automatically track state changes for (1) and the pr
>eference element associated with the widget should be updated bas>eference element associated with the widget should be updated bas
>ed on the state held by the widget. For example, if you are using>ed 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> 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 > as adding or removing an item) and you want to sync the changes 
>back to a preference, you must write an onpreferencewrite handler>back to a preference, you must write an onsynctopreference handle
> for your listbox that returns the value to be written to the pre>r for your listbox that returns the value to be written to the pr
>ference element, and then call the <code>userChangedValue</code> >eference element, and then call the <code>userChangedValue</code>
>function every time you edit the list in a way that should cause > function every time you edit the list in a way that should cause
>the preference's value to change.> the preference's value to change.

Back to History