nsIPrefBranch

You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Embedding Gecko API

nsIPrefBranch

This 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 scriptable.

See also nsIPrefService

Methods

getPrefType

Determines the type of a specific preference.

Syntax:
long nsIPrefBranch::getPrefType(in string aPrefName) 
Parameters:

aPrefName: The preference whose type is being requested.

Returns:

A value representing the type of the preference. This value will be PREF_STRING, PREF_INT, or PREF_BOOL (see below for definition of these constants).

getBoolPref

Gets the state of an individual boolean preference.

Syntax:
boolean nsIPrefBranch::getBoolPref(in string aPrefName) 
Parameters:

aPrefName: The boolean preference whose state is being requested.

Returns:

The value of the requested boolean preference.

setBoolPref

Sets the state of an individual boolean preference.

Syntax:
void nsIPrefBranch::setBoolPref(in string aPrefName,
	in long aValue)  
Parameters:

aPrefName: The preference whose state is to be set.

aValue: The value to set the preference to.

nsresult:

NS_OK if the value was successfully set.

Other if value was not set or is the wrong type.

getCharPref

Gets the state of an individual string preference.

Syntax:
string nsIPrefBranch::getCharPref(in string aPrefName)  
Parameters:

aPrefName: The name of string preference to get.

Returns:

The value of the requested string preference.

setCharPref

Sets the state of an individual string preference.

Syntax:
void nsIPrefBranch::setCharPref(in string aPrefName,
	in string aValue)  
Parameters:

aPrefName: The name of the string preference to set.

aValue: The value to set the preference to.

Returns:

NS_OK if the value was successfully set.

Other if the value was not set or is the wrong type.

getIntPref

Gets the state of an individual integer preference.

Syntax:
long nsIPrefBranch::getIntPref(in string aPrefName)  
Parameters:

aPrefName: The integer preference whose value is being requested.

Returns:

The value of the requested integer preference.

setIntPref

Sets the state of an individual integer preference.

Syntax:
void nsIPrefBranch::setIntPref(in string aPrefName,
	in long aValue)  
Parameters:

aPrefName: The name of the integer preference to set.

aValue: The value to set the preference to.

nsresult:

NS_OK if the value was successfully set.

Other if the value was not set or is the wrong type.

getComplexValue

Gets 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.

Syntax:
void nsIPrefBranch::getComplexValue(in string aPrefName,
	in nsIIDRef aType,
	[iid_is(aType), retval] out nsQIResult aValue)  
Parameters:

aPrefName: The name of the complex preference whose value is being requested.

aType: The XPCOM interface that this complex preference represents. Interfaces currently supported are:

aValue: [out] The XPCOM object into which to the complex preference value should be retrieved.

nsresult:

NS_OK if the value was successfully retrieved

Other if the value does not exist or is the wrong type.

setComplexValue

Sets 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.

Syntax:
void nsIPrefBranch::setComplexValue(in string aPrefName,
	in nsIIDRef aType,
	in nsISupports aValue)  
Parameters:

aPrefName: The name of the complex preference whose value is being set.

aType: The XPCOM interface that this complex preference represents. Interfaces currently supported are:

nsresult:

NS_OK if the value was successfully set.

Other if the value was not set or is the wrong type.

clearUserPref

Clears 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.

Syntax:
void nsIPrefBranch::clearUserPref (in string aPrefName)  
Parameters:

aPrefName: The preference to be cleared.

Note: This method does nothing if this object is a default branch.

nsresult:

NS_OK if the user preference was successfully cleared.

Other if the preference does not exist or have a user set value.

lockPref

Locks 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.

Syntax:
void nsIPrefBranch::lockPref(in string aPrefName) 
Parameters:

aPrefName: The preference to be locked.

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.

nsresult:

NS_OK if the preference was successfully locked.

Other if the preference does not exist or an error occurred.

prefHasUserValue

Checks if a specific preference has a user value associated with it.

Syntax:
boolean nsIPrefBranch::prefHasUserValue(
	in string aPrefName) 
Parameters:

aPrefName: The preference to be tested.

Note: This method can be called on either a default or user branch but, in effect, always operates on the user branch.

Returns:

TRUE if has a user set value.

FALSE if the preference only has a default value.

prefIsLocked

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

Syntax:
boolean nsIPrefBranch::prefIsLocked(in string aPrefName)  
Parameters:

aPrefName: The preference to be tested.

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.

Returns:

TRUE if the preference is locked.

FALSE if the preference is not locked.

unlockPref

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

Syntax:
void nsIPrefBranch::unlockPref(in string aPrefName)  
Parameters:

aPrefName: The preference to be unlocked.

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.

nsresult:

NS_OK if the preference was successfully unlocked.

Other if the preference does not exist or an error occurred.

deleteBranch

Removes all of the preferences referenced by this branch.

Syntax:
void nsIPrefBranch::deleteBranch(in string aStartingAt)  
Parameters:

aStartingAt: The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch.

Note:This method can be called on either a default or user branch but, in effect, always operates on both.

nsresult:

NS_OK if the preference(s) were successfully removed.

Other if the preference(s) do not exist or an error occurred.

getChildList

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

Syntax:
void nsIPrefBranch::getChildList(in string aStartingAt,
	out unsigned long aCount,
	[array, size_is(aCount), retval] out string aChildArray) 
Parameters:

aStartingAt: The point on the branch at which to start enumerating the child preferences. Pass in "" to enumerate all preferences referenced by this branch.

aCount: [out] Receives the number of elements in the array.

aChildArray: [out] Receives the array of child preferences.

Note: This method can be called on either a default or user branch but, in effect, always operates on both.

nsresult:

NS_OK if the preference list was successfully retrieved

Other if the preference(s) do not exist or an error occurred.

resetBranch

Resets all of the preferences referenced by this branch to their default values

Syntax:
void nsIPrefBranch::resetBranch(in string aStartingAt)  
Parameters:

aStartingAt: The point on the branch at which to start resetting the preferences to their default values. Pass in "" to reset all preferences referenced by this branch.

Note: This method can be called on either a default or user branch but, in effect, always operates on the user branch.

nsresult:

NS_OK if the preference(s) were successfully reset.

Other if the preference(s) do not exist or an error occurred.

Attributes and Constants

readonly attribute string nsIPrefBranch::root

Gets the root on which this branch is based, such as "browser.startup."

const long nsIPrefBranch::PREF_INVALID=0

const long nsIPrefBranch::PREF_STRING=32

const long nsIPrefBranch::PREF_INT=64

const long nsIPrefBranch::PREF_BOOL=128

Values describing the basic preference types. Used in getPrefType.

Written by:Ellen Evans | Comments, questions, complaints? Bug 143387

Mozilla

nsIPrefBranch

Syntax:

Parameters:

Returns:

Parameters:

Returns:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

Returns:

Syntax:

Parameters:

Returns:

Syntax:

Parameters:

Returns:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

Returns:

Syntax:

Parameters:

Returns:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult:

Syntax:

Parameters:

nsresult: