PreferenceFragment

Artifact: androidx.preference:preference

Added in 1.0.0

Deprecated in 1.1.0

Kotlin |Java

abstract class PreferenceFragment : Fragment, PreferenceManager.OnPreferenceTreeClickListener, PreferenceManager.OnDisplayPreferenceDialogListener, PreferenceManager.OnNavigateToScreenListener, DialogPreference.TargetFragment

kotlin.Any
↳	android.app.Fragment
	↳	androidx.preference.PreferenceFragment

Known direct subclasses

BaseLeanbackPreferenceFragment

BaseLeanbackPreferenceFragment

This class is deprecated.

Use BaseLeanbackPreferenceFragmentCompat

Known indirect subclasses

LeanbackPreferenceFragment

LeanbackPreferenceFragment

This class is deprecated.

Use LeanbackPreferenceFragmentCompat

Shows a hierarchy of Preference objects as lists. These preferences will automatically save to android.content.SharedPreferences as the user interacts with them. To retrieve an instance of android.content.SharedPreferences that the preference hierarchy in this fragment will use, call getDefaultSharedPreferences with a context in the same package as this fragment.

Furthermore, the preferences shown will follow the visual style of system preferences. It is easy to create a hierarchy of preferences (that can be shown on multiple screens) via XML. For these reasons, it is recommended to use this fragment (as a superclass) to deal with preferences in applications.

A PreferenceScreen object should be at the top of the preference hierarchy. Furthermore, subsequent PreferenceScreen in the hierarchy denote a screen break--that is the preferences contained within subsequent PreferenceScreen should be shown on another screen. The preference framework handles this by calling onNavigateToScreen.

The preference hierarchy can be formed in multiple ways:

From an XML file specifying the hierarchy
From different Activities that each specify its own preferences in an XML file via android.app.Activity meta-data
From an object hierarchy rooted with PreferenceScreen

To inflate from XML, use the addPreferencesFromResource. The root element should be a PreferenceScreen. Subsequent elements can point to actual Preference subclasses. As mentioned above, subsequent PreferenceScreen in the hierarchy will result in the screen break.

To specify an object hierarchy rooted with PreferenceScreen, use setPreferenceScreen.

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

See also
`Preference`
`PreferenceScreen`

Summary

Nested types
`interface PreferenceFragment.OnPreferenceDisplayDialogCallback` Interface that the fragment's containing activity should implement to be able to process preference items that wish to display a dialog.
`interface PreferenceFragment.OnPreferenceStartFragmentCallback` Interface that the fragment's containing activity should implement to be able to process preference items that wish to switch to a specified fragment.
`interface PreferenceFragment.OnPreferenceStartScreenCallback` 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
`const String!`	`ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"` This property is deprecated. Use `PreferenceFragmentCompat` instead

Constants

const String!

ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"

This property is deprecated.

Use PreferenceFragmentCompat instead

Public constructors
`PreferenceFragment()`

Public functions
`Unit`	`addPreferencesFromResource(preferencesResId: @XmlRes Int)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`T!`	`<T : Preference?> findPreference(key: CharSequence)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`RecyclerView!`	`getListView()` This function is deprecated. Use `PreferenceFragmentCompat` instead
`PreferenceManager!`	`getPreferenceManager()` This function is deprecated. Use `PreferenceFragmentCompat` instead
`PreferenceScreen!`	`getPreferenceScreen()` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`onCreate(savedInstanceState: Bundle?)` This function is deprecated.
`RecyclerView.LayoutManager`	`onCreateLayoutManager()` This function is deprecated. Use `PreferenceFragmentCompat` instead
`abstract Unit`	`onCreatePreferences(savedInstanceState: Bundle?, rootKey: String!)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`RecyclerView`	`onCreateRecyclerView( inflater: LayoutInflater, parent: ViewGroup, savedInstanceState: Bundle? )` This function is deprecated. Use `PreferenceFragmentCompat` instead
`View`	`onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? )` This function is deprecated.
`Unit`	`onDestroyView()` This function is deprecated.
`Unit`	`onDisplayPreferenceDialog(preference: Preference)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`onNavigateToScreen(preferenceScreen: PreferenceScreen)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Boolean`	`onPreferenceTreeClick(preference: Preference)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`onSaveInstanceState(outState: Bundle)` This function is deprecated.
`Unit`	`onStart()` This function is deprecated.
`Unit`	`onStop()` This function is deprecated.
`Unit`	`onViewCreated(view: View, savedInstanceState: Bundle?)` This function is deprecated.
`Unit`	`scrollToPreference(key: String)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`scrollToPreference(preference: Preference)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`setDivider(divider: Drawable?)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`setDividerHeight(height: Int)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`setPreferenceScreen(preferenceScreen: PreferenceScreen!)` This function is deprecated. Use `PreferenceFragmentCompat` instead
`Unit`	`setPreferencesFromResource(preferencesResId: @XmlRes Int, key: String?)` This function is deprecated. Use `PreferenceFragmentCompat` instead

Protected functions
`RecyclerView.Adapter`	`onCreateAdapter(preferenceScreen: PreferenceScreen)` This function is deprecated. Use `PreferenceFragmentCompat` instead

Protected functions

RecyclerView.Adapter

onCreateAdapter(preferenceScreen: PreferenceScreen)

This function is deprecated.

Use PreferenceFragmentCompat instead

Inherited Constants

From android.content.ComponentCallbacks2

`const Int`	`TRIM_MEMORY_BACKGROUND = 40`
`const Int`	`TRIM_MEMORY_COMPLETE = 80`
`const Int`	`TRIM_MEMORY_MODERATE = 60`
`const Int`	`TRIM_MEMORY_RUNNING_CRITICAL = 15`
`const Int`	`TRIM_MEMORY_RUNNING_LOW = 10`
`const Int`	`TRIM_MEMORY_RUNNING_MODERATE = 5`
`const Int`	`TRIM_MEMORY_UI_HIDDEN = 20`

Inherited functions

From android.app.Fragment

`Unit`	`dump( prefix: String!, fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>! )` This function is deprecated.
`Boolean`	`equals(o: Any!)` This function is deprecated.
`Activity!`	`getActivity()` This function is deprecated.
`Boolean`	`getAllowEnterTransitionOverlap()` This function is deprecated.
`Boolean`	`getAllowReturnTransitionOverlap()` This function is deprecated.
`Bundle!`	`getArguments()` This function is deprecated.
`FragmentManager!`	`getChildFragmentManager()` This function is deprecated.
`Context!`	`getContext()` This function is deprecated.
`Transition!`	`getEnterTransition()` This function is deprecated.
`Transition!`	`getExitTransition()` This function is deprecated.
`FragmentManager!`	`getFragmentManager()` This function is deprecated.
`Any!`	`getHost()` This function is deprecated.
`Int`	`getId()` This function is deprecated.
`LayoutInflater!`	`getLayoutInflater()` This function is deprecated.
`LoaderManager!`	`getLoaderManager()` This function is deprecated.
`Fragment!`	`getParentFragment()` This function is deprecated.
`Transition!`	`getReenterTransition()` This function is deprecated.
`Resources!`	`getResources()` This function is deprecated.
`Boolean`	`getRetainInstance()` This function is deprecated.
`Transition!`	`getReturnTransition()` This function is deprecated.
`Transition!`	`getSharedElementEnterTransition()` This function is deprecated.
`Transition!`	`getSharedElementReturnTransition()` This function is deprecated.
`String!`	`getString(resId: Int)` This function is deprecated.
`String!`	`getTag()` This function is deprecated.
`Fragment!`	`getTargetFragment()` This function is deprecated.
`Int`	`getTargetRequestCode()` This function is deprecated.
`CharSequence!`	`getText(resId: Int)` This function is deprecated.
`Boolean`	`getUserVisibleHint()` This function is deprecated.
`View!`	`getView()` This function is deprecated.
`Int`	`hashCode()` This function is deprecated.
`java-static Fragment!`	`instantiate(context: Context!, fname: String!)` This function is deprecated.
`Boolean`	`isAdded()` This function is deprecated.
`Boolean`	`isDetached()` This function is deprecated.
`Boolean`	`isHidden()` This function is deprecated.
`Boolean`	`isInLayout()` This function is deprecated.
`Boolean`	`isRemoving()` This function is deprecated.
`Boolean`	`isResumed()` This function is deprecated.
`Boolean`	`isStateSaved()` This function is deprecated.
`Boolean`	`isVisible()` This function is deprecated.
`Unit`	`onActivityCreated(savedInstanceState: Bundle!)` This function is deprecated.
`Unit`	`onActivityResult(requestCode: Int, resultCode: Int, data: Intent!)` This function is deprecated.
`Unit`	`onAttach(context: Context!)` This function is deprecated.
`Unit`	`onAttachFragment(childFragment: Fragment!)` This function is deprecated.
`Unit`	`onConfigurationChanged(newConfig: Configuration!)` This function is deprecated.
`Boolean`	`onContextItemSelected(item: MenuItem!)` This function is deprecated.
`Animator!`	`onCreateAnimator(transit: Int, enter: Boolean, nextAnim: Int)` This function is deprecated.
`Unit`	`onCreateContextMenu( menu: ContextMenu!, v: View!, menuInfo: ContextMenu.ContextMenuInfo! )` This function is deprecated.
`Unit`	`onCreateOptionsMenu(menu: Menu!, inflater: MenuInflater!)` This function is deprecated.
`Unit`	`onDestroy()` This function is deprecated.
`Unit`	`onDestroyOptionsMenu()` This function is deprecated.
`Unit`	`onDetach()` This function is deprecated.
`LayoutInflater!`	`onGetLayoutInflater(savedInstanceState: Bundle!)` This function is deprecated.
`Unit`	`onHiddenChanged(hidden: Boolean)` This function is deprecated.
`Unit`	`onInflate(attrs: AttributeSet!, savedInstanceState: Bundle!)` This function is deprecated.
`Unit`	`onLowMemory()` This function is deprecated.
`Unit`	`onMultiWindowModeChanged( isInMultiWindowMode: Boolean, newConfig: Configuration! )` This function is deprecated.
`Boolean`	`onOptionsItemSelected(item: MenuItem!)` This function is deprecated.
`Unit`	`onOptionsMenuClosed(menu: Menu!)` This function is deprecated.
`Unit`	`onPause()` This function is deprecated.
`Unit`	`onPictureInPictureModeChanged( isInPictureInPictureMode: Boolean, newConfig: Configuration! )` This function is deprecated.
`Unit`	`onPrepareOptionsMenu(menu: Menu!)` This function is deprecated.
`Unit`	`onRequestPermissionsResult( requestCode: Int, permissions: Array<String!>!, grantResults: IntArray! )` This function is deprecated.
`Unit`	`onResume()` This function is deprecated.
`Unit`	`onTrimMemory(level: Int)` This function is deprecated.
`Unit`	`onViewStateRestored(savedInstanceState: Bundle!)` This function is deprecated.
`Unit`	`postponeEnterTransition()` This function is deprecated.
`Unit`	`registerForContextMenu(view: View!)` This function is deprecated.
`Unit`	`requestPermissions(permissions: Array<String!>!, requestCode: Int)` This function is deprecated.
`Unit`	`setAllowEnterTransitionOverlap(allow: Boolean)` This function is deprecated.
`Unit`	`setAllowReturnTransitionOverlap(allow: Boolean)` This function is deprecated.
`Unit`	`setArguments(args: Bundle!)` This function is deprecated.
`Unit`	`setEnterSharedElementCallback(callback: SharedElementCallback!)` This function is deprecated.
`Unit`	`setEnterTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setExitSharedElementCallback(callback: SharedElementCallback!)` This function is deprecated.
`Unit`	`setExitTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setHasOptionsMenu(hasMenu: Boolean)` This function is deprecated.
`Unit`	`setInitialSavedState(state: Fragment.SavedState!)` This function is deprecated.
`Unit`	`setMenuVisibility(menuVisible: Boolean)` This function is deprecated.
`Unit`	`setReenterTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setRetainInstance(retain: Boolean)` This function is deprecated.
`Unit`	`setReturnTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setSharedElementEnterTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setSharedElementReturnTransition(transition: Transition!)` This function is deprecated.
`Unit`	`setTargetFragment(fragment: Fragment!, requestCode: Int)` This function is deprecated.
`Unit`	`setUserVisibleHint(isVisibleToUser: Boolean)` This function is deprecated.
`Boolean`	`shouldShowRequestPermissionRationale(permission: String!)` This function is deprecated.
`Unit`	`startActivity(intent: Intent!)` This function is deprecated.
`Unit`	`startActivityForResult(intent: Intent!, requestCode: Int)` This function is deprecated.
`Unit`	`startIntentSenderForResult( intent: IntentSender!, requestCode: Int, fillInIntent: Intent!, flagsMask: Int, flagsValues: Int, extraFlags: Int, options: Bundle! )` This function is deprecated.
`Unit`	`startPostponedEnterTransition()` This function is deprecated.
`String!`	`toString()` This function is deprecated.
`Unit`	`unregisterForContextMenu(view: View!)` This function is deprecated.

Constants

ARG_PREFERENCE_ROOT

Added in 1.0.0

Deprecated in 1.1.0

const val ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT": String!

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

Public constructors

PreferenceFragment

Added in 1.0.0

Deprecated in 1.1.0

PreferenceFragment()

Public functions

addPreferencesFromResource

Added in 1.0.0

Deprecated in 1.1.0

fun addPreferencesFromResource(preferencesResId: @XmlRes Int): Unit

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

Parameters
`preferencesResId: @XmlRes Int`	The XML resource ID to inflate

findPreference

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

fun <T : Preference?> findPreference(key: CharSequence): T!

Finds a Preference based on its key.

Parameters
`key: CharSequence`	The key of the preference to retrieve

Returns
`T!`	The `Preference` with the key, or null

See also
`findPreference`

getListView

Added in 1.0.0

Deprecated in 1.1.0

fun getListView(): RecyclerView!

getPreferenceManager

Added in 1.0.0

Deprecated in 1.1.0

fun getPreferenceManager(): PreferenceManager!

Returns the PreferenceManager used by this fragment.

Returns
`PreferenceManager!`	The `PreferenceManager` used by this fragment

getPreferenceScreen

Added in 1.0.0

Deprecated in 1.1.0

fun getPreferenceScreen(): PreferenceScreen!

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

Returns
`PreferenceScreen!`	The `PreferenceScreen` that is the root of the preference hierarchy

onCreate

Added in 1.0.0

Deprecated in 1.1.0

fun onCreate(savedInstanceState: Bundle?): Unit

onCreateLayoutManager

Added in 1.0.0

Deprecated in 1.1.0

fun onCreateLayoutManager(): RecyclerView.LayoutManager

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

Returns
`RecyclerView.LayoutManager`	A new `RecyclerView.LayoutManager` instance

onCreatePreferences

Added in 1.0.0

Deprecated in 1.1.0

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

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

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

onCreateRecyclerView

Added in 1.0.0

Deprecated in 1.1.0

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: ViewGroup`	The parent view 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: Bundle?`	If non-null, this view is being re-constructed from a previous saved state as given here.

Returns
`RecyclerView`	A new `RecyclerView` object to be placed into the view hierarchy

onCreateView

Added in 1.0.0

Deprecated in 1.1.0

fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
): View

onDestroyView

Added in 1.0.0

Deprecated in 1.1.0

fun onDestroyView(): Unit

onDisplayPreferenceDialog

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

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

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

fun onNavigateToScreen(preferenceScreen: PreferenceScreen): Unit

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

Parameters
`preferenceScreen: PreferenceScreen`	The `PreferenceScreen` to navigate to

onPreferenceTreeClick

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

fun onPreferenceTreeClick(preference: Preference): Boolean

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

onSaveInstanceState

Added in 1.0.0

Deprecated in 1.1.0

fun onSaveInstanceState(outState: Bundle): Unit

onStart

Added in 1.0.0

Deprecated in 1.1.0

fun onStart(): Unit

onStop

Added in 1.0.0

Deprecated in 1.1.0

fun onStop(): Unit

onViewCreated

Added in 1.0.0

Deprecated in 1.1.0

fun onViewCreated(view: View, savedInstanceState: Bundle?): Unit

scrollToPreference

Added in 1.0.0

Deprecated in 1.1.0

fun scrollToPreference(key: String): Unit

scrollToPreference

Added in 1.0.0

Deprecated in 1.1.0

fun scrollToPreference(preference: Preference): Unit

setDivider

Added in 1.0.0

Deprecated in 1.1.0

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.

Parameters
`divider: Drawable?`	The drawable to use `divider`

setDividerHeight

Added in 1.0.0

Deprecated in 1.1.0

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.

Parameters
`height: Int`	The new height of the divider in pixels `dividerHeight`

setPreferenceScreen

Added in 1.0.0

Deprecated in 1.1.0

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

Added in 1.0.0

Deprecated in 1.1.0

fun setPreferencesFromResource(preferencesResId: @XmlRes Int, 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: @XmlRes Int`	The XML resource ID to inflate
`key: String?`	The preference key of the `PreferenceScreen` to use as the root of the preference hierarchy, or `null` to use the root `PreferenceScreen`.

Protected functions

onCreateAdapter

Added in 1.0.0

Deprecated in 1.1.0

protected fun onCreateAdapter(preferenceScreen: PreferenceScreen): RecyclerView.Adapter

Creates the root adapter.

Parameters
`preferenceScreen: PreferenceScreen`	The `PreferenceScreen` object to create the adapter for

Returns
`RecyclerView.Adapter`	An adapter that contains the preferences contained in this `PreferenceScreen`

PreferenceFragment

Summary

Nested types

Constants

Public constructors

Public functions

Protected functions

Inherited Constants

Inherited functions

Constants

ARG_PREFERENCE_ROOT

Public constructors

PreferenceFragment

Public functions

addPreferencesFromResource

findPreference

getListView

getPreferenceManager

getPreferenceScreen

onCreate

onCreateLayoutManager

onCreatePreferences

onCreateRecyclerView

onCreateView

onDestroyView

onDisplayPreferenceDialog

onNavigateToScreen

onPreferenceTreeClick

onSaveInstanceState

onStart

onStop

onViewCreated

scrollToPreference

scrollToPreference

setDivider

setDividerHeight

setPreferenceScreen

setPreferencesFromResource

Protected functions

onCreateAdapter