PreferenceFragment

Kotlin |Java

public abstract class PreferenceFragment
extends Fragment implements PreferenceManager.OnPreferenceTreeClickListener, PreferenceManager.OnDisplayPreferenceDialogListener, PreferenceManager.OnNavigateToScreenListener, DialogPreference.TargetFragment

java.lang.Object
↳	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

This class is deprecated.
Use PreferenceFragmentCompat instead

Shows a hierarchy of Preference objects as lists. These preferences will automatically save to SharedPreferences as the user interacts with them. To retrieve an instance of SharedPreferences that the preference hierarchy in this fragment will use, call PreferenceManager.getDefaultSharedPreferences(android.content.Context) 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(PreferenceScreen).

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 Activity meta-data

From an object hierarchy rooted with PreferenceScreen

To inflate from XML, use the addPreferencesFromResource(int). 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(PreferenceScreen).

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

Developer Guides

For information about building a settings screen using the AndroidX Preference library, see Settings.

See also:

Preference
PreferenceScreen

Summary

Nested classes
`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
`String`	`ARG_PREFERENCE_ROOT` This constant is deprecated. Use `PreferenceFragmentCompat` instead

Inherited constants

From interface android.content.ComponentCallbacks2

`int`	`TRIM_MEMORY_BACKGROUND`
`int`	`TRIM_MEMORY_COMPLETE`
`int`	`TRIM_MEMORY_MODERATE`
`int`	`TRIM_MEMORY_RUNNING_CRITICAL`
`int`	`TRIM_MEMORY_RUNNING_LOW`
`int`	`TRIM_MEMORY_RUNNING_MODERATE`
`int`	`TRIM_MEMORY_UI_HIDDEN`

Public constructors
`PreferenceFragment()`

Public methods
`void`	`addPreferencesFromResource(int preferencesResId)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`<T extends Preference> T`	`findPreference(CharSequence key)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`final RecyclerView`	`getListView()` This method is deprecated. Use `PreferenceFragmentCompat` instead
`PreferenceManager`	`getPreferenceManager()` This method is deprecated. Use `PreferenceFragmentCompat` instead
`PreferenceScreen`	`getPreferenceScreen()` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`onCreate(Bundle savedInstanceState)`
`RecyclerView.LayoutManager`	`onCreateLayoutManager()` This method is deprecated. Use `PreferenceFragmentCompat` instead
`abstract void`	`onCreatePreferences(Bundle savedInstanceState, String rootKey)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`RecyclerView`	`onCreateRecyclerView(LayoutInflater inflater, ViewGroup parent, Bundle savedInstanceState)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`View`	`onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)`
`void`	`onDestroyView()`
`void`	`onDisplayPreferenceDialog(Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`onNavigateToScreen(PreferenceScreen preferenceScreen)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`boolean`	`onPreferenceTreeClick(Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`onSaveInstanceState(Bundle outState)`
`void`	`onStart()`
`void`	`onStop()`
`void`	`onViewCreated(View view, Bundle savedInstanceState)`
`void`	`scrollToPreference(Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`scrollToPreference(String key)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`setDivider(Drawable divider)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`setDividerHeight(int height)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`setPreferenceScreen(PreferenceScreen preferenceScreen)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`setPreferencesFromResource(int preferencesResId, String key)` This method is deprecated. Use `PreferenceFragmentCompat` instead

Protected methods
`Adapter`	`onCreateAdapter(PreferenceScreen preferenceScreen)` This method is deprecated. Use `PreferenceFragmentCompat` instead

Inherited methods

From class


        
          android.app.Fragment

`void`	`dump(String arg0, FileDescriptor arg1, PrintWriter arg2, String[] arg3)`
`final boolean`	`equals(Object arg0)`
`final Activity`	`getActivity()`
`boolean`	`getAllowEnterTransitionOverlap()`
`boolean`	`getAllowReturnTransitionOverlap()`
`final Bundle`	`getArguments()`
`final FragmentManager`	`getChildFragmentManager()`
`Context`	`getContext()`
`Transition`	`getEnterTransition()`
`Transition`	`getExitTransition()`
`final FragmentManager`	`getFragmentManager()`
`final Object`	`getHost()`
`final int`	`getId()`
`final LayoutInflater`	`getLayoutInflater()`
`LoaderManager`	`getLoaderManager()`
`final Fragment`	`getParentFragment()`
`Transition`	`getReenterTransition()`
`final Resources`	`getResources()`
`final boolean`	`getRetainInstance()`
`Transition`	`getReturnTransition()`
`Transition`	`getSharedElementEnterTransition()`
`Transition`	`getSharedElementReturnTransition()`
`final String`	`getString(int arg0, Object... arg1)`
`final String`	`getString(int arg0)`
`final String`	`getTag()`
`final Fragment`	`getTargetFragment()`
`final int`	`getTargetRequestCode()`
`final CharSequence`	`getText(int arg0)`
`boolean`	`getUserVisibleHint()`
`View`	`getView()`
`final int`	`hashCode()`
`static Fragment`	`instantiate(Context arg0, String arg1)`
`static Fragment`	`instantiate(Context arg0, String arg1, Bundle arg2)`
`final boolean`	`isAdded()`
`final boolean`	`isDetached()`
`final boolean`	`isHidden()`
`final boolean`	`isInLayout()`
`final boolean`	`isRemoving()`
`final boolean`	`isResumed()`
`final boolean`	`isStateSaved()`
`final boolean`	`isVisible()`
`void`	`onActivityCreated(Bundle arg0)`
`void`	`onActivityResult(int arg0, int arg1, Intent arg2)`
`void`	`onAttach(Activity arg0)`
`void`	`onAttach(Context arg0)`
`void`	`onAttachFragment(Fragment arg0)`
`void`	`onConfigurationChanged(Configuration arg0)`
`boolean`	`onContextItemSelected(MenuItem arg0)`
`void`	`onCreate(Bundle arg0)`
`Animator`	`onCreateAnimator(int arg0, boolean arg1, int arg2)`
`void`	`onCreateContextMenu(ContextMenu arg0, View arg1, ContextMenu.ContextMenuInfo arg2)`
`void`	`onCreateOptionsMenu(Menu arg0, MenuInflater arg1)`
`View`	`onCreateView(LayoutInflater arg0, ViewGroup arg1, Bundle arg2)`
`void`	`onDestroy()`
`void`	`onDestroyOptionsMenu()`
`void`	`onDestroyView()`
`void`	`onDetach()`
`LayoutInflater`	`onGetLayoutInflater(Bundle arg0)`
`void`	`onHiddenChanged(boolean arg0)`
`void`	`onInflate(AttributeSet arg0, Bundle arg1)`
`void`	`onInflate(Activity arg0, AttributeSet arg1, Bundle arg2)`
`void`	`onInflate(Context arg0, AttributeSet arg1, Bundle arg2)`
`void`	`onLowMemory()`
`void`	`onMultiWindowModeChanged(boolean arg0)`
`void`	`onMultiWindowModeChanged(boolean arg0, Configuration arg1)`
`boolean`	`onOptionsItemSelected(MenuItem arg0)`
`void`	`onOptionsMenuClosed(Menu arg0)`
`void`	`onPause()`
`void`	`onPictureInPictureModeChanged(boolean arg0, Configuration arg1)`
`void`	`onPictureInPictureModeChanged(boolean arg0)`
`void`	`onPrepareOptionsMenu(Menu arg0)`
`void`	`onRequestPermissionsResult(int arg0, String[] arg1, int[] arg2)`
`void`	`onResume()`
`void`	`onSaveInstanceState(Bundle arg0)`
`void`	`onStart()`
`void`	`onStop()`
`void`	`onTrimMemory(int arg0)`
`void`	`onViewCreated(View arg0, Bundle arg1)`
`void`	`onViewStateRestored(Bundle arg0)`
`void`	`postponeEnterTransition()`
`void`	`registerForContextMenu(View arg0)`
`final void`	`requestPermissions(String[] arg0, int arg1)`
`void`	`setAllowEnterTransitionOverlap(boolean arg0)`
`void`	`setAllowReturnTransitionOverlap(boolean arg0)`
`void`	`setArguments(Bundle arg0)`
`void`	`setEnterSharedElementCallback(SharedElementCallback arg0)`
`void`	`setEnterTransition(Transition arg0)`
`void`	`setExitSharedElementCallback(SharedElementCallback arg0)`
`void`	`setExitTransition(Transition arg0)`
`void`	`setHasOptionsMenu(boolean arg0)`
`void`	`setInitialSavedState(Fragment.SavedState arg0)`
`void`	`setMenuVisibility(boolean arg0)`
`void`	`setReenterTransition(Transition arg0)`
`void`	`setRetainInstance(boolean arg0)`
`void`	`setReturnTransition(Transition arg0)`
`void`	`setSharedElementEnterTransition(Transition arg0)`
`void`	`setSharedElementReturnTransition(Transition arg0)`
`void`	`setTargetFragment(Fragment arg0, int arg1)`
`void`	`setUserVisibleHint(boolean arg0)`
`boolean`	`shouldShowRequestPermissionRationale(String arg0)`
`void`	`startActivity(Intent arg0)`
`void`	`startActivity(Intent arg0, Bundle arg1)`
`void`	`startActivityForResult(Intent arg0, int arg1)`
`void`	`startActivityForResult(Intent arg0, int arg1, Bundle arg2)`
`void`	`startIntentSenderForResult(IntentSender arg0, int arg1, Intent arg2, int arg3, int arg4, int arg5, Bundle arg6)`
`void`	`startPostponedEnterTransition()`
`String`	`toString()`
`void`	`unregisterForContextMenu(View arg0)`

From class


        
          java.lang.Object

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

From interface


        
          android.content.ComponentCallbacks2

abstract void onTrimMemory(int arg0)

From interface


        
          android.view.View.OnCreateContextMenuListener

abstract void onCreateContextMenu(ContextMenu arg0, View arg1, ContextMenu.ContextMenuInfo arg2)

From interface


        
          androidx.preference.PreferenceManager.OnPreferenceTreeClickListener


        abstract
        
        
        
        
        boolean


      onPreferenceTreeClick(Preference preference)

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

From interface


        
          androidx.preference.PreferenceManager.OnDisplayPreferenceDialogListener


      onDisplayPreferenceDialog(Preference preference)

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

From interface


        
          androidx.preference.PreferenceManager.OnNavigateToScreenListener


      onNavigateToScreen(PreferenceScreen preferenceScreen)

Called when a PreferenceScreen in the tree requests to navigate to its contents.

From interface


        
          androidx.preference.DialogPreference.TargetFragment


        abstract
        
        
        
        <T extends Preference>
        T


      findPreference(CharSequence key)

Finds a Preference with the given key.

From interface


        
          android.content.ComponentCallbacks

`abstract void`	`onConfigurationChanged(Configuration arg0)`
`abstract void`	`onLowMemory()`

Constants

ARG_PREFERENCE_ROOT

public static final String ARG_PREFERENCE_ROOT

This constant is deprecated.
Use PreferenceFragmentCompat instead

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

Constant Value: "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"

Public constructors

PreferenceFragment

public PreferenceFragment ()

Public methods

addPreferencesFromResource

public void addPreferencesFromResource (int preferencesResId)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

public T findPreference (CharSequence key)

This method is deprecated.
Use PreferenceFragmentCompat instead

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:

PreferenceGroup.findPreference(CharSequence)

getListView

public final RecyclerView getListView ()

This method is deprecated.
Use PreferenceFragmentCompat instead

Returns
`RecyclerView`

getPreferenceManager

public PreferenceManager getPreferenceManager ()

This method is deprecated.
Use PreferenceFragmentCompat instead

Returns the PreferenceManager used by this fragment.

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

getPreferenceScreen

public PreferenceScreen getPreferenceScreen ()

This method is deprecated.
Use PreferenceFragmentCompat instead

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

public void onCreate (Bundle savedInstanceState)

Parameters
`savedInstanceState`	`Bundle`

onCreateLayoutManager

public RecyclerView.LayoutManager onCreateLayoutManager ()

This method is deprecated.
Use PreferenceFragmentCompat instead

Called from onCreateRecyclerView(LayoutInflater, ViewGroup, Bundle) to create the RecyclerView.LayoutManager for the created RecyclerView.

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

onCreatePreferences

public abstract void onCreatePreferences (Bundle savedInstanceState, 
                String rootKey)

This method is deprecated.
Use PreferenceFragmentCompat instead

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`	`String`: If non-null, this preference fragment should be rooted at the `PreferenceScreen` with this key.

onCreateRecyclerView

public RecyclerView onCreateRecyclerView (LayoutInflater inflater, 
                ViewGroup parent, 
                Bundle savedInstanceState)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

public View onCreateView (LayoutInflater inflater, 
                ViewGroup container, 
                Bundle savedInstanceState)

Parameters
`inflater`	`LayoutInflater`
`container`	`ViewGroup`
`savedInstanceState`	`Bundle`

Returns
`View`

onDestroyView

public void onDestroyView ()

onDisplayPreferenceDialog

public void onDisplayPreferenceDialog (Preference preference)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

public void onNavigateToScreen (PreferenceScreen preferenceScreen)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

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

onPreferenceTreeClick

public boolean onPreferenceTreeClick (Preference preference)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

Parameters
`preference`	`Preference`: The preference that was clicked

Returns
`boolean`	Whether the click was handled

onSaveInstanceState

public void onSaveInstanceState (Bundle outState)

Parameters
`outState`	`Bundle`

onStart

public void onStart ()

onStop

public void onStop ()

onViewCreated

public void onViewCreated (View view, 
                Bundle savedInstanceState)

Parameters
`view`	`View`
`savedInstanceState`	`Bundle`

scrollToPreference

public void scrollToPreference (Preference preference)

This method is deprecated.
Use PreferenceFragmentCompat instead

Parameters
`preference`	`Preference`

scrollToPreference

public void scrollToPreference (String key)

This method is deprecated.
Use PreferenceFragmentCompat instead

Parameters
`key`	`String`

setDivider

public void setDivider (Drawable divider)

This method is deprecated.
Use PreferenceFragmentCompat instead

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 `R.attr.divider`

setDividerHeight

public void setDividerHeight (int height)

This method is deprecated.
Use PreferenceFragmentCompat instead

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 `R.attr.dividerHeight`

setPreferenceScreen

public void setPreferenceScreen (PreferenceScreen preferenceScreen)

This method is deprecated.
Use PreferenceFragmentCompat instead

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

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

setPreferencesFromResource

public void setPreferencesFromResource (int preferencesResId, 
                String key)

This method is deprecated.
Use PreferenceFragmentCompat instead

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`	`String`: 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 Adapter onCreateAdapter (PreferenceScreen preferenceScreen)

This method is deprecated.
Use PreferenceFragmentCompat instead

Creates the root adapter.

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

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

PreferenceFragment

Developer Guides

Summary

Nested classes

Constants

Inherited constants

Public constructors

Public methods

Protected methods

Inherited methods

Constants

ARG_PREFERENCE_ROOT

Public constructors

PreferenceFragment

Public methods

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 methods

onCreateAdapter