Added in API level 1
Deprecated in API level 29

PreferenceManager


open class PreferenceManager
kotlin.Any
   ↳ android.preference.PreferenceManager

Used to help create Preference hierarchies from activities or XML.

In most cases, clients should use PreferenceActivity#addPreferencesFromIntent or PreferenceActivity#addPreferencesFromResource(int).

Summary

Nested classes
abstract

Interface definition for a class that will be called when the container's activity is destroyed.

abstract

Interface definition for a class that will be called when the container's activity receives an activity result.

abstract

Interface definition for a class that will be called when the container's activity is stopped.

Constants
static String

static String

The Activity meta-data key for its XML preference hierarchy.

Public methods
open PreferenceScreen!

open Preference?

Finds a Preference based on its key.

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 String!

Returns the name used for storing default shared preferences.

open PreferenceDataStore?

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

open SharedPreferences!

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

open Int

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

open String!

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

open Boolean

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

open Boolean

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

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(android.content.Context,int,boolean) but allows the client to provide the filename and mode of the shared preferences file.

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 Unit
setSharedPreferencesMode(sharedPreferencesMode: Int)

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

open Unit
setSharedPreferencesName(sharedPreferencesName: String!)

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

open Unit

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

open Unit

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

Constants

KEY_HAS_SET_DEFAULT_VALUES

Added in API level 1
static val KEY_HAS_SET_DEFAULT_VALUES: String

Deprecated: Deprecated in Java.

Value: "_has_set_default_values"

METADATA_KEY_PREFERENCES

Added in API level 1
static val METADATA_KEY_PREFERENCES: String

Deprecated: Deprecated in Java.

The Activity meta-data key for its XML preference hierarchy.

Value: "android.preference"

Public methods

createPreferenceScreen

Added in API level 1
open fun createPreferenceScreen(context: Context!): PreferenceScreen!

Deprecated: Deprecated in Java.

findPreference

Added in API level 1
open fun findPreference(key: CharSequence!): Preference?

Deprecated: Deprecated in Java.

Finds a Preference based on its key.

Parameters
key CharSequence!: the key of the preference to retrieve
Return
Preference? the Preference with the key, or null

getDefaultSharedPreferences

Added in API level 1
open static fun getDefaultSharedPreferences(context: Context!): SharedPreferences!

Deprecated: Deprecated in Java.

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.

getDefaultSharedPreferencesName

Added in API level 24
Deprecated in API level 29
open static fun getDefaultSharedPreferencesName(context: Context!): String!

Deprecated: Deprecated in Java.

Returns the name used for storing default shared preferences.

getPreferenceDataStore

Added in API level 26
Deprecated in API level 29
open fun getPreferenceDataStore(): PreferenceDataStore?

Deprecated: Deprecated in Java.

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

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

getSharedPreferences

Added in API level 1
open fun getSharedPreferences(): SharedPreferences!

Deprecated: Deprecated in Java.

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

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

getSharedPreferencesMode

Added in API level 1
open fun getSharedPreferencesMode(): Int

Deprecated: Deprecated in Java.

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

getSharedPreferencesName

Added in API level 1
open fun getSharedPreferencesName(): String!

Deprecated: Deprecated in Java.

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

isStorageDefault

Added in API level 24
Deprecated in API level 29
open fun isStorageDefault(): Boolean

Deprecated: Deprecated in Java.

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

isStorageDeviceProtected

Added in API level 24
Deprecated in API level 29
open fun isStorageDeviceProtected(): Boolean

Deprecated: Deprecated in Java.

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

setDefaultValues

Added in API level 1
open static fun setDefaultValues(
    context: Context!,
    resId: Int,
    readAgain: Boolean
): Unit

Deprecated: Deprecated in Java.

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 PreferenceManager#getDefaultSharedPreferences(Context) and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

Added in API level 1
open static fun setDefaultValues(
    context: Context!,
    sharedPreferencesName: String!,
    sharedPreferencesMode: Int,
    resId: Int,
    readAgain: Boolean
): Unit

Deprecated: Deprecated in Java.

Similar to setDefaultValues(android.content.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 android.content.Context#MODE_PRIVATE or android.content.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 PreferenceManager#getDefaultSharedPreferences(Context) and clear it followed by a call to this method with this parameter set to true.

setPreferenceDataStore

Added in API level 26
Deprecated in API level 29
open fun setPreferenceDataStore(dataStore: PreferenceDataStore!): Unit

Deprecated: Deprecated in Java.

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 android.content.SharedPreferences as long as they are assigned to this manager.

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

setSharedPreferencesMode

Added in API level 1
open fun setSharedPreferencesMode(sharedPreferencesMode: Int): Unit

Deprecated: Deprecated in Java.

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

Parameters
sharedPreferencesMode Int: The mode of the SharedPreferences file.

setSharedPreferencesName

Added in API level 1
open fun setSharedPreferencesName(sharedPreferencesName: String!): Unit

Deprecated: Deprecated in Java.

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.

setStorageDefault

Added in API level 24
Deprecated in API level 29
open fun setStorageDefault(): Unit

Deprecated: Deprecated in Java.

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

setStorageDeviceProtected

Added in API level 24
Deprecated in API level 29
open fun setStorageDeviceProtected(): Unit

Deprecated: Deprecated in Java.

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.