Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

PreferenceManager

open class PreferenceManager
kotlin.Any
   ↳ 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
abstract

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

abstract

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

abstract

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

abstract

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.

open

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

Constants
static String

Public methods
open Boolean

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

open PreferenceManager.PreferenceComparisonCallback!

open PreferenceManager.OnPreferenceTreeClickListener!

open PreferenceScreen!

open Unit

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

open T?

Finds a Preference with the given key.

open PreferenceManager.OnNavigateToScreenListener!

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

open Unit
setSharedPreferencesName(sharedPreferencesName: String!)

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

open PreferenceDataStore?

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

open PreferenceScreen!

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

open SharedPreferences!

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

open Unit

open Int

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

open Unit
setSharedPreferencesMode(sharedPreferencesMode: Int)

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

open Unit

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

open Boolean

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

open Context!

Returns the context.

open Unit

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

open Unit
showDialog(preference: Preference!)

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

open Unit

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

open Unit

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).

open String!

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

open Boolean
setPreferences(preferenceScreen: PreferenceScreen!)

Sets the root of the preference hierarchy.

open PreferenceManager.OnDisplayPreferenceDialogListener!

open Unit

open static SharedPreferences!

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

open static Unit
setDefaultValues(context: Context!, resId: Int, readAgain: Boolean)

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

open static Unit
setDefaultValues(context: Context!, sharedPreferencesName: String!, sharedPreferencesMode: Int, resId: Int, readAgain: Boolean)

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

Constants

KEY_HAS_SET_DEFAULT_VALUES

static val KEY_HAS_SET_DEFAULT_VALUES: String
Value: "_has_set_default_values"

Public methods

isStorageDefault

open fun isStorageDefault(): Boolean

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

getPreferenceComparisonCallback

open fun getPreferenceComparisonCallback(): PreferenceManager.PreferenceComparisonCallback!

getOnPreferenceTreeClickListener

open fun getOnPreferenceTreeClickListener(): PreferenceManager.OnPreferenceTreeClickListener!

createPreferenceScreen

open fun createPreferenceScreen(context: Context!): PreferenceScreen!

setStorageDefault

open fun setStorageDefault(): Unit

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

findPreference

@Nullable open fun <T : Preference!> findPreference(@NonNull key: CharSequence): T?

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
Return
T?: The Preference with the key, or null

getOnNavigateToScreenListener

open fun getOnNavigateToScreenListener(): PreferenceManager.OnNavigateToScreenListener!

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

setSharedPreferencesName

open fun setSharedPreferencesName(sharedPreferencesName: String!): Unit

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
sharedPreferencesName String!: The name of the SharedPreferences file

getPreferenceDataStore

@Nullable open fun getPreferenceDataStore(): PreferenceDataStore?

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

Return
PreferenceDataStore?: The PreferenceDataStore associated with this manager or null if none

getPreferenceScreen

open fun getPreferenceScreen(): PreferenceScreen!

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

Return
PreferenceScreen!: The PreferenceScreen object that is at the root of the hierarchy

getSharedPreferences

open fun getSharedPreferences(): SharedPreferences!

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

Return
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.

setOnDisplayPreferenceDialogListener

open fun setOnDisplayPreferenceDialogListener(onDisplayPreferenceDialogListener: PreferenceManager.OnDisplayPreferenceDialogListener!): Unit

getSharedPreferencesMode

open fun getSharedPreferencesMode(): Int

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

Return
Int: The mode that can be passed to Context#getSharedPreferences(String, int)

setSharedPreferencesMode

open fun setSharedPreferencesMode(sharedPreferencesMode: Int): Unit

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

Parameters
sharedPreferencesMode Int: The mode of the SharedPreferences file

setOnPreferenceTreeClickListener

open fun setOnPreferenceTreeClickListener(listener: PreferenceManager.OnPreferenceTreeClickListener!): Unit

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

isStorageDeviceProtected

open fun isStorageDeviceProtected(): Boolean

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

getContext

open fun getContext(): Context!

Returns the context.

Return
Context!: The Context

setOnNavigateToScreenListener

open fun setOnNavigateToScreenListener(listener: PreferenceManager.OnNavigateToScreenListener!): Unit

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

showDialog

open fun showDialog(preference: Preference!): Unit

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

Parameters
preference Preference!: The preference requesting the dialog

setStorageDeviceProtected

open fun setStorageDeviceProtected(): Unit

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.

setPreferenceDataStore

open fun setPreferenceDataStore(dataStore: PreferenceDataStore!): Unit

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). Also if the data store is set, the child preferences won't use SharedPreferences as long as they are assigned to this manager.

Parameters
dataStore PreferenceDataStore!: The PreferenceDataStore to be used by this manager

getSharedPreferencesName

open fun getSharedPreferencesName(): String!

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

Return
String!: The name that can be passed to Context#getSharedPreferences(String, int)

setPreferences

open fun setPreferences(preferenceScreen: PreferenceScreen!): Boolean

Sets the root of the preference hierarchy.

Parameters
preferenceScreen PreferenceScreen!: The root PreferenceScreen of the preference hierarchy
Return
Boolean: Whether the PreferenceScreen given is different than the previous

getOnDisplayPreferenceDialogListener

open fun getOnDisplayPreferenceDialogListener(): PreferenceManager.OnDisplayPreferenceDialogListener!

setPreferenceComparisonCallback

open fun setPreferenceComparisonCallback(preferenceComparisonCallback: PreferenceManager.PreferenceComparisonCallback!): Unit

getDefaultSharedPreferences

open static fun getDefaultSharedPreferences(context: Context!): SharedPreferences!

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
Return
SharedPreferences!: A SharedPreferences instance that can be used to retrieve and listen to values of the preferences

setDefaultValues

open static fun setDefaultValues(context: Context!, resId: Int, readAgain: Boolean): Unit

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 Context!: The resource ID of the preference XML file
readAgain Context!: 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 PreferenceManager#getDefaultSharedPreferences(Context) and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

open static fun setDefaultValues(context: Context!, sharedPreferencesName: String!, sharedPreferencesMode: Int, resId: Int, readAgain: Boolean): Unit

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