Skip to main content

Visit Mozilla.org

nsIPrefBranch

From MDC


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.

Contents

nsIPrefBranch is defined in modules/libpref/public/nsIPrefBranch.idl. It is scriptable and has been frozen since Mozilla 1.8.

Inherits from: nsISupports

[edit] Method overview

long getPrefType(in string aPrefName);
boolean getBoolPref(in string aPrefName);
void setBoolPref(in string aPrefName, in long aValue);
string getCharPref(in string aPrefName);
void setCharPref(in string aPrefName, in string aValue);
long getIntPref(in string aPrefName);
void setIntPref(in string aPrefName, in long aValue);
void getComplexValue(in string aPrefName, in nsIIDRef aType, [id_is(aType), retval] out nsQIResult aValue);
void clearUserPref(in string aPrefName);
void lockPref(in string aPrefName);
boolean prefHasUserValue(in string aPrefName);
boolean prefIsLocked(in string aPrefName);
void unlockPref(in string aPrefName);
void deleteBranch(in string aStartingAt);
void getChildList(in string aStartingAt, out unsigned long aCount,[array, size_is(aCount), retval] out string aChildArray);
void resetBranch(in string aStartingAt);

[edit] Attributes

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

[edit] Constants

Constant Value Description
PREF_INVALID 0 long
PREF_STRING 32 long data type.
PREF_INT 64 long data type.
PREF_BOOL 128 long data type.

[edit] Methods

[edit] getPrefType()

Called to determine the type of a specific preference. 

  long getPrefType(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to get the type of.
[edit] Return value

A value representing the type of the preference. This value will be PREF_STRING, PREF_INT, or PREF_BOOL.

[edit] getBoolPref()

Called to get the state of an individual boolean preference. 

  boolean getBoolPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The boolean preference to get the state of.
[edit] Return value

The value of the requested boolean preference.

[edit] setBoolPref()

Called to set the state of an individual boolean preference. 

  void setBoolPref(
     in string aPrefName, 
     in long aValue
  );
[edit] Parameters
aPrefName
The boolean preference to set the state of.
aValue
The boolean value to set the preference to.

[edit] getCharPref()

Called to get the state of an individual string preference. 

  string getCharPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The string preference to retrieve.
[edit] Return value

Returns string - The value of the requested string preference.

[edit] setCharPref()

Called to set the state of an individual string preference. 

  void setCharPref(
     in string aPrefName, 
     in string aValue
  );
[edit] Parameters
aPrefName
The string preference to set.
aValue
The string value to set the preference to.

[edit] getIntPref()

Called to get the state of an individual integer preference. 

  long getIntPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The integer preference to get the value of.
[edit] Return value

Returns long - The value of the requested integer preference.

[edit] setIntPref()

Called to set the state of an individual integer preference. 

  void setIntPref(
     in string aPrefName, 
     in long aValue
  );
[edit] Parameters
aPrefName
The integer preference to set the value of.
aValue
The integer value to set the preference to.

[edit] getComplexValue()

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. 

  void getComplexValue(
     in string aPrefName, 
     in nsIIDRef aType,
     [iid_is(aType), retval] out nsQIResult aValue
  );
[edit] Parameters
aPrefName
The complex preference to get the value of.
aType
The XPCOM interface that this complex preference represents. Interfaces currently supported are: nsILocalFile, nsISupportsString (UniChar), nsIPrefLocalizedString (Localized UniChar), nsIFileSpec (deprecated - to be removed eventually).
aValue
The XPCOM object into which to the complex preference value should be retrieved.

[edit] setComplexValue()

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. 

  void setComplexValue(
     in string aPrefName, 
     in nsIIDRef aType, 
     in nsISupports aValue
  );
[edit] Parameters
aPrefName
The complex preference to set the value of.
aType
The XPCOM interface that this complex preference represents. Interfaces currently supported are: nsILocalFile, nsISupportsString (UniChar), nsIPrefLocalizedString (Localized UniChar), nsIFileSpec (deprecated - to be removed eventually).
aValue
The XPCOM object from which to set the complex preference value

[edit] clearUserPref()

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.

Note: This method does nothing if this object is a default branch.
  void clearUserPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to be cleared.

[edit] lockPref()

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.

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.
  void lockPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to be locked.

[edit] prefHasUserValue()

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

Note: This method can be called on either a default or user branch but, in effect, always operates on the user branch.
Note: 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.
  void lockPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to be tested
[edit] Return value

Returns boolean True - The preference has a user set value. False - The preference only has a default value.

[edit] prefIsLocked()

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

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.
  boolean prefIsLocked(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to be tested
[edit] Return value

Returns boolean True - The preference is locked. False - The preference is not locked.

[edit] unlockPref()

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.

Note: This method can be called on either a default or user branch but, in effect, always operates on the default branch.
  void unlockPref(
     in string aPrefName
  );
[edit] Parameters
aPrefName
The preference to be unlocked.

[edit] deleteBranch()

Called to remove all of the 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.
  void deleteBranch(
     in string aStartingAt
  );
[edit] Parameters
aStartingAt
The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch.

[edit] getChildList()

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

Note: This method can be called on either a default or user branch but, in effect, always operates on both.
  void getChildList(
     in string aStartingAt, 
     out unsigned long aCount,
     [array, size_is(aCount), retval] out string aChildArray
  );
[edit] Parameters

(To call from javascript use children = nsIPrefBranch.getChildList("",obj), which will fill in obj.value with the count and return an array of keys! (It is not void in javascript)

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.

[edit] resetBranch()

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

Note: As of Firefox 3.0, this function has not yet been implemented.
  void resetBranch(
     in string aStartingAt
  );
[edit] 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.
Retrieved from "http://developer.mozilla.org/en/docs/nsIPrefBranch"