mozilla

Revision 125452 of extIPreferenceBranch

  • Revision slug: Toolkit_API/extIPreferenceBranch
  • Revision title: extIPreferenceBranch
  • Revision id: 125452
  • Created:
  • Creator: Clarkbw
  • Is current revision? No
  • Comment 2 words added, 2 words removed

Revision Content

{{ Fx_minversion_header("3") }}

{{ tb_minversion_header("3") }}

The extIPreferenceBranch interface provides simplified access to preferences. The interface has a predefined root preference branch. The root branch is set based on the context of the owner. For example, an extension's preferences has a root of "extensions.extensionid.", while the application-level preferences have an empty root. All preference "aName" parameters used in this interface are relative to the root branch. extIPreferenceBranch is defined in {{ source("toolkit/components/exthelper/extIApplication.idl") }}.

Implemented via XPCOM service for extIApplication: see the instructions on the FUEL (Firefox), STEEL (Thunderbird) and SMILE (SeaMonkey) pages.

Method overview

boolean has(in AString aName)
extIPreference get(in AString aName)
nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue)
void setValue(in AString aName, in nsIVariant aValue)
void reset()

Attributes

Attribute Type Description
root readonly attribute AString The name of the branch root.
all readonly attribute nsIVariant Array of extIPreference listing all preferences in this branch.
events readonly attribute extIEvents The events object for the preferences supports: "change"

Methods

has()

Check to see if a preference exists.

boolean has(in AString aName)
Parameters
aName
The name of preference
Return value

true if the preference exists, false if not

get()

Gets an object representing a preference

extIPreference get(in AString aName)
Parameters
aName
The name of preference
Return value

a preference object, or null if the preference does not exist

getValue()

Gets the value of a preference. Returns a default value if the preference does not exist.

nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue)
Parameters
aName
The name of a preference
aDefaultValue
The default value of a preference.  This will be passed back to you without any processing and can be something which would not be valid as a preference.  For example, null/undefined/an object.
Return value

The value of the preference or the given default value if preference does not exists.  The use of a variant as the return value means that to JavaScript code the value will appear as a value of the same type as is used in the preferences file and no coercion will occur.  A quoted string in the preference file will always appear as a string, even if the value of the string is "true" or "false".  An integer preference appears as a JavaScript Number, and a boolean appears as a JavaScript Boolean.  There are no other types supported by the preference subsystem.

setValue()

Sets the value of a preference with the given name.

void setValue(in AString aName, in nsIVariant aValue)
Parameters
aName
The name of a preference
aValue
The value of a preference
Return value

 

reset()

Resets all preferences in a branch back to their default values.

Note: This function has not been implemented and will raise an exception.  See
void reset()
Parameters
Return value

Examples

var myExt = Application.extensions.get('myapplicationid');

function myFunc (event) {
  Application.console.log('change!');
};

myExt.prefs.get("myprefname").events.addListener("change", myFunc);

See also

 FUEL (Firefox), STEEL (Thunderbird) and SMILE (SeaMonkey)

Known issues

Bug 488587 - Function registered as FUEL preference listener not always called

{{ languages( { "es": "es/FUEL/PreferenceBranch", "fr": "fr/FUEL/PreferenceBranch", "ja": "ja/FUEL/PreferenceBranch" } ) }}

Revision Source

<p>{{ Fx_minversion_header("3") }}</p>
<p>{{ tb_minversion_header("3") }}</p>
<p>The <code>extIPreferenceBranch</code> interface provides simplified access to preferences. The interface has a predefined root preference branch. The root branch is set based on the context of the owner. For example, an extension's preferences has a root of "<code>extensions.<em>extensionid</em>.</code>", while the application-level preferences have an empty root. All preference "<code>aName</code>" parameters used in this interface are relative to the root branch. <code>extIPreferenceBranch</code> is defined in {{ source("toolkit/components/exthelper/extIApplication.idl") }}.</p>
<p>Implemented via XPCOM service for <a class="internal" href="/en/Toolkit_API/extIApplication" title="en/Toolkit API/extIApplication"><code>extIApplication</code></a>: see the instructions on the <a class="internal" href="/en/Toolkit_API/FUEL" title="en/FUEL">FUEL</a> (Firefox), <a class="internal" href="/en/Toolkit_API/STEEL" title="en/Thunderbird/STEEL">STEEL</a> (Thunderbird) and <a class="internal" href="/en/Toolkit_API/SMILE" title="en/SeaMonkey/SMILE">SMILE</a> (SeaMonkey) pages.</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>boolean <a href="#has.28.29">has</a>(in AString aName)</code></td> </tr> <tr> <td><code><a href="/en/Toolkit_API/extIPreference" title="en/FUEL/Preference">extIPreference</a> <a href="#get.28.29">get</a>(in AString aName)</code></td> </tr> <tr> <td><code>nsIVariant <a href="#getValue.28.29">getValue</a>(in AString aName, in nsIVariant aDefaultValue)</code></td> </tr> <tr> <td><code>void <a href="#setValue.28.29">setValue</a>(in AString aName, in nsIVariant aValue)</code></td> </tr> <tr> <td><code>void <a href="#reset.28.29">reset</a>()</code></td> </tr> </tbody>
</table>
<h2 name="Attributes">Attributes</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>root</code></td> <td><code>readonly attribute AString</code></td> <td>The name of the branch root.</td> </tr> <tr> <td><code>all</code></td> <td><code>readonly attribute nsIVariant</code></td> <td>Array of <code>extIPreference</code> listing all preferences in this branch.</td> </tr> <tr> <td><code>events</code></td> <td><code>readonly attribute extIEvents</code></td> <td>The events object for the preferences supports: "change"</td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="has.28.29">has()</h3>
<p>Check to see if a preference exists.</p>
<pre class="eval">boolean has(in AString aName)
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>aName</code></dt> <dd>The name of preference</dd>
</dl>
<h6 name="Return_value">Return value</h6>
<p>true if the preference exists, false if not</p>
<h3 name="get.28.29">get()</h3>
<p>Gets an object representing a preference</p>
<pre class="eval">extIPreference get(in AString aName)
</pre>
<h6 name="Parameters_2">Parameters</h6>
<dl> <dt><code>aName</code></dt> <dd>The name of preference</dd>
</dl>
<h6 name="Return_value_2">Return value</h6>
<p>a preference object, or null if the preference does not exist</p>
<h3 name="getValue.28.29">getValue()</h3>
<p>Gets the value of a preference. Returns a default value if the preference does not exist.</p>
<pre class="eval">nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue)
</pre>
<h6 name="Parameters_3">Parameters</h6>
<dl> <dt><code>aName</code></dt> <dd>The name of a preference</dd> <dt><code>aDefaultValue</code></dt> <dd>The default value of a preference.  This will be passed back to you without any processing and can be something which would not be valid as a preference.  For example, null/undefined/an object.</dd>
</dl>
<h6 name="Return_value_3">Return value</h6>
<p>The value of the preference or the given default value if preference does not exists.  The use of a variant as the return value means that to JavaScript code the value will appear as a value of the same type as is used in the preferences file and no coercion will occur.  A quoted string in the preference file will always appear as a string, even if the value of the string is "true" or "false".  An integer preference appears as a JavaScript Number, and a boolean appears as a JavaScript Boolean.  There are no other types supported by the preference subsystem.</p>
<h3 name="setValue.28.29">setValue()</h3>
<p>Sets the value of a preference with the given name.</p>
<pre class="eval">void setValue(in AString aName, in nsIVariant aValue)
</pre>
<h6 name="Parameters_4">Parameters</h6>
<dl> <dt><code>aName</code></dt> <dd>The name of a preference</dd> <dt><code>aValue</code></dt> <dd>The value of a preference</dd>
</dl>
<h6 name="Return_value_4">Return value</h6>
<p> </p>
<h3 name="reset.28.29">reset()</h3>
<p>Resets all preferences in a branch back to their default values.</p>
<div class="note"><strong>Note:</strong> This function has not been implemented and will raise an exception.  See</div>
<pre class="eval">void reset()
</pre>
<h6 name="Parameters_5">Parameters</h6>
<h6 name="Return_value_5">Return value</h6><h2 name="Examples">Examples</h2>
<pre>var myExt = Application.extensions.get('myapplicationid');

function myFunc (event) {
  Application.console.log('change!');
};

myExt.prefs.get("myprefname").events.addListener("change", myFunc);
</pre>
<h2 name="See_also">See also</h2>
<p> <a class="internal" href="/en/Toolkit_API/FUEL" title="en/FUEL">FUEL</a> (Firefox), <a class="internal" href="/en/Toolkit_API/STEEL" title="en/Thunderbird/STEEL">STEEL</a> (Thunderbird) and <a class="internal" href="/en/Toolkit_API/SMILE" title="en/SeaMonkey/SMILE">SMILE</a> (SeaMonkey)</p>
<h2 name="See_also">Known issues</h2>
<p><a class=" link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=488587" title="https://bugzilla.mozilla.org/show_bug.cgi?id=488587">Bug 488587</a> - Function registered as FUEL preference listener not always called</p>
<p>{{ languages( { "es": "es/FUEL/PreferenceBranch", "fr": "fr/FUEL/PreferenceBranch", "ja": "ja/FUEL/PreferenceBranch" } ) }}</p>
Revert to this revision