nsISupports
最終更新: Gecko 13 (Firefox 13 / Thunderbird 13 / SeaMonkey 2.10)このオブジェクトは自身が指し示す"branch"の起点となるpreference木の"root"値を伴って生成されます。各preferencesにはこのrootに続く最後の部分のみを使ってアクセスすることができます。 例えばオブジェクトが"browser.startup."をrootとして生成された場合、"browser.startup.page"、"browser.startup.homepage"、"browser.startup.homepage_override"などに対してGet/Setを行う際には"page"、"homepage"、"homepage_override"と指定することができます。
Method overview
void addObserver(in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak); |
void clearUserPref(in string aPrefName); |
void deleteBranch(in string aStartingAt); |
boolean getBoolPref(in string aPrefName); |
string getCharPref(in string aPrefName); |
void getChildList(in string aStartingAt, [optional] out unsigned long aCount, [array, size_is(aCount), retval] out string aChildArray); |
void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue); |
long getIntPref(in string aPrefName); |
long getPrefType(in string aPrefName); |
void lockPref(in string aPrefName); |
boolean prefHasUserValue(in string aPrefName); |
boolean prefIsLocked(in string aPrefName); |
void removeObserver(in string aDomain, in nsIObserver aObserver); |
void resetBranch(in string aStartingAt); |
void setBoolPref(in string aPrefName, in long aValue); |
void setCharPref(in string aPrefName, in string aValue); |
void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue); |
void setIntPref(in string aPrefName, in long aValue); |
void unlockPref(in string aPrefName); |
Attributes
Attribute | Type | Description |
root |
string |
Called to get the root on which this branch is based, such as "browser.startup." Read only. |
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. |
Methods
addObserver()
preference change observerを追加します。preferenceに変化があると以下の引数がnsIObserver.observe()
に渡されます:
aSubject
- nsIPrefBranch
オブジェクト (this)。
aTopic
- NS_PREFBRANCH_PREFCHANGE_TOPIC_ID で定義される文字列。
aData
- 変更があったpreferenceの名前(aSubject
の"root"に対する相対値)
aSubject.get*Pref(aData)
で変更後の新しい値を得ることができます。例えば observer がaddObserver("bar.", ...)で
"foo."を起点とするbranchに対して登録を行った場合、
"foo.bar.baz"に対する変更がその
observerを起こします。その時のaDataは
"bar.baz"
になります。
void addObserver( in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak );
Parameters
-
aDomain
-
変更を監視したい preference 。完全なbranchを指定することもできます。 例えば "root"
prefbranch
からaddObserver("foo.bar.", ...)
を呼ぶとfoo.bar.baz
とfoo.bar.bzipを監視できます
。 -
aObserver
- preference の変更通知を受け取るオブジェクト。
-
aHoldWeak
-
true
を指定するとaObserver の weak reference を保持します。この場合オブジェクトは
nsISupportsWeakReference
インターフェースを実装する必要があり、実装されていない場合は失敗します。false
を指定すると strong reference を保持します。
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.
void clearUserPref( in string aPrefName );
Parameters
-
aPrefName
- The preference to be cleared.
Remarks
Prior to Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), this method would throw an exception if there was no user value set for the specified preference. Now, this method never throws. Instead, it simply does nothing.
deleteBranch()
Called to remove all of the preferences referenced by this branch.
void 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.
getBoolPref()
Called to get the state of an individual boolean preference.
boolean getBoolPref( in string aPrefName );
Parameters
-
aPrefName
- The boolean preference to get the state of.
Return value
The value of the requested boolean preference.
getCharPref()
Called to get the state of an individual string preference.
string getCharPref( in string aPrefName );
Parameters
-
aPrefName
- The string preference to retrieve.
Return value
Returns string
- The value of the requested string preference.
getChildList()
Returns an array of strings representing the child preferences of the root
of this branch.
(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)
void 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
Optional from Gecko 2.0 - Receives the number of elements in the array.
-
aChildArray
- Receives the array of child preferences.
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 );
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.
getIntPref()
Called to get the state of an individual integer preference.
long getIntPref( in string aPrefName );
Parameters
-
aPrefName
- The integer preference to get the value of.
Return value
Returns long
- The value of the requested integer preference.
getPrefType()
Called to determine the type of a specific preference.
long getPrefType( in string aPrefName );
Parameters
-
aPrefName
- The preference to get the type of.
Return value
Returns long
- A value representing the type of the preference. This value will be PREF_STRING
, PREF_INT, PREF_BOOL,
or PREF_INVALID
.
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.
void lockPref( in string aPrefName );
Parameters
-
aPrefName
- The preference to be locked.
prefHasUserValue()
Called to check if a specific preference has a user value associated to it.
false
for such a preference and the preference will not be saved to a file by nsIPrefService.savePrefFile()
.boolean prefHasUserValue( in string aPrefName );
Parameters
-
aPrefName
- The preference to be tested.
Return value
Returns boolean
- true
The preference has a user set value. false
The preference only has a default value.
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.
boolean prefIsLocked( in string aPrefName );
Parameters
-
aPrefName
- The preference to be tested.
Return value
Returns boolean
- true
The preference is locked. false
The preference is not locked.
removeObserver()
Remove a preference change observer.
removeObserver
method on the same nsIPrefBranch instance on which you called addObserver method in order to remove aObserver
; otherwise, the observer will not be removed.void removeObserver( in string aDomain, in nsIObserver aObserver );
Parameters
-
aDomain
- The preference which is being observed for changes.
-
aObserver
- An observer previously registered with addObserver.
resetBranch()
Called to reset all of the preferences referenced by this branch to their default values.
void resetBranch( in string aStartingAt );
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.
setBoolPref()
Called to set the state of an individual boolean preference.
void setBoolPref( in string aPrefName, in long aValue );
Parameters
-
aPrefName
- The boolean preference to set the state of.
-
aValue
- The boolean value to set the preference to.
setCharPref()
Called to set the state of an individual string preference.
void setCharPref( in string aPrefName, in string aValue );
Parameters
-
aPrefName
- The string preference to set.
-
aValue
- The string value to set the preference to.
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 );
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.
setIntPref()
Called to set the state of an individual integer preference.
void setIntPref( in string aPrefName, in long aValue );
Parameters
-
aPrefName
- The integer preference to set the value of.
-
aValue
- The integer value to set the preference to.
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.
void unlockPref( in string aPrefName );
Parameters
-
aPrefName
- The preference to be unlocked.
Remarks
Registering as a preference observer can open an object to potential cyclical references which will cause memory leaks. These cycles generally occur because an object both registers itself as an observer (causing the branch to hold a reference to the observer) and holds a reference to the branch object for the purpose of getting/setting preference values. There are 3 approaches which have been implemented in an attempt to avoid these situations:
- The nsPrefBranch object supports
nsISupportsWeakReference
. Any consumer may hold a weak reference to it instead of a strong one. - The nsPrefBranch object listens for xpcom-shutdown and frees all of the objects currently in its observer list. This ensures that long lived objects (services for example) will be freed correctly.
- The observer can request to be held as a weak reference when it is registered. This insures that shorter lived objects (say one tied to an open window) will not fall into the cyclical reference trap.
The list of registered observers may be changed during the dispatch of nsPref:changed notification. However, the observers are not guaranteed to be notified in any particular order, so you can't be sure whether the added/removed observer will be called during the notification when it is added/removed.
It is possible to change preferences during the notification.
It is not safe to change observers during this callback in releases before Gecko 1.9. If you want a safe way to remove a preference observer, please use an nsITimer
.