PreferenceManager

public class PreferenceManager
extends Object

java.lang.Object
   ↳ androidx.preference.PreferenceManager

Used to help create Preference hierarchies from activities or XML.

In most cases, clients should use PreferenceFragmentCompat.addPreferencesFromResource(int).

Summary

Nested classes

interface PreferenceManager.OnDisplayPreferenceDialogListener

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

interface PreferenceManager.OnNavigateToScreenListener

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

interface PreferenceManager.OnPreferenceTreeClickListener

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

class PreferenceManager.PreferenceComparisonCallback

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

class PreferenceManager.SimplePreferenceComparisonCallback

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

Constants

String KEY_HAS_SET_DEFAULT_VALUES

Public methods

PreferenceScreen createPreferenceScreen(Context context)
<T extends Preference> T findPreference(CharSequence key)

Finds a Preference with the given key.

Context getContext()

Returns the context.

static SharedPreferences getDefaultSharedPreferences(Context context)

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

PreferenceManager.OnDisplayPreferenceDialogListener getOnDisplayPreferenceDialogListener()
PreferenceManager.OnNavigateToScreenListener getOnNavigateToScreenListener()

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

PreferenceManager.OnPreferenceTreeClickListener getOnPreferenceTreeClickListener()
PreferenceManager.PreferenceComparisonCallback getPreferenceComparisonCallback()
PreferenceDataStore getPreferenceDataStore()

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

PreferenceScreen getPreferenceScreen()

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

SharedPreferences getSharedPreferences()

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

int getSharedPreferencesMode()

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

String getSharedPreferencesName()

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

boolean isStorageDefault()

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

boolean isStorageDeviceProtected()

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

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

Similar to setDefaultValues(Context, int, boolean) but allows the client to provide the filename and mode of the shared preferences file.

static void setDefaultValues(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.

void setOnDisplayPreferenceDialogListener(PreferenceManager.OnDisplayPreferenceDialogListener onDisplayPreferenceDialogListener)
void setOnNavigateToScreenListener(PreferenceManager.OnNavigateToScreenListener listener)

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

void setOnPreferenceTreeClickListener(PreferenceManager.OnPreferenceTreeClickListener listener)

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

void setPreferenceComparisonCallback(PreferenceManager.PreferenceComparisonCallback preferenceComparisonCallback)
void setPreferenceDataStore(PreferenceDataStore dataStore)

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

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 setStorageDefault()

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

void setStorageDeviceProtected()

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

void showDialog(Preference preference)

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

Inherited methods

Constants

KEY_HAS_SET_DEFAULT_VALUES

public static final String KEY_HAS_SET_DEFAULT_VALUES

Constant Value: "_has_set_default_values"

Public methods

createPreferenceScreen

public PreferenceScreen createPreferenceScreen (Context context)

Parameters
context Context

Returns
PreferenceScreen

findPreference

public T findPreference (CharSequence key)

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

Parameters
key CharSequence: The key of the Preference to retrieve
Returns
T The Preference with the key, or null

getContext

public Context getContext ()

Returns the context.

Returns
Context The Context

getDefaultSharedPreferences

public static SharedPreferences getDefaultSharedPreferences (Context context)

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

Parameters
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

getOnDisplayPreferenceDialogListener

public PreferenceManager.OnDisplayPreferenceDialogListener getOnDisplayPreferenceDialogListener ()

Returns
PreferenceManager.OnDisplayPreferenceDialogListener

getOnNavigateToScreenListener

public PreferenceManager.OnNavigateToScreenListener getOnNavigateToScreenListener ()

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

Returns
PreferenceManager.OnNavigateToScreenListener

getOnPreferenceTreeClickListener

public PreferenceManager.OnPreferenceTreeClickListener getOnPreferenceTreeClickListener ()

Returns
PreferenceManager.OnPreferenceTreeClickListener

getPreferenceComparisonCallback

public PreferenceManager.PreferenceComparisonCallback getPreferenceComparisonCallback ()

Returns
PreferenceManager.PreferenceComparisonCallback

getPreferenceDataStore

public PreferenceDataStore getPreferenceDataStore ()

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

Returns
PreferenceDataStore The PreferenceDataStore associated with this manager or null if none

getPreferenceScreen

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

public SharedPreferences getSharedPreferences ()

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

Returns
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

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 Context.getSharedPreferences(String, int)

getSharedPreferencesName

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 Context.getSharedPreferences(String, int)

isStorageDefault

public boolean isStorageDefault ()

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

Returns
boolean

isStorageDeviceProtected

public boolean isStorageDeviceProtected ()

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

Returns
boolean

setDefaultValues

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

Similar to setDefaultValues(Context, int, boolean) but allows the client to provide the filename and mode of the shared preferences file.

Parameters
context Context: The context of the shared preferences
sharedPreferencesName String: A custom name for the shared preferences file
sharedPreferencesMode int: The file creation mode for the shared preferences file, such as Context.MODE_PRIVATE or Context.MODE_PRIVATE.
resId int: The resource ID of the preference XML file
readAgain boolean: 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(Context) and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

public static void setDefaultValues (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
context Context: The context of the shared preferences
resId int: The resource ID of the preference XML file
readAgain boolean: 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(Context) and clear it followed by a call to this method with this parameter set to true.

setOnDisplayPreferenceDialogListener

public void setOnDisplayPreferenceDialogListener (PreferenceManager.OnDisplayPreferenceDialogListener onDisplayPreferenceDialogListener)

Parameters
onDisplayPreferenceDialogListener PreferenceManager.OnDisplayPreferenceDialogListener

setOnNavigateToScreenListener

public void setOnNavigateToScreenListener (PreferenceManager.OnNavigateToScreenListener listener)

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

Parameters
listener PreferenceManager.OnNavigateToScreenListener: The callback to be invoked

setOnPreferenceTreeClickListener

public void setOnPreferenceTreeClickListener (PreferenceManager.OnPreferenceTreeClickListener listener)

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

Parameters
listener PreferenceManager.OnPreferenceTreeClickListener: The callback to be invoked

setPreferenceComparisonCallback

public void setPreferenceComparisonCallback (PreferenceManager.PreferenceComparisonCallback preferenceComparisonCallback)

Parameters
preferenceComparisonCallback PreferenceManager.PreferenceComparisonCallback

setPreferenceDataStore

public void setPreferenceDataStore (<a