mozilla

Revision 295390 of Using preferences from application code

  • Revision slug: Mozilla/Preferences/Using_preferences_from_application_code
  • Revision title: Using preferences from application code
  • Revision id: 295390
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment

Revision Content

{{ gecko_minversion_header("6.0") }}

{{ draft() }}

Firefox 6 introduced static functions, as part of the C++ Preferences class, for accessing preferences efficiently from within application code. This API is not available for add-ons, but if you're working on a Gecko application, this API is the preferred way to access preferences.

Due to the relatively limited target audience for this API, we don't have a thorough API reference at this time (although if you have some time, feel free to add one!). The examples below and the self-explanatory nature of most of the API should do the trick. Take a look at the source: {{ Source("modules/libpref/public/Preferences.h") }}.

Method overview

static bool GetBool(const char* aPref, bool aDefault = false);
static PRInt32 GetInt(const char* aPref, PRInt32 aDefault = 0);
static PRUint32 GetUint(const char* aPref, PRUint32 aDefault = 0);
static nsAdoptingCString GetCString(const char* aPref);
static nsAdoptingString GetString(const char* aPref);
static nsAdoptingCString GetLocalizedCString(const char* aPref);
static nsAdoptingString GetLocalizedString(const char* aPref);
static nsresult GetBool(const char* aPref, bool* aResult);
static nsresult GetInt(const char* aPref, PRInt32* aResult);
static nsresult GetUint(const char* aPref, PRUint32* aResult);
static nsresult GetCString(const char* aPref, nsACString* aResult);
static nsresult GetString(const char* aPref, nsAString* aResult);
static nsresult GetLocalizedCString(const char* aPref, nsACString* aResult);
static nsresult GetLocalizedString(const char* aPref, nsAString* aResult);
static nsresult GetComplex(const char* aPref, const nsIID &aType, void** aResult);
static nsresult SetBool(const char* aPref, bool aValue);
static nsresult SetInt(const char* aPref, PRInt32 aValue);
static nsresult SetUint(const char* aPref, PRUint32 aValue);
static nsresult SetCString(const char* aPref, const char* aValue);
static nsresult SetCString(const char* aPref, const nsACString &aValue);
static nsresult SetString(const char* aPref, const PRUnichar* aValue);
static nsresult SetString(const char* aPref, const nsAString &aValue);
static nsresult SetComplex(const char* aPref, const nsIID &aType, nsISupports* aValue);
static nsresult ClearUser(const char* aPref);
static bool HasUserValue(const char* aPref);
static nsresult AddStrongObserver(nsIObserver* aObserver, const char* aPref);
static nsresult AddWeakObserver(nsIObserver* aObserver, const char* aPref);
static nsresult RemoveObserver(nsIObserver* aObserver, const char* aPref);
static nsresult AddStrongObservers(nsIObserver* aObserver, const char** aPrefs);
static nsresult AddWeakObservers(nsIObserver* aObserver, const char** aPrefs);
static nsresult RemoveObservers(nsIObserver* aObserver, const char** aPrefs);
static nsresult RegisterCallback(PrefChangedFunc aCallback, const char* aPref, void* aClosure = nsnull);
static nsresult UnregisterCallback(PrefChangedFunc aCallback, const char* aPref, void* aClosure = nsnull);
static nsresult AddBoolVarCache(bool* aVariable, const char* aPref, bool aDefault = false);
static nsresult AddIntVarCache(PRInt32* aVariable, const char* aPref, PRInt32 aDefault = 0);
static nsresult AddUintVarCache(PRUint32* aVariable, const char* aPref, PRUint32 aDefault = 0);
static nsresult GetDefaultBool(const char* aPref, bool* aResult);
static nsresult GetDefaultInt(const char* aPref, PRInt32* aResult);
static nsresult GetDefaultUint(const char* aPref, PRUint32* aResult);
static bool GetDefaultBool(const char* aPref, bool aFailedResult);
static PRInt32 GetDefaultInt(const char* aPref, PRInt32 aFailedResult);
static PRUint32 GetDefaultUint(const char* aPref, PRUint32 aFailedResult);
static nsAdoptingString GetDefaultString(const char* aPref);
static nsAdoptingCString GetDefaultCString(const char* aPref);
static nsAdoptingString GetDefaultLocalizedString(const char* aPref);
static nsAdoptingCString GetDefaultLocalizedCString(const char* aPref);
static nsresult GetDefaultCString(const char* aPref, nsACString* aResult);
static nsresult GetDefaultString(const char* aPref, nsAString* aResult);
static nsresult GetDefaultLocalizedCString(const char* aPref, nsACString* aResult);
static nsresult GetDefaultLocalizedString(const char* aPref, nsAString* aResult);
static nsresult GetDefaultComplex(const char* aPref, const nsIID &aType, void** aResult);

Examples

Simply retrieving the value of a Boolean preference can be done like this:

PRBool myPref = Preferences::GetBool("preference.name.string", PR_TRUE);

This returns the value of the preference named "preference.name.string", using the default value PR_TRUE if the preference doesn't exist.

See also

Revision Source

<p>{{ gecko_minversion_header("6.0") }}</p>
<p>{{ draft() }}</p>
<p>Firefox 6 introduced static functions, as part of the C++&nbsp;<code>Preferences</code> class, for accessing preferences efficiently from within application code. This API is not available for add-ons, but if you're working on a Gecko application, this API is the preferred way to access preferences.</p>
<p>Due to the relatively limited target audience for this API, we don't have a thorough API reference at this time (although if you have some time, feel free to add one!). The examples below and the self-explanatory nature of most of the API should do the trick. Take a look at the source:&nbsp;{{ Source("modules/libpref/public/Preferences.h") }}.</p>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td><code>static bool GetBool(const char* aPref, bool aDefault = false);</code></td>
    </tr>
    <tr>
      <td><code>static PRInt32 GetInt(const char* aPref, PRInt32 aDefault = 0);</code></td>
    </tr>
    <tr>
      <td><code>static PRUint32 GetUint(const char* aPref, PRUint32 aDefault = 0);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingCString GetCString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingString GetString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingCString GetLocalizedCString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingString GetLocalizedString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetBool(const char* aPref, bool* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetInt(const char* aPref, PRInt32* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetUint(const char* aPref, PRUint32* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetCString(const char* aPref, nsACString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetString(const char* aPref, nsAString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetLocalizedCString(const char* aPref, nsACString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetLocalizedString(const char* aPref, nsAString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetComplex(const char* aPref, const nsIID &amp;aType, void** aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetBool(const char* aPref, bool aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetInt(const char* aPref, PRInt32 aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetUint(const char* aPref, PRUint32 aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetCString(const char* aPref, const char* aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetCString(const char* aPref, const nsACString &amp;aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetString(const char* aPref, const PRUnichar* aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetString(const char* aPref, const nsAString &amp;aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult SetComplex(const char* aPref, const nsIID &amp;aType, nsISupports* aValue);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult ClearUser(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static bool HasUserValue(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddStrongObserver(nsIObserver* aObserver, const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddWeakObserver(nsIObserver* aObserver, const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult RemoveObserver(nsIObserver* aObserver, const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddStrongObservers(nsIObserver* aObserver, const char** aPrefs);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddWeakObservers(nsIObserver* aObserver, const char** aPrefs);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult RemoveObservers(nsIObserver* aObserver, const char** aPrefs);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult RegisterCallback(PrefChangedFunc aCallback, const char* aPref, void* aClosure = nsnull);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult UnregisterCallback(PrefChangedFunc aCallback, const char* aPref, void* aClosure = nsnull);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddBoolVarCache(bool* aVariable, const char* aPref, bool aDefault = false);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddIntVarCache(PRInt32* aVariable, const char* aPref, PRInt32 aDefault = 0);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult AddUintVarCache(PRUint32* aVariable, const char* aPref, PRUint32 aDefault = 0);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultBool(const char* aPref, bool* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultInt(const char* aPref, PRInt32* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultUint(const char* aPref, PRUint32* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static bool GetDefaultBool(const char* aPref, bool aFailedResult);</code></td>
    </tr>
    <tr>
      <td><code>static PRInt32 GetDefaultInt(const char* aPref, PRInt32 aFailedResult);</code></td>
    </tr>
    <tr>
      <td><code>static PRUint32 GetDefaultUint(const char* aPref, PRUint32 aFailedResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingString GetDefaultString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingCString GetDefaultCString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingString GetDefaultLocalizedString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsAdoptingCString GetDefaultLocalizedCString(const char* aPref);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultCString(const char* aPref, nsACString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultString(const char* aPref, nsAString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultLocalizedCString(const char* aPref, nsACString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultLocalizedString(const char* aPref, nsAString* aResult);</code></td>
    </tr>
    <tr>
      <td><code>static nsresult GetDefaultComplex(const char* aPref, const nsIID &amp;aType, void** aResult);</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Examples">Examples</h2>
<p>Simply retrieving the value of a Boolean preference can be done like this:</p>
<pre>
PRBool myPref = Preferences::GetBool("preference.name.string", PR_TRUE);
</pre>
<p>This returns the value of the preference named "preference.name.string", using the default value <code>PR_TRUE</code>&nbsp;if the preference doesn't exist.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en/Preferences" title="en/Preferences">Preferences</a></li>
</ul>
Revert to this revision