Package org.mozilla.geckoview

Class GeckoPreferenceController

Object

org.mozilla.geckoview.GeckoPreferenceController

public class GeckoPreferenceController
extends Object

Class is used to access and manipulate Gecko preferences through GeckoView.

This API is experimental because manipulating Gecko preferences is risky and can interfere with browser operation without special care.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GeckoPreferenceController.GeckoPreference<T>	This object represents information on a GeckoPreference.
static final class	GeckoPreferenceController.Observer	The Observer class contains utilities for monitoring preference changes in Gecko.
static @interface	GeckoPreferenceController.PrefBranch	Pref branch used to distinguish user and default Gecko preferences.
static @interface	GeckoPreferenceController.PrefType	Pref types as defined by Gecko in nsIPrefBranch.idl and should remain in sync.
static class	GeckoPreferenceController.SetGeckoPreference<T>	This object is for constructing instructions on how to set a given preference.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	PREF_BRANCH_DEFAULT	Used when the preference is a default preference.
static final int	PREF_BRANCH_USER	Used when the preference is a "user" defined preference.
static final int	PREF_TYPE_BOOL	Used when the preference conforms to type boolean.
static final int	PREF_TYPE_INT	Used when the preference conforms to type integer.
static final int	PREF_TYPE_INVALID	Used when the preference does not have a type (i.e.
static final int	PREF_TYPE_STRING	Used when the preference conforms to type string.

Constructor Summary

Constructors

Constructor	Description
GeckoPreferenceController()

Method Summary

Modifier and Type	Method	Description
static GeckoResult<Void>	clearGeckoUserPref(String prefName)	Restated from nsIPrefBranch.idl's clearUserPref:
static GeckoResult<GeckoPreferenceController.GeckoPreference<?>>	getGeckoPref(String prefName)	Retrieves the value of a given Gecko preference.
static GeckoResult<List<GeckoPreferenceController.GeckoPreference<?>>>	getGeckoPrefs(List<String> prefNames)	Takes a list of given Gecko preferences and retrieves their corresponding values.
static GeckoResult<Void>	setGeckoPref(String prefName, Boolean value, int branch)	Sets a boolean preference with Gecko.
static GeckoResult<Void>	setGeckoPref(String prefName, Integer value, int branch)	Sets an Integer preference with Gecko.
static GeckoResult<Void>	setGeckoPref(String prefName, String value, int branch)	Sets a String preference with Gecko.
static GeckoResult<Map<String,Boolean>>	setGeckoPrefs(List<GeckoPreferenceController.SetGeckoPreference<?>> prefs)	Sets multiple Gecko preferences at once.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PREF_TYPE_INVALID

public static final int PREF_TYPE_INVALID

Used when the preference does not have a type (i.e. is not defined).

See Also:

• Constant Field Values

PREF_TYPE_STRING

public static final int PREF_TYPE_STRING

Used when the preference conforms to type string.

See Also:

• Constant Field Values

PREF_TYPE_INT

public static final int PREF_TYPE_INT

Used when the preference conforms to type integer.

See Also:

• Constant Field Values

PREF_TYPE_BOOL

public static final int PREF_TYPE_BOOL

Used when the preference conforms to type boolean.

See Also:

• Constant Field Values

PREF_BRANCH_USER

public static final int PREF_BRANCH_USER

Used when the preference is a "user" defined preference. A "user" preference is specified to be set as the current value of the preference. It will persist through restarts and is a part of the user's profile.

See Also:

• Constant Field Values

PREF_BRANCH_DEFAULT

public static final int PREF_BRANCH_DEFAULT

Used when the preference is a default preference. A "default" preference is what is used when no user preference is set.

See Also:

• Constant Field Values

Constructor Details

GeckoPreferenceController

public GeckoPreferenceController()

Method Details

getGeckoPref

@AnyThread
@NonNull
public static GeckoResult<GeckoPreferenceController.GeckoPreference<?>> getGeckoPref(@NonNull
 String prefName)

Retrieves the value of a given Gecko preference.

Parameters:

prefName - The preference to find the value of. e.g., some.pref.value.

Returns:

The typed Gecko preference that corresponds to this value. Will return exceptionally if a deserialization issue occurs.

getGeckoPrefs

@AnyThread
@NonNull
public static GeckoResult<List<GeckoPreferenceController.GeckoPreference<?>>> getGeckoPrefs(@NonNull
 List<String> prefNames)

Takes a list of given Gecko preferences and retrieves their corresponding values.

Parameters:

prefNames - The list of preferences to find the value of. e.g., [some.pref.value, other.pref].

Returns:

A list of retrieved typed Gecko preferences. Will return exceptionally if a deserialization issue occurs.

setGeckoPref

@AnyThread
@NonNull
public static GeckoResult<Void> setGeckoPref(@NonNull
 String prefName,
 @NonNull
 String value,
 int branch)

Sets a String preference with Gecko. Float preferences should use this API.

Parameters:

prefName - The name of the preference to change. e.g., "some.pref.item".

value - The string value the preference should be set to.

branch - The preference branch to operate on. For most usage this will usually be PREF_BRANCH_USER to actively change the value that is active. PREF_BRANCH_DEFAULT will change the current default. If there is ever a user preference value set, then the user value will be used over the default value. The user value will be saved as a part of the user's profile. The default value will not be saved on the user's profile.

Returns:

Will return a GeckoResult when the pref is set or else complete exceptionally.

setGeckoPref

@AnyThread
@NonNull
public static GeckoResult<Void> setGeckoPref(@NonNull
 String prefName,
 @NonNull
 Integer value,
 int branch)

Sets an Integer preference with Gecko.

Parameters:

prefName - The name of the preference to change. e.g., "some.pref.item".

value - The integer value the preference should be set to.

branch - The preference branch to operate on. For most usage this will usually be PREF_BRANCH_USER to actively change the value that is active. PREF_BRANCH_DEFAULT will change the current default. If there is ever a user preference value set, then the user value will be used over the default value. The user value will be saved as a part of the user's profile. The default value will not be saved on the user's profile.

Returns:

Will return a GeckoResult when the pref is set or else complete exceptionally.

setGeckoPref

@AnyThread
@NonNull
public static GeckoResult<Void> setGeckoPref(@NonNull
 String prefName,
 @NonNull
 Boolean value,
 int branch)

Sets a boolean preference with Gecko.

Parameters:

prefName - The name of the preference to change. e.g., "some.pref.item".

value - The boolean value the preference should be set to.

branch - The preference branch to operate on. For most usage this will usually be PREF_BRANCH_USER to actively change the value that is active. PREF_BRANCH_DEFAULT will change the current default. If there is ever a user preference value set, then the user value will be used over the default value. The user value will be saved as a part of the user's profile. The default value will not be saved on the user's profile.

Returns:

Will return a GeckoResult when the pref is set or else complete exceptionally.

setGeckoPrefs

@AnyThread
@NonNull
public static GeckoResult<Map<String,Boolean>> setGeckoPrefs(@NonNull
 List<GeckoPreferenceController.SetGeckoPreference<?>> prefs)

Sets multiple Gecko preferences at once.

Parameters:

prefs - A list of GeckoPreferenceController.SetGeckoPreference to set.

Returns:

A Map of preference names (key) and if they successfully set (values).

clearGeckoUserPref

@AnyThread
@NonNull
public static GeckoResult<Void> clearGeckoUserPref(@NonNull
 String prefName)

Restated from nsIPrefBranch.idl's 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.

Parameters:

prefName - The name of the preference to clear. e.g., "some.pref.item".

Returns:

Will return a GeckoResult once the pref is cleared.