PreferenceFragment

Artifact: androidx.preference:preference

Added in 1.0.0

Deprecated in 1.1.0

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

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
`public 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.
`public 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.
`public 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
`static final String`	`ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"` This field is deprecated. Use `PreferenceFragmentCompat` instead

Constants

static final String

ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"

This field is deprecated.

Use PreferenceFragmentCompat instead

Public constructors
`PreferenceFragment()`

Public methods
`void`	`addPreferencesFromResource(@XmlRes int preferencesResId)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`T`	`<T extends Preference> findPreference(@NonNull 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(@Nullable Bundle savedInstanceState)` This method is deprecated.
`@NonNull RecyclerView.LayoutManager`	`onCreateLayoutManager()` This method is deprecated. Use `PreferenceFragmentCompat` instead
`abstract void`	`onCreatePreferences(@Nullable Bundle savedInstanceState, String rootKey)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`@NonNull RecyclerView`	`onCreateRecyclerView( @NonNull LayoutInflater inflater, @NonNull ViewGroup parent, @Nullable Bundle savedInstanceState )` This method is deprecated. Use `PreferenceFragmentCompat` instead
`@NonNull View`	`onCreateView( @NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState )` This method is deprecated.
`void`	`onDestroyView()` This method is deprecated.
`void`	`onDisplayPreferenceDialog(@NonNull Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`onNavigateToScreen(@NonNull PreferenceScreen preferenceScreen)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`boolean`	`onPreferenceTreeClick(@NonNull Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`onSaveInstanceState(@NonNull Bundle outState)` This method is deprecated.
`void`	`onStart()` This method is deprecated.
`void`	`onStop()` This method is deprecated.
`void`	`onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState)` This method is deprecated.
`void`	`scrollToPreference(@NonNull String key)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`scrollToPreference(@NonNull Preference preference)` This method is deprecated. Use `PreferenceFragmentCompat` instead
`void`	`setDivider(@Nullable 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( @XmlRes int preferencesResId, @Nullable String key )` This method is deprecated. Use `PreferenceFragmentCompat` instead

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

Protected methods

@NonNull RecyclerView.Adapter

onCreateAdapter(@NonNull PreferenceScreen preferenceScreen)

This method is deprecated.

Use PreferenceFragmentCompat instead

Inherited Constants

From android.content.ComponentCallbacks2

`static final int`	`TRIM_MEMORY_BACKGROUND = 40`
`static final int`	`TRIM_MEMORY_COMPLETE = 80`
`static final int`	`TRIM_MEMORY_MODERATE = 60`
`static final int`	`TRIM_MEMORY_RUNNING_CRITICAL = 15`
`static final int`	`TRIM_MEMORY_RUNNING_LOW = 10`
`static final int`	`TRIM_MEMORY_RUNNING_MODERATE = 5`
`static final int`	`TRIM_MEMORY_UI_HIDDEN = 20`

Inherited methods

From android.app.Fragment

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

Constants

ARG_PREFERENCE_ROOT

Added in 1.0.0

Deprecated in 1.1.0

public static final String ARG_PREFERENCE_ROOT = "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"

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

public PreferenceFragment()

Public methods

addPreferencesFromResource

Added in 1.0.0

Deprecated in 1.1.0

public void addPreferencesFromResource(@XmlRes int preferencesResId)

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

Parameters
`@XmlRes int preferencesResId`	The XML resource ID to inflate

findPreference

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

public T <T extends Preference> findPreference(@NonNull CharSequence key)

Finds a Preference based on its key.

Parameters
`@NonNull CharSequence key`	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

public final RecyclerView getListView()

getPreferenceManager

Added in 1.0.0

Deprecated in 1.1.0

public PreferenceManager getPreferenceManager()

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

public PreferenceScreen getPreferenceScreen()

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

public void onCreate(@Nullable Bundle savedInstanceState)

onCreateLayoutManager

Added in 1.0.0

Deprecated in 1.1.0

public @NonNull RecyclerView.LayoutManager onCreateLayoutManager()

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

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

onCreatePreferences

Added in 1.0.0

Deprecated in 1.1.0

public abstract void onCreatePreferences(@Nullable Bundle savedInstanceState, String rootKey)

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
`@Nullable Bundle savedInstanceState`	If the fragment is being re-created from a previous saved state, this is the state.
`String rootKey`	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

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

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

Parameters
`@NonNull LayoutInflater inflater`	The LayoutInflater object that can be used to inflate the `RecyclerView`.
`@NonNull ViewGroup parent`	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.
`@Nullable Bundle savedInstanceState`	If non-null, this view is being re-constructed from a previous saved state as given here.

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

onCreateView

Added in 1.0.0

Deprecated in 1.1.0

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

onDestroyView

Added in 1.0.0

Deprecated in 1.1.0

public void onDestroyView()

onDisplayPreferenceDialog

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

public void onDisplayPreferenceDialog(@NonNull Preference preference)

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
`@NonNull Preference preference`	The `Preference` object requesting the dialog

onNavigateToScreen

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

public void onNavigateToScreen(@NonNull PreferenceScreen preferenceScreen)

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
`@NonNull PreferenceScreen preferenceScreen`	The `PreferenceScreen` to navigate to

onPreferenceTreeClick

Added in 1.3.0-alpha01

Deprecated in 1.3.0-alpha01

public boolean onPreferenceTreeClick(@NonNull Preference preference)

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

onSaveInstanceState

Added in 1.0.0

Deprecated in 1.1.0

public void onSaveInstanceState(@NonNull Bundle outState)

onStart

Added in 1.0.0

Deprecated in 1.1.0

public void onStart()

onStop

Added in 1.0.0

Deprecated in 1.1.0

public void onStop()

onViewCreated

Added in 1.0.0

Deprecated in 1.1.0

public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState)

scrollToPreference

Added in 1.0.0

Deprecated in 1.1.0

public void scrollToPreference(@NonNull String key)

scrollToPreference

Added in 1.0.0

Deprecated in 1.1.0

public void scrollToPreference(@NonNull Preference preference)

setDivider

Added in 1.0.0

Deprecated in 1.1.0

public void setDivider(@Nullable Drawable divider)

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
`@Nullable Drawable divider`	The drawable to use `divider`

setDividerHeight

Added in 1.0.0

Deprecated in 1.1.0

public void setDividerHeight(int height)

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
`int height`	The new height of the divider in pixels `dividerHeight`

setPreferenceScreen

Added in 1.0.0

Deprecated in 1.1.0

public void setPreferenceScreen(PreferenceScreen preferenceScreen)

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

public void setPreferencesFromResource(
    @XmlRes int preferencesResId,
    @Nullable String key
)

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

Parameters
`@XmlRes int preferencesResId`	The XML resource ID to inflate
`@Nullable String key`	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

Added in 1.0.0

Deprecated in 1.1.0

protected @NonNull RecyclerView.Adapter onCreateAdapter(@NonNull PreferenceScreen preferenceScreen)

Creates the root adapter.

Parameters
`@NonNull PreferenceScreen preferenceScreen`	The `PreferenceScreen` object to create the adapter for

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

PreferenceFragment

Summary

Nested types

Constants

Public constructors

Public methods

Protected methods

Inherited Constants

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