PreferenceFragmentCompat

Artifact: androidx.preference:preference

Added in 1.0.0

Kotlin |Java

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

java.lang.Object
↳	androidx.fragment.app.Fragment
	↳	androidx.preference.PreferenceFragmentCompat

Known direct subclasses

BaseLeanbackPreferenceFragmentCompat

BaseLeanbackPreferenceFragmentCompat

This fragment provides a preference fragment with leanback-style behavior, suitable for embedding into broader UI elements.

Known indirect subclasses

LeanbackPreferenceFragmentCompat

LeanbackPreferenceFragmentCompat

This fragment provides a fully decorated leanback-style preference fragment, including a list background and header.

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 getDefaultSharedPreferences 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. An example example XML resource is shown further down.

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

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

Sample Code

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

<PreferenceScreen
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto">

    <PreferenceCategory
            android:title="@string/basic_preferences">

        <Preference
                android:key="preference"
                android:title="@string/title_basic_preference"
                android:summary="@string/summary_basic_preference"/>

        <Preference
                android:key="stylized"
                android:title="@string/title_stylish_preference"
                android:summary="@string/summary_stylish_preference"/>

        <Preference
                android:key="icon"
                android:title="@string/title_icon_preference"
                android:summary="@string/summary_icon_preference"
                android:icon="@android:drawable/ic_menu_camera"/>

        <Preference
                android:key="single_line_title"
                android:title="@string/title_single_line_title_preference"
                android:summary="@string/summary_single_line_title_preference"
                app:singleLineTitle="true"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/widgets">

        <CheckBoxPreference
                android:key="checkbox"
                android:title="@string/title_checkbox_preference"
                android:summary="@string/summary_checkbox_preference"/>

        <SwitchPreferenceCompat
                android:key="switch"
                android:title="@string/title_switch_preference"
                android:summary="@string/summary_switch_preference"/>

        <DropDownPreference
                android:key="dropdown"
                android:title="@string/title_dropdown_preference"
                android:entries="@array/entries"
                app:useSimpleSummaryProvider="true"
                android:entryValues="@array/entry_values"/>

        <SeekBarPreference
                android:key="seekbar"
                android:title="@string/title_seekbar_preference"
                android:max="10"
                android:defaultValue="5"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/dialogs">

        <EditTextPreference
                android:key="edittext"
                android:title="@string/title_edittext_preference"
                app:useSimpleSummaryProvider="true"
                android:dialogTitle="@string/dialog_title_edittext_preference"/>

        <ListPreference
                android:key="list"
                android:title="@string/title_list_preference"
                app:useSimpleSummaryProvider="true"
                android:entries="@array/entries"
                android:entryValues="@array/entry_values"
                android:dialogTitle="@string/dialog_title_list_preference"/>

        <MultiSelectListPreference
                android:key="multi_select_list"
                android:title="@string/title_multi_list_preference"
                android:summary="@string/summary_multi_list_preference"
                android:entries="@array/entries"
                android:entryValues="@array/entry_values"
                android:dialogTitle="@string/dialog_title_multi_list_preference"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:key="advanced"
            android:title="@string/advanced_attributes"
            app:initialExpandedChildrenCount="1">

        <Preference
                android:key="expandable"
                android:title="@string/title_expandable_preference"
                android:summary="@string/summary_expandable_preference"/>

        <Preference
                android:title="@string/title_intent_preference"
                android:summary="@string/summary_intent_preference">

            <intent android:action="android.intent.action.VIEW"
                    android:data="http://www.android.com"/>

        </Preference>

        <SwitchPreferenceCompat
                android:key="parent"
                android:title="@string/title_parent_preference"
                android:summary="@string/summary_parent_preference"/>

        <SwitchPreferenceCompat
                android:key="child"
                android:dependency="parent"
                android:title="@string/title_child_preference"
                android:summary="@string/summary_child_preference"/>

        <SwitchPreferenceCompat
                android:key="toggle_summary"
                android:title="@string/title_toggle_summary_preference"
                android:summaryOn="@string/summary_on_toggle_summary_preference"
                android:summaryOff="@string/summary_off_toggle_summary_preference"/>

        <Preference
                android:key="copyable"
                android:title="@string/title_copyable_preference"
                android:summary="@string/summary_copyable_preference"
                android:selectable="false"
                app:enableCopying="true"/>
    </PreferenceCategory>

</PreferenceScreen>

The fragment that loads the XML resource is as follows:

public static class DemoFragment extends PreferenceFragmentCompat {

    @Override
    public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
        // Load the preferences from an XML resource
        setPreferencesFromResource(R.xml.preferences, rootKey);
    }
}

See also
`Preference`
`PreferenceScreen`

Summary

Nested types
`public interface PreferenceFragmentCompat.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 PreferenceFragmentCompat.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 PreferenceFragmentCompat.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"` Fragment argument used to specify the tag of the desired root `PreferenceScreen` object.

Public constructors
`PreferenceFragmentCompat()`

Public methods
`void`	`addPreferencesFromResource(@XmlRes int preferencesResId)` Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.
`@Nullable T`	`<T extends Preference> findPreference(@NonNull CharSequence key)` Finds a `Preference` with the given key.
`final RecyclerView`	`getListView()`
`PreferenceManager`	`getPreferenceManager()` Returns the `PreferenceManager` used by this fragment.
`PreferenceScreen`	`getPreferenceScreen()` Gets the root of the preference hierarchy that this fragment is showing.
`void`	`onCreate(@Nullable Bundle savedInstanceState)` Called to do initial creation of a fragment.
`@NonNull RecyclerView.LayoutManager`	`onCreateLayoutManager()` Called from `onCreateRecyclerView` to create the `RecyclerView.LayoutManager` for the created `RecyclerView`.
`abstract void`	`onCreatePreferences( @Nullable Bundle savedInstanceState, @Nullable String rootKey )` Called during `onCreate` to supply the preferences for this fragment.
`@NonNull RecyclerView`	`onCreateRecyclerView( @NonNull LayoutInflater inflater, @NonNull ViewGroup parent, @Nullable Bundle savedInstanceState )` Creates the `RecyclerView` used to display the preferences.
`@NonNull View`	`onCreateView( @NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState )` Called to have the fragment instantiate its user interface view.
`void`	`onDestroyView()` Called when the view previously created by `onCreateView` has been detached from the fragment.
`void`	`onDisplayPreferenceDialog(@NonNull Preference preference)` Called when a preference in the tree requests to display a dialog.
`void`	`onNavigateToScreen(@NonNull PreferenceScreen preferenceScreen)` Called by `onClick` in order to navigate to a new screen of preferences.
`boolean`	`onPreferenceTreeClick(@NonNull Preference preference)` Called when a preference in the tree rooted at this has been clicked.
`void`	`onSaveInstanceState(@NonNull Bundle outState)` Called to ask the fragment to save its current dynamic state, so it can later be reconstructed in a new instance if its process is restarted.
`void`	`onStart()` Called when the Fragment is visible to the user.
`void`	`onStop()` Called when the Fragment is no longer started.
`void`	`onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState)` Called immediately after `onCreateView` has returned, but before any saved state has been restored in to the view.
`void`	`scrollToPreference(@NonNull String key)`
`void`	`scrollToPreference(@NonNull Preference preference)`
`void`	`setDivider(@Nullable Drawable divider)` Sets the `Drawable` that will be drawn between each item in the list.
`void`	`setDividerHeight(int height)` Sets the height of the divider that will be drawn between each item in the list.
`void`	`setPreferenceScreen(PreferenceScreen preferenceScreen)` Sets the root of the preference hierarchy that this fragment is showing.
`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`.

Protected methods
`@NonNull RecyclerView.Adapter`	`onCreateAdapter(@NonNull PreferenceScreen preferenceScreen)` Creates the root adapter.

Inherited methods

From androidx.activity.result.ActivityResultCaller

abstract ActivityResultLauncher<I>

<I, O> registerForActivityResult(
    ActivityResultContract<I, O> contract,
    ActivityResultCallback<O> callback
)

From android.content.ComponentCallbacks

`abstract void`	`onConfigurationChanged(Configuration p)`
`abstract void`	`onLowMemory()` This method is deprecated.

From androidx.fragment.app.Fragment

`void`	`dump( @NonNull String prefix, @Nullable FileDescriptor fd, @NonNull PrintWriter writer, @Nullable String[] args )` Print the Fragments's state into the given stream.
`final boolean`	`equals(@Nullable Object o)` Subclasses can not override equals().
`final @Nullable FragmentActivity`	`getActivity()` Return the `FragmentActivity` this fragment is currently associated with.
`boolean`	`getAllowEnterTransitionOverlap()` Returns whether the the exit transition and enter transition overlap or not.
`boolean`	`getAllowReturnTransitionOverlap()` Returns whether the the return transition and reenter transition overlap or not.
`final @Nullable Bundle`	`getArguments()` Return the arguments supplied when the fragment was instantiated, if any.
`final @NonNull FragmentManager`	`getChildFragmentManager()` Return a private FragmentManager for placing and managing Fragments inside of this Fragment.
`@Nullable Context`	`getContext()` Return the `Context` this fragment is currently associated with.
`@NonNull CreationExtras`	`@CallSuper getDefaultViewModelCreationExtras()` The `Fragment's arguments` when this is first called will be used as the defaults to any `androidx.lifecycle.SavedStateHandle` passed to a view model created using this extra.
`@NonNull ViewModelProvider.Factory`	`getDefaultViewModelProviderFactory()`
`@Nullable Object`	`getEnterTransition()` Returns the Transition that will be used to move Views into the initial scene.
`@Nullable Object`	`getExitTransition()` Returns the Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack.
`final @Nullable FragmentManager`	`getFragmentManager()` This method is deprecated. This has been removed in favor of `getParentFragmentManager()` which throws an `IllegalStateException` if the FragmentManager is null.
`final @Nullable Object`	`getHost()` Return the host object of this fragment.
`final int`	`getId()` Return the identifier this fragment is known by.
`final @NonNull LayoutInflater`	`getLayoutInflater()` Returns the cached LayoutInflater used to inflate Views of this Fragment.
`@NonNull Lifecycle`	`getLifecycle()` Overriding this method is no longer supported and this method will be made `final` in a future version of Fragment.
`@NonNull LoaderManager`	`getLoaderManager()` This method is deprecated. Use `LoaderManager.getInstance(this)`.
`final @Nullable Fragment`	`getParentFragment()` Returns the parent Fragment containing this Fragment.
`final @NonNull FragmentManager`	`getParentFragmentManager()` Return the FragmentManager for interacting with fragments associated with this fragment's activity.
`@Nullable Object`	`getReenterTransition()` Returns the Transition that will be used to move Views in to the scene when returning due to popping a back stack.
`final @NonNull Resources`	`getResources()` Return `requireActivity().getResources()`.
`final boolean`	`getRetainInstance()` This method is deprecated. Instead of retaining the Fragment itself, use a non-retained Fragment and keep retained state in a ViewModel attached to that Fragment.
`@Nullable Object`	`getReturnTransition()` Returns the Transition that will be used to move Views out of the scene when the Fragment is preparing to be removed, hidden, or detached because of popping the back stack.
`final @NonNull SavedStateRegistry`	`getSavedStateRegistry()`
`@Nullable Object`	`getSharedElementEnterTransition()` Returns the Transition that will be used for shared elements transferred into the content Scene.
`@Nullable Object`	`getSharedElementReturnTransition()` Return the Transition that will be used for shared elements transferred back during a pop of the back stack.
`final @NonNull String`	`getString(@StringRes int resId)` Return a localized string from the application's package's default string table.
`final @NonNull String`	`getString(@StringRes int resId, @Nullable Object[] formatArgs)` Return a localized formatted string from the application's package's default string table, substituting the format arguments as defined in `java.util.Formatter` and format.
`final @Nullable String`	`getTag()` Get the tag name of the fragment, if specified.
`final @Nullable Fragment`	`getTargetFragment()` This method is deprecated. Instead of using a target fragment to pass results, use `setFragmentResult` to deliver results to `FragmentResultListener` instances registered by other fragments via `setFragmentResultListener`.
`final int`	`getTargetRequestCode()` This method is deprecated. When using the target fragment replacement of `setFragmentResultListener` and `setFragmentResult`, consider using `setArguments` to pass a `requestKey` if you need to support dynamic request keys.
`final @NonNull CharSequence`	`getText(@StringRes int resId)` Return a localized, styled CharSequence from the application's package's default string table.
`boolean`	`getUserVisibleHint()` This method is deprecated. Use `setMaxLifecycle` instead.
`@Nullable View`	`getView()` Get the root view for the fragment's layout (the one returned by `onCreateView`), if provided.
`@NonNull LifecycleOwner`	`@MainThread getViewLifecycleOwner()` Get a `LifecycleOwner` that represents the `Fragment's View` lifecycle.
`@NonNull LiveData<LifecycleOwner>`	`getViewLifecycleOwnerLiveData()` Retrieve a `LiveData` which allows you to observe the `lifecycle of the Fragment's View`.
`@NonNull ViewModelStore`	`getViewModelStore()` Returns the `ViewModelStore` associated with this Fragment
`final int`	`hashCode()` Subclasses can not override hashCode().
`static @NonNull Fragment`	`instantiate(@NonNull Context context, @NonNull String fname)` This method is deprecated. Use `getFragmentFactory` and `instantiate`
`static @NonNull Fragment`	`instantiate( @NonNull Context context, @NonNull String fname, @Nullable Bundle args )` This method is deprecated. Use `getFragmentFactory` and `instantiate`, manually calling `setArguments` on the returned Fragment.
`final boolean`	`isAdded()` Return true if the fragment is currently added to its activity.
`final boolean`	`isDetached()` Return true if the fragment has been explicitly detached from the UI.
`final boolean`	`isHidden()` Return true if the fragment has been hidden.
`final boolean`	`isInLayout()` Return true if the layout is included as part of an activity view hierarchy via the tag.
`final boolean`	`isRemoving()` Return true if this fragment is currently being removed from its activity.
`final boolean`	`isResumed()` Return true if the fragment is in the resumed state.
`final boolean`	`isStateSaved()` Returns true if this fragment is added and its state has already been saved by its host.
`final boolean`	`isVisible()` Return true if the fragment is currently visible to the user.
`void`	`@MainThread @CallSuper onActivityCreated(@Nullable Bundle savedInstanceState)` This method is deprecated. use `onViewCreated` for code touching the view created by `onCreateView` and `onCreate` for other initialization.
`void`	`onActivityResult(int requestCode, int resultCode, @Nullable Intent data)` This method is deprecated. This method has been deprecated in favor of using the Activity Result API which brings increased type safety via an `ActivityResultContract` and the prebuilt contracts for common intents available in `androidx.activity.result.contract.ActivityResultContracts`, provides hooks for testing, and allow receiving results in separate, testable classes independent from your fragment.
`void`	`@MainThread @CallSuper onAttach(@NonNull Activity activity)` This method is deprecated. See `onAttach`.
`void`	`@MainThread @CallSuper onAttach(@NonNull Context context)` Called when a fragment is first attached to its context.
`void`	`@MainThread onAttachFragment(@NonNull Fragment childFragment)` This method is deprecated. The responsibility for listening for fragments being attached has been moved to FragmentManager.
`void`	`@CallSuper onConfigurationChanged(@NonNull Configuration newConfig)`
`boolean`	`@MainThread onContextItemSelected(@NonNull MenuItem item)` This hook is called whenever an item in a context menu is selected.
`@Nullable Animation`	`@MainThread onCreateAnimation(int transit, boolean enter, int nextAnim)` Called when a fragment loads an animation.
`@Nullable Animator`	`@MainThread onCreateAnimator(int transit, boolean enter, int nextAnim)` Called when a fragment loads an animator.
`void`	`@MainThread onCreateContextMenu( @NonNull ContextMenu menu, @NonNull View v, @Nullable ContextMenu.ContextMenuInfo menuInfo )` Called when a context menu for the `view` is about to be shown.
`void`	`@MainThread onCreateOptionsMenu(@NonNull Menu menu, @NonNull MenuInflater inflater)` This method is deprecated. `androidx.activity.ComponentActivity` now implements `MenuHost`, an interface that allows any component, including your activity itself, to add menu items by calling addMenuProvider without forcing all components through this single method override.
`void`	`@MainThread @CallSuper onDestroy()` Called when the fragment is no longer in use.
`void`	`@MainThread onDestroyOptionsMenu()` This method is deprecated. `androidx.activity.ComponentActivity` now implements `MenuHost`, an interface that allows any component, including your activity itself, to add menu items by calling addMenuProvider without forcing all components through this single method override.
`void`	`@MainThread @CallSuper onDetach()` Called when the fragment is no longer attached to its activity.
`@NonNull LayoutInflater`	`onGetLayoutInflater(@Nullable Bundle savedInstanceState)` Returns the LayoutInflater used to inflate Views of this Fragment.
`void`	`@MainThread onHiddenChanged(boolean hidden)` Called when the hidden state (as returned by `isHidden` of the fragment or another fragment in its hierarchy has changed.
`void`	`@UiThread @CallSuper onInflate( @NonNull Activity activity, @NonNull AttributeSet attrs, @Nullable Bundle savedInstanceState )` This method is deprecated. See `onInflate`.
`void`	`@UiThread @CallSuper onInflate( @NonNull Context context, @NonNull AttributeSet attrs, @Nullable Bundle savedInstanceState )` Called when a fragment is being created as part of a view layout inflation, typically from setting the content view of an activity.
`void`	`@MainThread @CallSuper onLowMemory()` This method is deprecated.
`void`	`onMultiWindowModeChanged(boolean isInMultiWindowMode)` Called when the Fragment's activity changes from fullscreen mode to multi-window mode and visa-versa.
`boolean`	`@MainThread onOptionsItemSelected(@NonNull MenuItem item)` This method is deprecated. `androidx.activity.ComponentActivity` now implements `MenuHost`, an interface that allows any component, including your activity itself, to add menu items by calling addMenuProvider without forcing all components through this single method override.
`void`	`@MainThread onOptionsMenuClosed(@NonNull Menu menu)` This method is deprecated. `androidx.activity.ComponentActivity` now implements `MenuHost`, an interface that allows any component, including your activity itself, to add menu items by calling addMenuProvider without forcing all components through this single method override.
`void`	`@MainThread @CallSuper onPause()` Called when the Fragment is no longer resumed.
`void`	`onPictureInPictureModeChanged(boolean isInPictureInPictureMode)` Called by the system when the activity changes to and from picture-in-picture mode.
`void`	`@MainThread onPrepareOptionsMenu(@NonNull Menu menu)` This method is deprecated. `androidx.activity.ComponentActivity` now implements `MenuHost`, an interface that allows any component, including your activity itself, to add menu items by calling addMenuProvider without forcing all components through this single method override.
`void`	`@MainThread onPrimaryNavigationFragmentChanged( boolean isPrimaryNavigationFragment )` Callback for when the primary navigation state of this Fragment has changed.
`void`	`onRequestPermissionsResult( int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults )` This method is deprecated. This method has been deprecated in favor of using the Activity Result API which brings increased type safety via an `ActivityResultContract` and the prebuilt contracts for common intents available in `androidx.activity.result.contract.ActivityResultContracts`, provides hooks for testing, and allow receiving results in separate, testable classes independent from your fragment.
`void`	`@MainThread @CallSuper onResume()` Called when the fragment is visible to the user and actively running.
`void`	`@MainThread @CallSuper onViewStateRestored(@Nullable Bundle savedInstanceState)` Called when all saved state has been restored into the view hierarchy of the fragment.
`void`	`postponeEnterTransition()` Postpone the entering Fragment transition until `startPostponedEnterTransition` or `executePendingTransactions` has been called.
`final void`	`postponeEnterTransition(long duration, @NonNull TimeUnit timeUnit)` Postpone the entering Fragment transition for a given amount of time and then call `startPostponedEnterTransition`.
`final @NonNull ActivityResultLauncher<I>`	`@MainThread <I, O> registerForActivityResult( @NonNull ActivityResultContract<I, O> contract, @NonNull ActivityResultCallback<O> callback )` Register a request to `start an activity for result`, designated by the given `contract`.
`final @NonNull ActivityResultLauncher<I>`	`@MainThread <I, O> registerForActivityResult( @NonNull ActivityResultContract<I, O> contract, @NonNull ActivityResultRegistry registry, @NonNull ActivityResultCallback<O> callback )` Register a request to `start an activity for result`, designated by the given `contract`.
`void`	`registerForContextMenu(@NonNull View view)` Registers a context menu to be shown for the given view (multiple views can show the context menu).
`final void`	`requestPermissions(@NonNull String[] permissions, int requestCode)` This method is deprecated. This method has been deprecated in favor of using the Activity Result API which brings increased type safety via an `ActivityResultContract` and the prebuilt contracts for common intents available in `androidx.activity.result.contract.ActivityResultContracts`, provides hooks for testing, and allow receiving results in separate, testable classes independent from your fragment.
`final @NonNull FragmentActivity`	`requireActivity()` Return the `FragmentActivity` this fragment is currently associated with.
`final @NonNull Bundle`	`requireArguments()` Return the arguments supplied when the fragment was instantiated.
`final @NonNull`

PreferenceFragmentCompat

Sample Code

Summary

Nested types

Constants

Public constructors

Public methods

Protected methods

Inherited methods