Using preferences from application code

This article is in need of a technical review.

Draft
This page is not complete.

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: 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

Document Tags and Contributors

Contributors to this page: Sheppy, Neil, jhammel, kscarfone
Last updated by: kscarfone,