Added in API level 1

SharedPreferences

interface SharedPreferences
android.content.SharedPreferences

Interface for accessing and modifying preference data returned by android.content.Context#getSharedPreferences. For any particular set of preferences, there is a single instance of this class that all clients share. Modifications to the preferences must go through an Editor object to ensure the preference values remain in a consistent state and control when they are committed to storage. Objects that are returned from the various get methods must be treated as immutable by the application.

SharedPreferences is best suited to storing data about how the user prefers to experience the app, for example, whether the user prefers a particular UI theme or whether they prefer viewing particular content in a list vs. a grid. To this end, SharedPreferences reflects changes committed or applied by Editors immediately, potentially before those changes are durably persisted. Under some circumstances such as app crashes or termination these changes may be lost, even if an OnSharedPreferenceChangeListener reported the change was successful. SharedPreferences is not recommended for storing data that is sensitive to this kind of rollback to a prior state such as user security or privacy settings. For other high-level data persistence options, see Room or DataStore.

Note: Common implementations guarantee that outstanding edits to preference files are persisted to disk when host Activities become stopped. In some situations (e.g. performing many Editor.commit() or Editor.apply() operations just prior to navigating away from the host Activity) this can lead to blocking the main thread during lifecycle transition events and associated ANR errors. For more details see the documentation for Editor.commit() and Editor.apply().

Note: This class does not support use across multiple processes.

Summary

Nested classes
abstract

Interface used for modifying values in a SharedPreferences object.
abstract

Interface definition for a callback to be invoked when a shared preference is changed.
Public methods
abstract Boolean

Checks whether the preferences contains a preference.
abstract SharedPreferences.Editor!

Create a new Editor for these preferences, through which you can make modifications to the data in the preferences and atomically commit those changes back to the SharedPreferences object.
abstract MutableMap<String!, *>!

Retrieve all values from the preferences.
abstract Boolean
getBoolean(key: String!, defValue: Boolean)

Retrieve a boolean value from the preferences.
abstract Float
getFloat(key: String!, defValue: Float)

Retrieve a float value from the preferences.
abstract Int
getInt(key: String!, defValue: Int)

Retrieve an int value from the preferences.
abstract Long
getLong(key: String!, defValue: Long)

Retrieve a long value from the preferences.
abstract String?
getString(key: String!, defValue: String?)

Retrieve a String value from the preferences.
abstract MutableSet<String!>?
getStringSet(key: String!, defValues: MutableSet<String!>?)

Retrieve a set of String values from the preferences.
abstract Unit

Registers a callback to be invoked when a change happens to a preference.
abstract Unit

Unregisters a previous callback.

Public methods

contains

Added in API level 1
abstract fun contains(key: String!): Boolean

Checks whether the preferences contains a preference.

Parameters
key String!: The name of the preference to check.
Return
Boolean Returns true if the preference exists in the preferences, otherwise false.

edit

Added in API level 1
abstract fun edit(): SharedPreferences.Editor!

Create a new Editor for these preferences, through which you can make modifications to the data in the preferences and atomically commit those changes back to the SharedPreferences object.

Note that you must call Editor.commit to have any changes you perform in the Editor actually show up in the SharedPreferences.

Return
SharedPreferences.Editor! Returns a new instance of the Editor interface, allowing you to modify the values in this SharedPreferences object.

getAll

Added in API level 1
abstract fun getAll(): MutableMap<String!, *>!

Retrieve all values from the preferences.

Note that you must not modify the collection returned by this method, or alter any of its contents. The consistency of your stored data is not guaranteed if you do.

Return
MutableMap<String!, *>! Returns a map containing a list of pairs key/value representing the preferences.
Exceptions
java.lang.NullPointerException

getBoolean

Added in API level 1
abstract fun getBoolean(
    key: String!, 
    defValue: Boolean
): Boolean

Retrieve a boolean value from the preferences.

Parameters
key String!: The name of the preference to retrieve.
defValue Boolean: Value to return if this preference does not exist.
Return
Boolean Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a boolean.
Exceptions
java.lang.ClassCastException

getFloat

Added in API level 1
abstract fun getFloat(
    key: String!, 
    defValue: Float
): Float

Retrieve a float value from the preferences.

Parameters
key String!: The name of the preference to retrieve.
defValue Float: Value to return if this preference does not exist.
Return
Float Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a float.
Exceptions
java.lang.ClassCastException

getInt

Added in API level 1
abstract fun getInt(
    key: String!, 
    defValue: Int
): Int

Retrieve an int value from the preferences.

Parameters
key String!: The name of the preference to retrieve.
defValue Int: Value to return if this preference does not exist.
Return
Int Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not an int.
Exceptions
java.lang.ClassCastException

getLong

Added in API level 1
abstract fun getLong(
    key: String!, 
    defValue: Long
): Long

Retrieve a long value from the preferences.

Parameters
key String!: The name of the preference to retrieve.
defValue Long: Value to return if this preference does not exist.
Return
Long Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a long.
Exceptions
java.lang.ClassCastException

getString

Added in API level 1
abstract fun getString(
    key: String!, 
    defValue: String?
): String?

Retrieve a String value from the preferences.

Parameters
key String!: The name of the preference to retrieve.
defValue String?: Value to return if this preference does not exist. This value may be null.
Return
String? Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a String. This value may be null.
Exceptions
java.lang.ClassCastException

getStringSet

Added in API level 11
abstract fun getStringSet(
    key: String!, 
    defValues: MutableSet<String!>?
): MutableSet<String!>?

Retrieve a set of String values from the preferences.

Note that you must not modify the set instance returned by this call. The consistency of the stored data is not guaranteed if you do, nor is your ability to modify the instance at all.

Parameters
key String!: The name of the preference to retrieve.
defValues MutableSet<String!>?: Values to return if this preference does not exist. This value may be null.
Return
MutableSet<String!>? Returns the preference values if they exist, or defValues. Throws ClassCastException if there is a preference with this name that is not a Set. This value may be null.
Exceptions
java.lang.ClassCastException

registerOnSharedPreferenceChangeListener

Added in API level 1
abstract fun registerOnSharedPreferenceChangeListener(listener: SharedPreferences.OnSharedPreferenceChangeListener!): Unit

Registers a callback to be invoked when a change happens to a preference.

Caution: The preference manager does not currently store a strong reference to the listener. You must store a strong reference to the listener, or it will be susceptible to garbage collection. We recommend you keep a reference to the listener in the instance data of an object that will exist as long as you need the listener.

Parameters
listener SharedPreferences.OnSharedPreferenceChangeListener!: The callback that will run.

unregisterOnSharedPreferenceChangeListener

Added in API level 1
abstract fun unregisterOnSharedPreferenceChangeListener(listener: SharedPreferences.OnSharedPreferenceChangeListener!): Unit

Unregisters a previous callback.

Parameters
listener SharedPreferences.OnSharedPreferenceChangeListener!: The callback that should be unregistered.