PreferenceFragmentCompat

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 SharedPreferences that the preference hierarchy in this fragment will use by default, call PreferenceManager.getDefaultSharedPreferences(android.content.Context) with a context in the same package as this fragment.

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

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

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

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

Developer Guides

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

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 classes
`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.
`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.
`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
`String`	`ARG_PREFERENCE_ROOT` Fragment argument used to specify the tag of the desired root `PreferenceScreen` object.

Public constructors
`PreferenceFragmentCompat()`

Public methods
`void`	`addPreferencesFromResource(int preferencesResId)` Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.
`<T extends Preference> T`	`findPreference(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(Bundle savedInstanceState)` Called to do initial creation of a fragment.
`RecyclerView.LayoutManager`	`onCreateLayoutManager()` Called from `onCreateRecyclerView(LayoutInflater, ViewGroup, Bundle)` to create the `RecyclerView.LayoutManager` for the created `RecyclerView`.
`abstract void`	`onCreatePreferences(Bundle savedInstanceState, String rootKey)` Called during `onCreate(Bundle)` to supply the preferences for this fragment.
`RecyclerView`	`onCreateRecyclerView(LayoutInflater inflater, ViewGroup parent, Bundle savedInstanceState)` Creates the `RecyclerView` used to display the preferences.
`View`	`onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)` Called to have the fragment instantiate its user interface view.
`void`	`onDestroyView()` Called when the view previously created by `onCreateView(LayoutInflater, ViewGroup, Bundle)` has been detached from the fragment.
`void`	`onDisplayPreferenceDialog(Preference preference)` Called when a preference in the tree requests to display a dialog.
`void`	`onNavigateToScreen(PreferenceScreen preferenceScreen)` Called by `PreferenceScreen.onClick()` in order to navigate to a new screen of preferences.
`boolean`	`onPreferenceTreeClick(Preference preference)` Called when a preference in the tree rooted at this `PreferenceScreen` has been clicked.
`void`	`onSaveInstanceState(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(View view, Bundle savedInstanceState)` Called immediately after `onCreateView(LayoutInflater, ViewGroup, Bundle)` has returned, but before any saved state has been restored in to the view.
`void`	`scrollToPreference(Preference preference)`
`void`	`scrollToPreference(String key)`
`void`	`setDivider(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(int preferencesResId, String key)` Inflates the given XML resource and replaces the current preference hierarchy (if any) with the preference hierarchy rooted at `key`.

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

Inherited methods

From class


        
          androidx.fragment.app.Fragment

`void`	`dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)` Print the Fragments's state into the given stream.
`final boolean`	`equals(Object o)` Subclasses can not override equals().
`final 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 Bundle`	`getArguments()` Return the arguments supplied when the fragment was instantiated, if any.
`final FragmentManager`	`getChildFragmentManager()` Return a private FragmentManager for placing and managing Fragments inside of this Fragment.
`Context`	`getContext()` Return the `Context` this fragment is currently associated with.
`ViewModelProvider.Factory`	`getDefaultViewModelProviderFactory()` Returns the default `ViewModelProvider.Factory` that should be used when no custom `Factory` is provided to the `ViewModelProvider` constructors. The `Fragment's arguments` when this is first called will be used as the defaults to any `SavedStateHandle` passed to a view model created using this factory.
`Object`	`getEnterTransition()` Returns the Transition that will be used to move Views into the initial scene.
`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 FragmentManager`	`getFragmentManager()` This method is deprecated. This has been removed in favor of `getParentFragmentManager()` which throws an `IllegalStateException` if the FragmentManager is null. Check if `isAdded()` returns `false` to determine if the FragmentManager is `null`.
`final Object`	`getHost()` Return the host object of this fragment.
`final int`	`getId()` Return the identifier this fragment is known by.
`final LayoutInflater`	`getLayoutInflater()` Returns the cached LayoutInflater used to inflate Views of this Fragment.
`Lifecycle`	`getLifecycle()` Returns the Lifecycle of the provider. Overriding this method is no longer supported and this method will be made `final` in a future version of Fragment.
`LoaderManager`	`getLoaderManager()` This method is deprecated. Use `LoaderManager.getInstance(this)`.
`final Fragment`	`getParentFragment()` Returns the parent Fragment containing this Fragment.
`final FragmentManager`	`getParentFragmentManager()` Return the FragmentManager for interacting with fragments associated with this fragment's activity.
`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 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. The ViewModel's constructor and its onCleared() callback provide the signal for initial creation and final destruction of the retained state.
`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 SavedStateRegistry`	`getSavedStateRegistry()` Returns owned `SavedStateRegistry`
`Object`	`getSharedElementEnterTransition()` Returns the Transition that will be used for shared elements transferred into the content Scene.
`Object`	`getSharedElementReturnTransition()` Return the Transition that will be used for shared elements transferred back during a pop of the back stack.
`final String`	`getString(int resId, Object... formatArgs)` Return a localized formatted string from the application's package's default string table, substituting the format arguments as defined in `Formatter` and `String.format(String, Object...)`.
`final String`	`getString(int resId)` Return a localized string from the application's package's default string table.
`final String`	`getTag()` Get the tag name of the fragment, if specified.
`final Fragment`	`getTargetFragment()` This method is deprecated. Instead of using a target fragment to pass results, use `FragmentManager.setFragmentResult(String, Bundle)` to deliver results to `FragmentResultListener` instances registered by other fragments via `FragmentManager.setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)`.
`final int`	`getTargetRequestCode()` This method is deprecated. When using the target fragment replacement of `FragmentManager.setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)` and `FragmentManager.setFragmentResult(String, Bundle)`, consider using `setArguments(Bundle)` to pass a `requestKey` if you need to support dynamic request keys.
`final CharSequence`

PreferenceFragmentCompat

Developer Guides

Sample Code

Summary

Nested classes

Constants

Public constructors

Public methods

Protected methods

Inherited methods