Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

PreferenceDataStore

abstract class PreferenceDataStore
kotlin.Any
   ↳ androidx.preference.PreferenceDataStore

A data store interface to be implemented and provided to the Preference framework. This can be used to replace the default android.content.SharedPreferences, if needed.

In most cases you want to use android.content.SharedPreferences as it is automatically backed up and migrated to new devices. However, providing custom data store to preferences can be useful if your app stores its preferences in a local database, cloud, or they are device specific like "Developer settings". It might be also useful when you want to use the preferences UI but the data is not supposed to be stored at all because they are only valid per session.

Once a put method is called it is the full responsibility of the data store implementation to safely store the given values. Time expensive operations need to be done in the background to prevent from blocking the UI. You also need to have a plan on how to serialize the data in case the activity holding this object gets destroyed.

By default, all "put" methods throw UnsupportedOperationException.

Summary

Public constructors

A data store interface to be implemented and provided to the Preference framework.

Public methods
open Boolean
getBoolean(key: String!, defValue: Boolean)

Retrieves a Boolean value from the data store.
open Float
getFloat(key: String!, defValue: Float)

Retrieves a Float value from the data store.
open Int
getInt(key: String!, defValue: Int)

Retrieves an Integer value from the data store.
open Long
getLong(key: String!, defValue: Long)

Retrieves a Long value from the data store.
open String?
getString(key: String!, @Nullable defValue: String?)

Retrieves a String value from the data store.
open MutableSet<String!>?
getStringSet(key: String!, @Nullable defValues: MutableSet<String!>?)

Retrieves a set of Strings from the data store.
open Unit
putBoolean(key: String!, value: Boolean)

Sets a Boolean value to the data store.
open Unit
putFloat(key: String!, value: Float)

Sets a Float value to the data store.
open Unit
putInt(key: String!, value: Int)

Sets an Integer value to the data store.
open Unit
putLong(key: String!, value: Long)

Sets a Long value to the data store.
open Unit
putString(key: String!, @Nullable value: String?)

Sets a String value to the data store.
open Unit
putStringSet(key: String!, @Nullable values: MutableSet<String!>?)

Sets a set of Strings to the data store.

Public constructors

<init>

PreferenceDataStore()

A data store interface to be implemented and provided to the Preference framework. This can be used to replace the default android.content.SharedPreferences, if needed.

In most cases you want to use android.content.SharedPreferences as it is automatically backed up and migrated to new devices. However, providing custom data store to preferences can be useful if your app stores its preferences in a local database, cloud, or they are device specific like "Developer settings". It might be also useful when you want to use the preferences UI but the data is not supposed to be stored at all because they are only valid per session.

Once a put method is called it is the full responsibility of the data store implementation to safely store the given values. Time expensive operations need to be done in the background to prevent from blocking the UI. You also need to have a plan on how to serialize the data in case the activity holding this object gets destroyed.

By default, all "put" methods throw UnsupportedOperationException.

Public methods

getBoolean

open fun getBoolean(key: String!, defValue: Boolean): Boolean

Retrieves a Boolean value from the data store.

Parameters
key String!: The name of the preference to retrieve
defValue String!: Value to return if this preference does not exist in the storage
Return
Boolean: the value from the data store or the default return value

getFloat

open fun getFloat(key: String!, defValue: Float): Float

Retrieves a Float value from the data store.

Parameters
key String!: The name of the preference to retrieve
defValue String!: Value to return if this preference does not exist in the storage
Return
Float: The value from the data store or the default return value

getInt

open fun getInt(key: String!, defValue: Int): Int

Retrieves an Integer value from the data store.

Parameters
key String!: The name of the preference to retrieve
defValue String!: Value to return if this preference does not exist in the storage
Return
Int: The value from the data store or the default return value

getLong

open fun getLong(key: String!, defValue: Long): Long

Retrieves a Long value from the data store.

Parameters
key String!: The name of the preference to retrieve
defValue String!: Value to return if this preference does not exist in the storage
Return
Long: The value from the data store or the default return value

getString

@Nullable open fun getString(key: String!, @Nullable defValue: String?): String?

Retrieves a String value from the data store.

Parameters
key String!: The name of the preference to retrieve
defValue String!: Value to return if this preference does not exist in the storage
Return
String?: The value from the data store or the default return value

getStringSet

@Nullable open fun getStringSet(key: String!, @Nullable defValues: MutableSet<String!>?): MutableSet<String!>?

Retrieves a set of Strings from the data store.

Parameters
key String!: The name of the preference to retrieve
defValues String!: Values to return if this preference does not exist in the storage
Return
MutableSet<String!>?: The values from the data store or the default return values

putBoolean

open fun putBoolean(key: String!, value: Boolean): Unit

Sets a Boolean value to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
value String!: The new value for the preference

putFloat

open fun putFloat(key: String!, value: Float): Unit

Sets a Float value to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
value String!: The new value for the preference

putInt

open fun putInt(key: String!, value: Int): Unit

Sets an Integer value to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
value String!: The new value for the preference

putLong

open fun putLong(key: String!, value: Long): Unit

Sets a Long value to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
value String!: The new value for the preference

putString

open fun putString(key: String!, @Nullable value: String?): Unit

Sets a String value to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
value String!: The new value for the preference

putStringSet

open fun putStringSet(key: String!, @Nullable values: MutableSet<String!>?): Unit

Sets a set of Strings to the data store.

Once the value is set the data store is responsible for holding it.

Parameters
key String!: The name of the preference to modify
values String!: The set of new values for the preference