Public Member Functions | Public Attributes

nsIPrefBranch Interface Reference

The nsIPrefBranch interface is used to manipulate the preferences data. More...

import "nsIPrefBranch.idl";

Inheritance diagram for nsIPrefBranch:

List of all members.

Public Member Functions

long getPrefType (in string aPrefName)
 Called to determine the type of a specific preference.
boolean getBoolPref (in string aPrefName)
 Called to get the state of an individual boolean preference.
void setBoolPref (in string aPrefName, in long aValue)
 Called to set the state of an individual boolean preference.
string getCharPref (in string aPrefName)
 Called to get the state of an individual string preference.
void setCharPref (in string aPrefName, in string aValue)
 Called to set the state of an individual string preference.
long getIntPref (in string aPrefName)
 Called to get the state of an individual integer preference.
void setIntPref (in string aPrefName, in long aValue)
 Called to set the state of an individual integer preference.
void getComplexValue (in string aPrefName, in nsIIDRef aType,[iid_is(aType), retval] out nsQIResult aValue)
 Called to get the state of an individual complex preference.
void setComplexValue (in string aPrefName, in nsIIDRef aType, in nsISupports aValue)
 Called to set the state of an individual complex preference.
void clearUserPref (in string aPrefName)
 Called to clear a user set value from a specific preference.
void lockPref (in string aPrefName)
 Called to lock a specific preference.
boolean prefHasUserValue (in string aPrefName)
 Called to check if a specific preference has a user value associated to it.
boolean prefIsLocked (in string aPrefName)
 Called to check if a specific preference is locked.
void unlockPref (in string aPrefName)
 Called to unlock a specific preference.
void deleteBranch (in string aStartingAt)
 Called to remove all of the preferences referenced by this branch.
void getChildList (in string aStartingAt,[optional] out unsigned long aCount,[array, size_is(aCount), retval] out string aChildArray)
 Returns an array of strings representing the child preferences of the root of this branch.
void resetBranch (in string aStartingAt)
 Called to reset all of the preferences referenced by this branch to their default values.

Public Attributes

const long PREF_INVALID = 0
 Values describing the basic preference types.
const long PREF_STRING = 32
const long PREF_INT = 64
const long PREF_BOOL = 128
readonly attribute string root
 Called to get the root on which this branch is based, such as "browser.startup.".

Detailed Description

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.

See also:
nsIPrefService

Member Function Documentation

void nsIPrefBranch::clearUserPref ( in string  aPrefName  ) 

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.

Parameters:
aPrefName The preference to be cleared.
Note:
This method does nothing if this object is a default branch.
Returns:
NS_OK The user preference was successfully cleared.
Other The preference does not exist or have a user set value.
void nsIPrefBranch::deleteBranch ( in string  aStartingAt  ) 

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

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.
Returns:
NS_OK The preference(s) were successfully removed.
Other The preference(s) do not exist or an error occurred.
boolean nsIPrefBranch::getBoolPref ( in string  aPrefName  ) 

Called to get the state of an individual boolean preference.

Parameters:
aPrefName The boolean preference to get the state of.
Returns:
boolean The value of the requested boolean preference.
See also:
setBoolPref
string nsIPrefBranch::getCharPref ( in string  aPrefName  ) 

Called to get the state of an individual string preference.

Parameters:
aPrefName The string preference to retrieve.
Returns:
string The value of the requested string preference.
See also:
setCharPref
void nsIPrefBranch::getChildList ( in string  aStartingAt,
[optional] out unsigned long  aCount,
[array, size_is(aCount), retval] out string  aChildArray 
)

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

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 Receives the number of elements in the array.
aChildArray 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.
Returns:
NS_OK The preference list was successfully retrieved.
Other The preference(s) do not exist or an error occurred.
void nsIPrefBranch::getComplexValue ( in string  aPrefName,
in nsIIDRef  aType,
[iid_is(aType), retval] out nsQIResult  aValue 
)

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.

Parameters:
aPrefName The complex preference to get the value of.
aType The XPCOM interface that this complex preference represents. Interfaces currently supported are:

aValue The XPCOM object into which to the complex preference value should be retrieved.
Returns:
NS_OK The value was successfully retrieved.
Other The value does not exist or is the wrong type.
See also:
setComplexValue
long nsIPrefBranch::getIntPref ( in string  aPrefName  ) 

Called to get the state of an individual integer preference.

Parameters:
aPrefName The integer preference to get the value of.
Returns:
long The value of the requested integer preference.
See also:
setIntPref
long nsIPrefBranch::getPrefType ( in string  aPrefName  ) 

Called to determine the type of a specific preference.

Parameters:
aPrefName 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 nsIPrefBranch::lockPref ( in string  aPrefName  ) 

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.

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.
Returns:
NS_OK The preference was successfully locked.
Other The preference does not exist or an error occurred.
See also:
unlockPref
boolean nsIPrefBranch::prefHasUserValue ( in string  aPrefName  ) 

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

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.
If a preference was manually set to a value that equals the default value, then the preference no longer has a user set value, i.e. it is considered reset to its default value. In particular, this method will return false for such a preference and the preference will not be saved to a file by nsIPrefService.savePrefFile.
Returns:
boolean true The preference has a user set value. false The preference only has a default value.
boolean nsIPrefBranch::prefIsLocked ( in string  aPrefName  ) 

Called to check if a specific preference is locked.

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

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:
boolean true The preference is locked. false The preference is not locked.
See also:
lockPref
unlockPref
void nsIPrefBranch::resetBranch ( in string  aStartingAt  ) 

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

Parameters:
aStartingAt 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.
Note:
This method can be called on either a default or user branch but, in effect, always operates on the user branch.
Returns:
NS_OK The preference(s) were successfully reset.
Other The preference(s) do not exist or an error occurred.
void nsIPrefBranch::setBoolPref ( in string  aPrefName,
in long  aValue 
)

Called to set the state of an individual boolean preference.

Parameters:
aPrefName The boolean preference to set the state of.
aValue The boolean value to set the preference to.
Returns:
NS_OK The value was successfully set.
Other The value was not set or is the wrong type.
See also:
getBoolPref
void nsIPrefBranch::setCharPref ( in string  aPrefName,
in string  aValue 
)

Called to set the state of an individual string preference.

Parameters:
aPrefName The string preference to set.
aValue The string value to set the preference to.
Returns:
NS_OK The value was successfully set.
Other The value was not set or is the wrong type.
See also:
getCharPref
void nsIPrefBranch::setComplexValue ( in string  aPrefName,
in nsIIDRef  aType,
in nsISupports  aValue 
)

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.

Parameters:
aPrefName The complex preference to set the value of.
aType The XPCOM interface that this complex preference represents. Interfaces currently supported are:

aValue The XPCOM object from which to set the complex preference value.
Returns:
NS_OK The value was successfully set.
Other The value was not set or is the wrong type.
See also:
getComplexValue
void nsIPrefBranch::setIntPref ( in string  aPrefName,
in long  aValue 
)

Called to set the state of an individual integer preference.

Parameters:
aPrefName The integer preference to set the value of.
aValue The integer value to set the preference to.
Returns:
NS_OK The value was successfully set.
Other The value was not set or is the wrong type.
See also:
getIntPref
void nsIPrefBranch::unlockPref ( in string  aPrefName  ) 

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.

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.
Returns:
NS_OK The preference was successfully unlocked.
Other The preference does not exist or an error occurred.
See also:
lockPref

Member Data Documentation

const long nsIPrefBranch::PREF_BOOL = 128
const long nsIPrefBranch::PREF_INT = 64

Values describing the basic preference types.

See also:
getPrefType
const long nsIPrefBranch::PREF_STRING = 32
readonly attribute string nsIPrefBranch::root

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


The documentation for this interface was generated from the following file: