PreferenceManager

public class PreferenceManager


Used to help create Preference hierarchies from activities or XML.

In most cases, clients should use addPreferencesFromResource.

Summary

Nested types

Interface definition for a class that will be called when a Preference requests to display a dialog.

Interface definition for a class that will be called when a PreferenceScreen requests navigation.

Interface definition for a callback to be invoked when a Preference in the hierarchy rooted at this PreferenceScreen is clicked.

Callback class to be used by the androidx.recyclerview.widget.RecyclerView.Adapter associated with the PreferenceScreen, used to determine when two Preference objects are semantically and visually the same.

A basic implementation of PreferenceComparisonCallback suitable for use with the default Preference classes.

Constants

static final String
KEY_HAS_SET_DEFAULT_VALUES = "_has_set_default_values"

Public methods

@NonNull PreferenceScreen
@Nullable T

Finds a Preference with the given key.

@NonNull Context

Returns the context.

static SharedPreferences

Gets a SharedPreferences instance that points to the default file that is used by the preference framework in the given context.

@Nullable PreferenceManager.OnDisplayPreferenceDialogListener
@Nullable PreferenceManager.OnNavigateToScreenListener

Returns the PreferenceManager.OnNavigateToScreenListener, if one has been set.

@Nullable PreferenceManager.OnPreferenceTreeClickListener
@Nullable PreferenceManager.PreferenceComparisonCallback
@Nullable PreferenceDataStore

Returns the PreferenceDataStore associated with this manager or null if the default SharedPreferences are used instead.

PreferenceScreen

Returns the root of the preference hierarchy managed by this class.

@Nullable SharedPreferences

Gets a SharedPreferences instance that preferences managed by this will use.

int

Returns the current mode of the SharedPreferences file that preferences managed by this will use.

String

Returns the current name of the SharedPreferences file that preferences managed by this will use.

boolean

Indicates if the storage location used internally by this class is the default provided by the hosting Context.

boolean

Indicates if the storage location used internally by this class is backed by device-protected storage.

static void
setDefaultValues(@NonNull Context context, int resId, boolean readAgain)

Sets the default values from an XML preference file by reading the values defined by each Preference item's android:defaultValue attribute.

static void
setDefaultValues(
    @NonNull Context context,
    String sharedPreferencesName,
    int sharedPreferencesMode,
    int resId,
    boolean readAgain
)

Similar to setDefaultValues but allows the client to provide the filename and mode of the shared preferences file.

void
void

Sets the callback to be invoked when a PreferenceScreen in the hierarchy rooted at this PreferenceManager is clicked.

void

Sets the callback to be invoked when a Preference in the hierarchy rooted at this PreferenceManager is clicked.

void
void

Sets a PreferenceDataStore to be used by all preferences associated with this manager that don't have a custom PreferenceDataStore assigned via setPreferenceDataStore.

boolean
setPreferences(PreferenceScreen preferenceScreen)

Sets the root of the preference hierarchy.

void
setSharedPreferencesMode(int sharedPreferencesMode)

Sets the mode of the SharedPreferences file that preferences managed by this will use.

void
setSharedPreferencesName(String sharedPreferencesName)

Sets the name of the SharedPreferences file that preferences managed by this will use.

void

Sets the storage location used internally by this class to be the default provided by the hosting Context.

void

Explicitly set the storage location used internally by this class to be device-protected storage.

void

Called when a preference requests that a dialog be shown to complete a user interaction.

Constants

KEY_HAS_SET_DEFAULT_VALUES

Added in 1.0.0
public static final String KEY_HAS_SET_DEFAULT_VALUES = "_has_set_default_values"

Public methods

createPreferenceScreen

Added in 1.0.0
public @NonNull PreferenceScreen createPreferenceScreen(@NonNull Context context)

findPreference

Added in 1.1.0
public @Nullable T <T extends Preference> findPreference(@NonNull CharSequence key)

Finds a Preference with the given key. Returns null if no Preference could be found with the given key.

Parameters
@NonNull CharSequence key

The key of the Preference to retrieve

Returns
@Nullable T

The Preference with the key, or null

See also
findPreference

getContext

Added in 1.0.0
public @NonNull Context getContext()

Returns the context.

Returns
@NonNull Context

The Context

getDefaultSharedPreferences

Added in 1.0.0
public static SharedPreferences getDefaultSharedPreferences(@NonNull Context context)

Gets a SharedPreferences instance that points to the default file that is used by the preference framework in the given context.

Parameters
@NonNull Context context

The context of the preferences whose values are wanted

Returns
SharedPreferences

A SharedPreferences instance that can be used to retrieve and listen to values of the preferences

getOnNavigateToScreenListener

Added in 1.0.0
public @Nullable PreferenceManager.OnNavigateToScreenListener getOnNavigateToScreenListener()

Returns the PreferenceManager.OnNavigateToScreenListener, if one has been set.

getPreferenceDataStore

Added in 1.0.0
public @Nullable PreferenceDataStore getPreferenceDataStore()

Returns the PreferenceDataStore associated with this manager or null if the default SharedPreferences are used instead.

Returns
@Nullable PreferenceDataStore

The PreferenceDataStore associated with this manager or null if none

getPreferenceScreen

Added in 1.0.0
public PreferenceScreen getPreferenceScreen()

Returns the root of the preference hierarchy managed by this class.

Returns
PreferenceScreen

The PreferenceScreen object that is at the root of the hierarchy

getSharedPreferences

Added in 1.0.0
public @Nullable SharedPreferences getSharedPreferences()

Gets a SharedPreferences instance that preferences managed by this will use.

Returns
@Nullable SharedPreferences

A SharedPreferences instance pointing to the file that contain the values of preferences that are managed by this PreferenceManager. If a PreferenceDataStore has been set, this method returns null.

getSharedPreferencesMode

Added in 1.0.0
public int getSharedPreferencesMode()

Returns the current mode of the SharedPreferences file that preferences managed by this will use.

Returns
int

The mode that can be passed to getSharedPreferences

getSharedPreferencesName

Added in 1.0.0
public String getSharedPreferencesName()

Returns the current name of the SharedPreferences file that preferences managed by this will use.

Returns
String

The name that can be passed to getSharedPreferences

isStorageDefault

Added in 1.0.0
public boolean isStorageDefault()

Indicates if the storage location used internally by this class is the default provided by the hosting Context.

isStorageDeviceProtected

Added in 1.0.0
public boolean isStorageDeviceProtected()

Indicates if the storage location used internally by this class is backed by device-protected storage.

setDefaultValues

Added in 1.0.0
public static void setDefaultValues(@NonNull Context context, int resId, boolean readAgain)

Sets the default values from an XML preference file by reading the values defined by each Preference item's android:defaultValue attribute. This should be called by the application's main activity.

Parameters
@NonNull Context context

The context of the shared preferences

int resId

The resource ID of the preference XML file

boolean readAgain

Whether to re-read the default values. If false, this method sets the default values only if this method has never been called in the past (or if the KEY_HAS_SET_DEFAULT_VALUES in the default value shared preferences file is false). To attempt to set the default values again bypassing this check, set readAgain to true.

Note: this will NOT reset preferences back to their default values. For that functionality, use getDefaultSharedPreferences and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

Added in 1.0.0
public static void setDefaultValues(
    @NonNull Context context,
    String sharedPreferencesName,
    int sharedPreferencesMode,
    int resId,
    boolean readAgain
)

Similar to setDefaultValues but allows the client to provide the filename and mode of the shared preferences file.

Parameters
@NonNull Context context

The context of the shared preferences

String sharedPreferencesName

A custom name for the shared preferences file

int sharedPreferencesMode

The file creation mode for the shared preferences file, such as MODE_PRIVATE or MODE_PRIVATE.

int resId

The resource ID of the preference XML file

boolean readAgain

Whether to re-read the default values. If false, this method will set the default values only if this method has never been called in the past (or if the KEY_HAS_SET_DEFAULT_VALUES in the default value shared preferences file is false). To attempt to set the default values again bypassing this check, set readAgain to true.

Note: this will NOT reset preferences back to their default values. For that functionality, use getDefaultSharedPreferences and clear it followed by a call to this method with this parameter set to true.

setOnDisplayPreferenceDialogListener

Added in 1.0.0
public void setOnDisplayPreferenceDialogListener(
    @Nullable PreferenceManager.OnDisplayPreferenceDialogListener onDisplayPreferenceDialogListener
)

setOnNavigateToScreenListener

Added in 1.0.0
public void setOnNavigateToScreenListener(
    @Nullable PreferenceManager.OnNavigateToScreenListener listener
)

Sets the callback to be invoked when a PreferenceScreen in the hierarchy rooted at this PreferenceManager is clicked.

Parameters
@Nullable PreferenceManager.OnNavigateToScreenListener listener

The callback to be invoked

setOnPreferenceTreeClickListener

Added in 1.0.0
public void setOnPreferenceTreeClickListener(
    @Nullable PreferenceManager.OnPreferenceTreeClickListener listener
)

Sets the callback to be invoked when a Preference in the hierarchy rooted at this PreferenceManager is clicked.

Parameters
@Nullable PreferenceManager.OnPreferenceTreeClickListener listener

The callback to be invoked

setPreferenceComparisonCallback

Added in 1.0.0
public void setPreferenceComparisonCallback(
    @Nullable PreferenceManager.PreferenceComparisonCallback preferenceComparisonCallback
)

setPreferenceDataStore

Added in 1.0.0
public void setPreferenceDataStore(@Nullable PreferenceDataStore dataStore)

Sets a PreferenceDataStore to be used by all preferences associated with this manager that don't have a custom PreferenceDataStore assigned via setPreferenceDataStore. Also if the data store is set, the child preferences won't use SharedPreferences as long as they are assigned to this manager.

Parameters
@Nullable PreferenceDataStore dataStore

The PreferenceDataStore to be used by this manager

setPreferences

Added in 1.0.0
public boolean setPreferences(PreferenceScreen preferenceScreen)

Sets the root of the preference hierarchy.

Parameters
PreferenceScreen preferenceScreen

The root PreferenceScreen of the preference hierarchy

Returns
boolean

Whether the PreferenceScreen given is different than the previous

setSharedPreferencesMode

Added in 1.0.0
public void setSharedPreferencesMode(int sharedPreferencesMode)

Sets the mode of the SharedPreferences file that preferences managed by this will use.

Parameters
int sharedPreferencesMode

The mode of the SharedPreferences file

setSharedPreferencesName

Added in 1.0.0
public void setSharedPreferencesName(String sharedPreferencesName)

Sets the name of the SharedPreferences file that preferences managed by this will use.

If custom PreferenceDataStore is set, this won't override its usage.

Parameters
String sharedPreferencesName

The name of the SharedPreferences file

setStorageDefault

Added in 1.0.0
public void setStorageDefault()

Sets the storage location used internally by this class to be the default provided by the hosting Context.

setStorageDeviceProtected

Added in 1.0.0
public void setStorageDeviceProtected()

Explicitly set the storage location used internally by this class to be device-protected storage.

On devices with direct boot, data stored in this location is encrypted with a key tied to the physical device, and it can be accessed immediately after the device has booted successfully, both before and after the user has authenticated with their credentials (such as a lock pattern or PIN).

Because device-protected data is available without user authentication, you should carefully limit the data you store using this Context. For example, storing sensitive authentication tokens or passwords in the device-protected area is strongly discouraged.

Prior to API 24 this method has no effect, since device-protected storage is not available.

showDialog

Added in 1.0.0
public void showDialog(@NonNull Preference preference)

Called when a preference requests that a dialog be shown to complete a user interaction.

Parameters
@NonNull Preference preference

The preference requesting the dialog