browserSettings API
Hint
The browserSettings.homepageOverride API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Use the browser.browserSettings API to control global settings of the browser.
Property: homepageOverride
Returns the value of the overridden home page. Read-only.
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
browserSettings
Read and modify browser settings.
Functions
clear(details)
Clears the setting, restoring any default value.
Parameters
details
Which setting to clear.
scope
Where to clear the setting (default: regular).
Required permissions
get(details)
Gets the value of a setting.
Parameters
details
Return type (Promise)
_returns
Details of the currently effective value.
levelOfControl
The level of control of the setting.
value
The value of the setting.
incognitoSpecific
Whether the effective value is specific to the incognito session.<br/>This property will only be present if the incognito property in the details parameter of get() was true.
Required permissions
set(details)
Sets the value of a setting.
Parameters
details
Which setting to change.
value
The value of the setting. <br/>Note that every setting has a specific value type, which is described together with the setting. An extension should not set a value of a different type.
scope
Where to set the setting (default: regular).
Required permissions
Events
onChange
Fired after the setting changes.
Parameters for onChange.addListener(listener)
listener(details)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
levelOfControl
The level of control of the setting.
value
The value of the setting after the change.
incognitoSpecific
Whether the value that has changed is specific to the incognito session.<br/>This property will only be present if the user has enabled the extension in incognito mode.
Required permissions
Types
LevelOfControl
One of
not_controllable: cannot be controlled by any extension
controlled_by_other_extensions: controlled by extensions with higher precedence
controllable_by_this_extension: can be controlled by this extension
controlled_by_this_extension: controlled by this extension
SettingScope
The scope of the Setting. One of
regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
regular_only: setting for the regular profile only (not inherited by the incognito profile),
incognito_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
incognito_session_only: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences). Only regular is supported by Thunderbird at this time.