nsIPrefBranch

IID:56c35506-f14b-11d3-99d3-ddbfac2ccf65
Inherits From:nsISupports
Status:FROZEN

The nsIPrefBranch interface is used to manipulate the preferences data. This object may be obtained from the preferences service (nsIPrefService) and used to get and set default and/or user preferences across the application.

This object is created with a "root" value which describes the base point in the preferences "tree" from which this "branch" stems. Preferences are accessed off of this root by using just the final portion of the preference. For example, if this object is created with the root "browser.startup.", the preferences "browser.startup.page", "browser.startup.homepage", and "browser.startup.homepage_override" can be accessed by simply passing "page", "homepage", or "homepage_override" to the various Get/Set methods.

This interface is implemented by the following components:


Constants

Values describing the basic preference types.

PRInt32 PREF_INVALID = 0
PRInt32 PREF_STRING = 32
PRInt32 PREF_INT = 64
PRInt32 PREF_BOOL = 128

Properties

readonly char* root

Called to get the root on which this branch is based, such as "browser.startup."


Methods

void clearUserPref ( char* prefName ) void deleteBranch ( char* startingAt ) PRBool getBoolPref ( char* prefName ) char* getCharPref ( char* prefName ) void getChildList ( char* startingAt , out PRUint32 count , out arrayof char* childArray ) void getComplexValue ( char* prefName , nsIIDRef type , out nsQIResult* value ) PRInt32 getIntPref ( char* prefName ) PRInt32 getPrefType ( char* prefName ) void lockPref ( char* prefName ) PRBool prefHasUserValue ( char* prefName ) PRBool prefIsLocked ( char* prefName ) void resetBranch ( char* startingAt ) void setBoolPref ( char* prefName , PRInt32 value ) void setCharPref ( char* prefName , char* value ) void setComplexValue ( char* prefName , nsIIDRef type , nsISupports value ) void setIntPref ( char* prefName , PRInt32 value ) void unlockPref ( char* prefName )

void clearUserPref ( char* prefName )

Called to clear a user set value from a specific preference. This will, in effect, reset the value to the default value. If no default value exists the preference will cease to exist.

Arguments:
prefName: The preference to be cleared.
Returns:
Other The preference does not exist or have a user set value.

void deleteBranch ( char* startingAt )

Called to remove all of the preferences referenced by this branch.

Arguments:
startingAt: The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch.
Returns:
Other The preference(s) do not exist or an error occurred.

PRBool getBoolPref ( char* prefName )

Called to get the state of an individual boolean preference.

Arguments:
prefName: The boolean preference to get the state of.
Returns:
boolean The value of the requested boolean preference.

char* getCharPref ( char* prefName )

Called to get the state of an individual string preference.

Arguments:
prefName: The string preference to retrieve.
Returns:
string The value of the requested string preference.

void getChildList ( char* startingAt , out PRUint32 count , out arrayof char* childArray )

Returns an array of strings representing the child preferences of the root of this branch.

Arguments:
startingAt: The point on the branch at which to start enumerating the child preferences. Pass in "" to enumerate all preferences referenced by this branch.
count: Receives the number of elements in the array.
childArray: Receives the array of child preferences.
Returns:
Other The preference(s) do not exist or an error occurred.

void getComplexValue ( char* prefName , nsIIDRef type , out nsQIResult* value )

Called to get the state of an individual complex preference. A complex preference is a preference which represents an XPCOM object that can not be easily represented using a standard boolean, integer or string value.

Arguments:
prefName: The complex preference to get the value of.
type: The XPCOM interface that this complex preference represents. Interfaces currently supported are: - nsILocalFile - nsISupportsString (UniChar) - nsIPrefLocalizedString (Localized UniChar) - nsIFileSpec (deprecated - to be removed eventually)
value: The XPCOM object into which to the complex preference value should be retrieved.
Returns:
Other The value does not exist or is the wrong type.

PRInt32 getIntPref ( char* prefName )

Called to get the state of an individual integer preference.

Arguments:
prefName: The integer preference to get the value of.
Returns:
long The value of the requested integer preference.

PRInt32 getPrefType ( char* prefName )

Called to determine the type of a specific preference.

Arguments:
prefName: The preference to get the type of.
Returns:
long A value representing the type of the preference. This value will be PREF_STRING, PREF_INT, or PREF_BOOL.

void lockPref ( char* prefName )

Called to lock a specific preference. Locking a preference will cause the preference service to always return the default value regardless of whether there is a user set value or not.

Arguments:
prefName: The preference to be locked.
Returns:
Other The preference does not exist or an error occurred.

PRBool prefHasUserValue ( char* prefName )

Called to check if a specific preference has a user value associated to it.

Arguments:
prefName: The preference to be tested.
Returns:
boolean true The preference has a user set value. false The preference only has a default value.

PRBool prefIsLocked ( char* prefName )

Called to check if a specific preference is locked. If a preference is locked calling its Get method will always return the default value.

Arguments:
prefName: The preference to be tested.
Returns:
boolean true The preference is locked. false The preference is not locked.

void resetBranch ( char* startingAt )

Called to reset all of the preferences referenced by this branch to their default values.

Arguments:
startingAt: The point on the branch at which to start the resetting preferences to their default values. Pass in "" to reset all preferences referenced by this branch.
Returns:
Other The preference(s) do not exist or an error occurred.

void setBoolPref ( char* prefName , PRInt32 value )

Called to set the state of an individual boolean preference.

Arguments:
prefName: The boolean preference to set the state of.
value: The boolean value to set the preference to.
Returns:
Other The value was not set or is the wrong type.

void setCharPref ( char* prefName , char* value )

Called to set the state of an individual string preference.

Arguments:
prefName: The string preference to set.
value: The string value to set the preference to.
Returns:
Other The value was not set or is the wrong type.

void setComplexValue ( char* prefName , nsIIDRef type , nsISupports value )

Called to set the state of an individual complex preference. A complex preference is a preference which represents an XPCOM object that can not be easily represented using a standard boolean, integer or string value.

Arguments:
prefName: The complex preference to set the value of.
type: The XPCOM interface that this complex preference represents. Interfaces currently supported are: - nsILocalFile - nsISupportsString (UniChar) - nsIPrefLocalizedString (Localized UniChar) - nsIFileSpec (deprecated - to be removed eventually)
value: The XPCOM object from which to set the complex preference value.
Returns:
Other The value was not set or is the wrong type.

void setIntPref ( char* prefName , PRInt32 value )

Called to set the state of an individual integer preference.

Arguments:
prefName: The integer preference to set the value of.
value: The integer value to set the preference to.
Returns:
Other The value was not set or is the wrong type.

void unlockPref ( char* prefName )

Called to unlock a specific preference. Unlocking a previously locked preference allows the preference service to once again return the user set value of the preference.

Arguments:
prefName: The preference to be unlocked.
Returns:
Other The preference does not exist or an error occurred.

References

This interface is passed as an argument to the following methods:

nsILDAPPrefsService.getServerList

This interface is returned from the following methods:

nsIPref.getBranch, nsIPref.getDefaultBranch, nsIPrefService.getBranch, nsIPrefService.getDefaultBranch

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
April 16, 2004, 2:58 am g dot kakanauskas at conexus dot lt
If you want to set preferences with special characters, setCharPref will not help. Use unicode instead:


const nsISupportsString = Components.interfaces.nsISupportsString;

function getUnicodePref(prefName,prefBranch) {
return prefBranch.getComplexValue(prefName, nsISupportsString).data;
}

function setUnicodePref(prefName,prefValue,prefBranch) {
var sString = Components.classes["@mozilla.org/supports-string;1"].
createInstance(nsISupportsString);
sString.data = prefValue;
prefBranch.setComplexValue(prefName,nsISupportsString,sString);
}


The code above is not mine, it was posten on netscape.public.dev.xul
Worked for me perfectly. Hope this will save you half of the day :)

Copyright © 1999 - 2005 XULPlanet.com