MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla

Compare Revisions

Handling Preferences

Change Revisions

Revision 13518:

Revision 13518 by Jorge.villalobos on

Revision 13519:

Revision 13519 by Dao on

Title:
Handling Preferences
Handling Preferences
Slug:
XUL_School/Handling_Preferences
XUL_School/Handling_Preferences
Content:

Revision 13518
Revision 13519
n10    <h2>n10    <h2 id="Preferences_in_Firefox">
n52      The list in about:config is not complete. Some Firefox prefn52      The list in about:config is not complete. Some Firefox pref
>erences have no default value, so they are left out unless you ad>erences have no default value, so they are left out unless you ad
>d them manually. An extensive specification of Firefox preference>d them manually. An extensive specification of Firefox preference
>s can be seen <a class=" external" href="http://kb.mozillazine.or>s can be seen <a class="external" href="http://kb.mozillazine.org
>g/Category:Preferences">in this page</a>. You don't need to know >/Category:Preferences">in this page</a>. You don't need to know t
>them by heart; if doing task X requires some preference, then it'>hem by heart; if doing task X requires some preference, then it's
>s better to look for an explanation on how to do X rather than di> better to look for an explanation on how to do X rather than div
>ving into the preferences list and see if you can find the prefer>ing into the preferences list and see if you can find the prefere
>ence you need. MDC articles and other guides are usually good at >nce you need. MDC articles and other guides are usually good at s
>specifying the preferences you'll need to use.>pecifying the preferences you'll need to use.
53    </p>
54    <h2>53    </p>
54    <h2 id="Adding_preferences_to_an_extension">
n100    <h2>n100    <h2 id="Managing_Preferences_with_XPCOM">
101      Managing Preferences with FUEL
102    </h2>
103    <p>
104      <a href="/en/Toolkit_API/FUEL" title="en/FUEL">FUEL</a> is 
>a JS library integrated into Firefox that was meant to facilitate 
> extension development. It fell a little short of its goals, but  
>it is useful for preference handling. Firefox-based applications  
>like Flock include FUEL, and SeaMonkey includes a FUEL equivalent 
> called <a href="/en/Toolkit_API/SMILE" title="en/Toolkit API/SMI 
>LE">SMILE</a> since version 2. 
105    </p>
106    <p>
107      We modified our JSM sample extension so that it uses a pref
>erence instead of an internal variable. The main difference in fu 
>nctionality is that after closing Firefox and reopening it, our e 
>xtension remembers how many greetings have been displayed before. 
> The original extension only kept track of the greetings shown in 
> a browser session. This new version persists this number across  
>sessions. 
108    </p>
109    <p>
110      Since the only reason we used non-chrome code in the JSM sa
>mple extension was to store the message count in a single locatio 
>n, we can easily modify this new extension so that it uses chrome 
> code exclusively. There's no need for JavaScript Code Modules or 
> XPCOM anymore. We're making this point because using the FUEL li 
>brary from chrome code is slightly different thant using it from  
>non-chrome code. The difference lies in how to get the "root" <a  
>href="/en/Toolkit_API/extIApplication" title="en/FUEL/Application 
>">Application object</a>: 
111    </p>
112    <div class="code panel" style="border-width: 1px;">
113      <div class="codeContent panelContent">
114        <pre class="brush: js">
115// chrome code.
116Application.something
117 
118// non-chrome code.
119let application =
120  Cc["@mozilla.org/fuel/application;1"].getService(Ci.fuelIApplic
>ation); 
121application.something
122</pre>
123      </div>
124    </div>
125    <p>
126      In the chrome you have the global Application object ready 
>to use, while in non-chrome code you need to get it as an XPCOM s 
>ervice. It <em>is</em> an XPCOM service, with the difference that 
> it can be more easily accessed in the chrome. 
127    </p>
128    <div class="panel" style="border-width: 1px;">
129      <div class="panelContent">
130        <div class="note">
131          FUEL only works in Firefox 3 and above.
132        </div>
133      </div>
134    </div>
135    <p>
136      The Application object has a <em>prefs</em> property of typ
>e <a href="/en/Toolkit_API/extIPreferenceBranch" title="en/FUEL/P 
>referenceBranch">PreferenceBranch</a>. You can use it to manage p 
>references easily. 
137    </p>
138    <p>
139      First, you get an object that represents your preference:
140    </p>
141    <div class="code panel" style="border-width: 1px;">
142      <div class="codeContent panelContent">
143        <pre class="brush: js">
144this._countPref =
145  application.prefs.get("extensions.xulschoolhello.message.count"
>); 
146</pre>
147      </div>
148    </div>
149    <p>
150      Then you can get or set its value using the <em>value</em> 
>property. 
151    </p>
152    <div class="code panel" style="border-width: 1px;">
153      <div class="codeContent panelContent">
154        <pre class="brush: js">
155/**
156 * Returns the current message count.
157 * @return the current message count.
158 */
159get count() { return this._countPref.value; },
160 
161/**
162 * Increments the message count by one.
163 */
164increment : function() {
165  this._countPref.value++;
166}
167</pre>
168      </div>
169    </div>
170    <p>
171      The <em>prefs</em> object also has methods that allow you t
>o get and set preference values directly, but we prefer this appr 
>oach. 
172    </p>
173    <h4>
174      Preference Listeners
175    </h4>
176    <p>
177      Sometimes you'll want to be notified when a preference chan
>ges its value. For example, if we wanted to have a display of the 
> message count somewhere in the browser, we should use a preferen 
>ce listener to keep it up to date. This way we know we have the r 
>ight value even if the user changes it manually in about:config. 
178    </p>
179    <p>
180      To do this in FUEL, add an event listener for the "change" 
>event: 
181    </p>
182    <div class="code panel" style="border-width: 1px;">
183      <div class="codeContent panelContent">
184        <pre class="brush: js">
185this._countPref.events.addListener("change", this);
186</pre>
187      </div>
188    </div>
189    <p>
190      The listener object should implement the <a href="/en/Toolk
>it_API/extIEventListener" title="en/FUEL/EventListener">EventList 
>ener</a> interface. Similarly to observers, all you need to do is 
> have a <em>handleEvent</em> method in a JS object. Or you can us 
>e an anonymous function that takes an <a href="/en/Toolkit_API/ex 
>tIEventItem" title="en/FUEL/EventItem">EventItem</a> object. 
191    </p>
192    <div class="code panel" style="border-width: 1px;">
193      <div class="codeContent panelContent">
194        <pre class="brush: js">
195this._countPref.events.addListener("change", function(aEvent) { /
>* do stuff. */ }); 
196</pre>
197      </div>
198    </div>
199    <p>
200      Always remember to remove listeners when you don't need the
>m anymore. 
201    </p>
202    <h2>
n209      We use the <a href="/en/nsIPrefBranch" title="en/NsIPrefBran107      We use the <a href="/en/XPCOM_Interface_Reference/nsIPrefBr
>nch">Preferences Service</a> in order to get and set preference v>anch" title="en/NsIPrefBranch">Preferences Service</a> in order t
>alues:>o get and set preference values:
n232    <h4>n130    <h4 id="Preference_Listeners">
t276    <h2>t174    <h2 id="Preference_Windows">

Back to History