PreferenceManager

Artifact: androidx.preference:preference

View Source

Added in 1.0.0

---

Kotlin |Java

class PreferenceManager

---

Used to help create Preference hierarchies from activities or XML.

In most cases, clients should use addPreferencesFromResource.

See also
PreferenceFragmentCompat

Summary

Nested types
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.
abstract class PreferenceManager.PreferenceComparisonCallback 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.
class PreferenceManager.SimplePreferenceComparisonCallback : PreferenceManager.PreferenceComparisonCallback A basic implementation of PreferenceComparisonCallback suitable for use with the default Preference classes.

Constants
const String!	KEY_HAS_SET_DEFAULT_VALUES = "_has_set_default_values"

Public functions
PreferenceScreen	createPreferenceScreen(context: Context)
T?	<T : Preference?> findPreference(key: CharSequence) Finds a Preference with the given key.
Context	getContext() Returns the context.
java-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.
java-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.
java-static Unit	setDefaultValues(     context: Context,     sharedPreferencesName: String!,     sharedPreferencesMode: Int,     resId: Int,     readAgain: Boolean ) Similar to setDefaultValues but allows the client to provide the filename and mode of the shared preferences file.
Unit	setOnDisplayPreferenceDialogListener(     onDisplayPreferenceDialogListener: PreferenceManager.OnDisplayPreferenceDialogListener? )
Unit	setOnNavigateToScreenListener(     listener: PreferenceManager.OnNavigateToScreenListener? ) Sets the callback to be invoked when a PreferenceScreen in the hierarchy rooted at this PreferenceManager is clicked.
Unit	setOnPreferenceTreeClickListener(     listener: PreferenceManager.OnPreferenceTreeClickListener? ) Sets the callback to be invoked when a Preference in the hierarchy rooted at this PreferenceManager is clicked.
Unit	setPreferenceComparisonCallback(     preferenceComparisonCallback: PreferenceManager.PreferenceComparisonCallback? )
Unit	setPreferenceDataStore(dataStore: PreferenceDataStore?) Sets a PreferenceDataStore to be used by all preferences associated with this manager that don't have a custom PreferenceDataStore assigned via setPreferenceDataStore.
Boolean	setPreferences(preferenceScreen: PreferenceScreen!) Sets the root of the preference hierarchy.
Unit	setSharedPreferencesMode(sharedPreferencesMode: Int) Sets the mode of the SharedPreferences file that preferences managed by this will use.
Unit	setSharedPreferencesName(sharedPreferencesName: String!) Sets the name of the SharedPreferences file that preferences managed by this will use.
Unit	setStorageDefault() Sets the storage location used internally by this class to be the default provided by the hosting Context.
Unit	setStorageDeviceProtected() Explicitly set the storage location used internally by this class to be device-protected storage.
Unit	showDialog(preference: Preference) Called when a preference requests that a dialog be shown to complete a user interaction.

Constants

KEY_HAS_SET_DEFAULT_VALUES

Added in 1.0.0

const val KEY_HAS_SET_DEFAULT_VALUES = "_has_set_default_values": String!

Public functions

createPreferenceScreen

Added in 1.0.0

fun createPreferenceScreen(context: Context): PreferenceScreen

findPreference

Added in 1.1.0

fun <T : Preference?> findPreference(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

Returns
T?	The Preference with the key, or null

See also
findPreference

getContext

Added in 1.0.0

fun getContext(): Context

Returns the context.

Returns
Context	The Context

getDefaultSharedPreferences

Added in 1.0.0

java-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

Returns
SharedPreferences!	A SharedPreferences instance that can be used to retrieve and listen to values of the preferences

getOnDisplayPreferenceDialogListener

Added in 1.0.0

fun getOnDisplayPreferenceDialogListener(): PreferenceManager.OnDisplayPreferenceDialogListener?

getOnNavigateToScreenListener

Added in 1.0.0

fun getOnNavigateToScreenListener(): PreferenceManager.OnNavigateToScreenListener?

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

getOnPreferenceTreeClickListener

Added in 1.0.0

fun getOnPreferenceTreeClickListener(): PreferenceManager.OnPreferenceTreeClickListener?

getPreferenceComparisonCallback

Added in 1.0.0

fun getPreferenceComparisonCallback(): PreferenceManager.PreferenceComparisonCallback?

getPreferenceDataStore

Added in 1.0.0

fun getPreferenceDataStore(): PreferenceDataStore?

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

See also
setPreferenceDataStore

getPreferenceScreen

Added in 1.0.0

fun getPreferenceScreen(): PreferenceScreen!

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

Added in 1.0.0

fun getSharedPreferences(): SharedPreferences?

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

Added in 1.0.0

fun getSharedPreferencesMode(): Int

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

Returns
Int	The mode that can be passed to getSharedPreferences

See also
getSharedPreferences

getSharedPreferencesName

Added in 1.0.0

fun getSharedPreferencesName(): String!

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

Returns
String!	The name that can be passed to getSharedPreferences

See also
getSharedPreferences

isStorageDefault

Added in 1.0.0

fun isStorageDefault(): Boolean

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

See also
setStorageDefault
setStorageDeviceProtected

isStorageDeviceProtected

Added in 1.0.0

fun isStorageDeviceProtected(): Boolean

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

See also
setStorageDefault
setStorageDeviceProtected

setDefaultValues

Added in 1.0.0

java-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: 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 and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

Added in 1.0.0

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

Similar to setDefaultValues 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 MODE_PRIVATE or 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 and clear it followed by a call to this method with this parameter set to true.

See also
setDefaultValues
setSharedPreferencesName
setSharedPreferencesMode

setOnDisplayPreferenceDialogListener

Added in 1.0.0

fun setOnDisplayPreferenceDialogListener(
    onDisplayPreferenceDialogListener: PreferenceManager.OnDisplayPreferenceDialogListener?
): Unit

setOnNavigateToScreenListener

Added in 1.0.0

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

setOnPreferenceTreeClickListener

Added in 1.0.0

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

setPreferenceComparisonCallback

Added in 1.0.0

fun setPreferenceComparisonCallback(
    preferenceComparisonCallback: PreferenceManager.PreferenceComparisonCallback?
): Unit

setPreferenceDataStore

Added in 1.0.0

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

See also
setPreferenceDataStore

setPreferences

Added in 1.0.0

fun setPreferences(preferenceScreen: PreferenceScreen!): Boolean

Sets the root of the preference hierarchy.

Parameters
preferenceScreen: PreferenceScreen!	The root PreferenceScreen of the preference hierarchy

Returns
Boolean	Whether the PreferenceScreen given is different than the previous

setSharedPreferencesMode

Added in 1.0.0

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

See also
getSharedPreferences

setSharedPreferencesName

Added in 1.0.0

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

See also
getSharedPreferences
setPreferenceDataStore

setStorageDefault

Added in 1.0.0

fun setStorageDefault(): Unit

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

setStorageDeviceProtected

Added in 1.0.0

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.

See also
createDeviceProtectedStorageContext

showDialog

Added in 1.0.0

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