It's happening now, watch the livestream.

PreferenceFragmentCompat

abstract class PreferenceFragmentCompat : Fragment, PreferenceManager.OnPreferenceTreeClickListener, PreferenceManager.OnDisplayPreferenceDialogListener, PreferenceManager.OnNavigateToScreenListener, DialogPreference.TargetFragment
kotlin.Any
   ↳ androidx.fragment.app.Fragment
   ↳ androidx.preference.PreferenceFragmentCompat

A PreferenceFragmentCompat is the entry point to using the Preference library. This Fragment displays a hierarchy of Preference objects to the user. It also handles persisting values to the device. To retrieve an instance of android.content.SharedPreferences that the preference hierarchy in this fragment will use by default, call PreferenceManager#getDefaultSharedPreferences(android.content.Context) with a context in the same package as this fragment.

You can define a preference hierarchy as an XML resource, or you can build a hierarchy in code. In both cases you need to use a PreferenceScreen as the root component in your hierarchy.

To inflate from XML, use the setPreferencesFromResource(int, String). An example example XML resource is shown further down.

To build a hierarchy from code, use PreferenceManager#createPreferenceScreen(Context) to create the root PreferenceScreen. Once you have added other Preferences to this root scree with PreferenceScreen#addPreference(Preference), you then need to set the screen as the root screen in your hierarchy with setPreferenceScreen(PreferenceScreen).

As a convenience, this fragment implements a click listener for any preference in the current hierarchy, see onPreferenceTreeClick(Preference).

Sample Code

The following sample code shows a simple settings screen using an XML resource. The XML resource is as follows:

The fragment that loads the XML resource is as follows:

Summary

Nested classes

abstract

Interface that the fragment's containing activity should implement to be able to process preference items that wish to display a dialog.

abstract

Interface that the fragment's containing activity should implement to be able to process preference items that wish to switch to a specified fragment.

abstract

Interface that the fragment's containing activity should implement to be able to process preference items that wish to switch to a new screen of preferences.

Constants

static String

Fragment argument used to specify the tag of the desired root PreferenceScreen object.

Public constructors

A PreferenceFragmentCompat is the entry point to using the Preference library.

Public methods

open Unit
addPreferencesFromResource(@XmlRes preferencesResId: Int)

Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

open T?

RecyclerView!

open PreferenceManager!

Returns the PreferenceManager used by this fragment.

open PreferenceScreen!

Gets the root of the preference hierarchy that this fragment is showing.

open Unit
onCreate(@Nullable savedInstanceState: Bundle?)

open RecyclerView.LayoutManager!

Called from onCreateRecyclerView to create the RecyclerView.LayoutManager for the created RecyclerView.

abstract Unit
onCreatePreferences(savedInstanceState: Bundle!, rootKey: String!)

Called during onCreate(Bundle) to supply the preferences for this fragment.

open RecyclerView!
onCreateRecyclerView(inflater: LayoutInflater!, parent: ViewGroup!, savedInstanceState: Bundle!)

Creates the RecyclerView used to display the preferences.

open View?
onCreateView(@NonNull inflater: LayoutInflater, @Nullable container: ViewGroup?, @Nullable savedInstanceState: Bundle?)

open Unit

open Unit

Called when a preference in the tree requests to display a dialog.

open Unit

Called by PreferenceScreen#onClick() in order to navigate to a new screen of preferences.

open Boolean

Called when a preference in the tree rooted at this PreferenceScreen has been clicked.

open Unit
onSaveInstanceState(@NonNull outState: Bundle)

open Unit

open Unit

open Unit
onViewCreated(@NonNull view: View, @Nullable savedInstanceState: Bundle?)

open Unit

open Unit

open Unit
setDivider(divider: Drawable!)

Sets the Drawable that will be drawn between each item in the list.

open Unit

Sets the height of the divider that will be drawn between each item in the list.

open Unit

Sets the root of the preference hierarchy that this fragment is showing.

open Unit
setPreferencesFromResource(@XmlRes preferencesResId: Int, @Nullable key: String?)

Inflates the given XML resource and replaces the current preference hierarchy (if any) with the preference hierarchy rooted at key.

Protected methods

open RecyclerView.Adapter<RecyclerView.ViewHolder!>!
onCreateAdapter(preferenceScreen: PreferenceScreen!)

Creates the root adapter.

Inherited functions

Constants

ARG_PREFERENCE_ROOT

static val ARG_PREFERENCE_ROOT: String

Fragment argument used to specify the tag of the desired root PreferenceScreen object.

Value: "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"

Public constructors

<init>

PreferenceFragmentCompat()

A PreferenceFragmentCompat is the entry point to using the Preference library. This Fragment displays a hierarchy of Preference objects to the user. It also handles persisting values to the device. To retrieve an instance of android.content.SharedPreferences that the preference hierarchy in this fragment will use by default, call PreferenceManager#getDefaultSharedPreferences(android.content.Context) with a context in the same package as this fragment.

You can define a preference hierarchy as an XML resource, or you can build a hierarchy in code. In both cases you need to use a PreferenceScreen as the root component in your hierarchy.

To inflate from XML, use the setPreferencesFromResource(int, String). An example example XML resource is shown further down.

To build a hierarchy from code, use PreferenceManager#createPreferenceScreen(Context) to create the root PreferenceScreen. Once you have added other Preferences to this root scree with PreferenceScreen#addPreference(Preference), you then need to set the screen as the root screen in your hierarchy with setPreferenceScreen(PreferenceScreen).

As a convenience, this fragment implements a click listener for any preference in the current hierarchy, see onPreferenceTreeClick(Preference).

Sample Code

The following sample code shows a simple settings screen using an XML resource. The XML resource is as follows:

The fragment that loads the XML resource is as follows:

Public methods

addPreferencesFromResource

open fun addPreferencesFromResource(@XmlRes preferencesResId: Int): Unit

Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

Parameters
preferencesResId Int: The XML resource ID to inflate

findPreference

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

getListView

fun getListView(): RecyclerView!

getPreferenceManager

open fun getPreferenceManager(): PreferenceManager!

Returns the PreferenceManager used by this fragment.

Return
PreferenceManager!: The PreferenceManager used by this fragment

getPreferenceScreen

open fun getPreferenceScreen(): PreferenceScreen!

Gets the root of the preference hierarchy that this fragment is showing.

Return
PreferenceScreen!: The PreferenceScreen that is the root of the preference hierarchy

onCreate

open fun onCreate(@Nullable savedInstanceState: Bundle?): Unit

onCreateLayoutManager

open fun onCreateLayoutManager(): RecyclerView.LayoutManager!

Called from onCreateRecyclerView to create the RecyclerView.LayoutManager for the created RecyclerView.

Return
RecyclerView.LayoutManager!: A new RecyclerView.LayoutManager instance

onCreatePreferences

abstract fun onCreatePreferences(savedInstanceState: Bundle!, rootKey: String!): Unit

Called during onCreate(Bundle) to supply the preferences for this fragment. Subclasses are expected to call setPreferenceScreen(PreferenceScreen) either directly or via helper methods such as addPreferencesFromResource(int).

Parameters
savedInstanceState Bundle!: If the fragment is being re-created from a previous saved state, this is the state.
rootKey Bundle!: If non-null, this preference fragment should be rooted at the PreferenceScreen with this key.

onCreateRecyclerView

open fun onCreateRecyclerView(inflater: LayoutInflater!, parent: ViewGroup!, savedInstanceState: Bundle!): RecyclerView!

Creates the RecyclerView used to display the preferences. Subclasses may override this to return a customized RecyclerView.

Parameters
inflater LayoutInflater!: The LayoutInflater object that can be used to inflate the RecyclerView.
parent LayoutInflater!: The parent ViewGroup that the RecyclerView will be attached to. This method should not add the view itself, but this can be used to generate the layout params of the view.
savedInstanceState LayoutInflater!: If non-null, this view is being re-constructed from a previous saved state as given here.
Return
RecyclerView!: A new RecyclerView object to be placed into the view hierarchy

onCreateView

open fun onCreateView(@NonNull inflater: LayoutInflater, @Nullable container: ViewGroup?, @Nullable savedInstanceState: Bundle?): View?

onDestroyView

open fun onDestroyView(): Unit

onDisplayPreferenceDialog

open fun onDisplayPreferenceDialog(preference: Preference!): Unit

Called when a preference in the tree requests to display a dialog. Subclasses should override this method to display custom dialogs or to handle dialogs for custom preference classes.

Parameters
preference Preference!: The Preference object requesting the dialog

onNavigateToScreen

open fun onNavigateToScreen(preferenceScreen: PreferenceScreen!): Unit

Called by PreferenceScreen#onClick() in order to navigate to a new screen of preferences. Calls PreferenceFragmentCompat.OnPreferenceStartScreenCallback#onPreferenceStartScreen if the target fragment or containing activity implements PreferenceFragmentCompat.OnPreferenceStartScreenCallback.

Parameters
preferenceScreen PreferenceScreen!: The PreferenceScreen to navigate to

onPreferenceTreeClick

open fun onPreferenceTreeClick(preference: Preference!): Boolean

Called when a preference in the tree rooted at this PreferenceScreen has been clicked.

Parameters
preference Preference!: The preference that was clicked
Return
Boolean: Whether the click was handled

onSaveInstanceState

open fun onSaveInstanceState(@NonNull outState: Bundle): Unit

onStart

open fun onStart(): Unit

onStop

open fun onStop(): Unit

onViewCreated

open fun onViewCreated(@NonNull view: View, @Nullable savedInstanceState: Bundle?): Unit

scrollToPreference

open fun scrollToPreference(key: String!): Unit

scrollToPreference

open fun scrollToPreference(preference: Preference!): Unit

setDivider

open fun setDivider(divider: Drawable!): Unit

Sets the Drawable that will be drawn between each item in the list.

Note: If the drawable does not have an intrinsic height, you should also call setDividerHeight(int).

Parameters
divider Drawable!: The drawable to use android.R.attr#divider

setDividerHeight

open fun setDividerHeight(height: Int): Unit

Sets the height of the divider that will be drawn between each item in the list. Calling this will override the intrinsic height as set by setDivider(Drawable).

Parameters
height Int: The new height of the divider in pixels android.R.attr#dividerHeight

setPreferenceScreen

open fun setPreferenceScreen(preferenceScreen: PreferenceScreen!): Unit

Sets the root of the preference hierarchy that this fragment is showing.

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

setPreferencesFromResource

open fun setPreferencesFromResource(@XmlRes preferencesResId: Int, @Nullable key: String?): Unit

Inflates the given XML resource and replaces the current preference hierarchy (if any) with the preference hierarchy rooted at key.

Parameters
preferencesResId Int: The XML resource ID to inflate
key Int: The preference key of the PreferenceScreen to use as the root of the preference hierarchy, or null to use the root PreferenceScreen.

Protected methods

onCreateAdapter

protected open fun onCreateAdapter(preferenceScreen: PreferenceScreen!): RecyclerView.Adapter<RecyclerView.ViewHolder!>!

Creates the root adapter.

Parameters
preferenceScreen PreferenceScreen!: The PreferenceScreen object to create the adapter for
Return
RecyclerView.Adapter<RecyclerView.ViewHolder!>!: An adapter that contains the preferences contained in this PreferenceScreen