added in version 24.1.0
belongs to Maven artifact com.android.support:preference-v7:28.0.0-alpha1

PreferenceFragmentCompat

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

java.lang.Object
   ↳ android.support.v4.app.Fragment
     ↳ android.support.v7.preference.PreferenceFragmentCompat


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 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 using PreferenceFragment, read the Settings guide.

    Sample Code

    The following sample code shows a simple preference fragment that is populated from a resource. The resource it loads is:

    <PreferenceScreen
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:title="@string/root_title">
    
        <Preference
            android:key="basic_preference"
            android:title="@string/title_basic_preference"
            android:summary="@string/summary_basic_preference" />
    
        <Preference
            android:key="stylish_preference"
            android:title="@string/title_stylish_preference"
            android:summary="@string/summary_stylish_preference" />
    
        <Preference
            android:key="preference_with_icon"
            android:title="Preference with icon"
            android:summary="This preference has an icon"
            android:icon="@android:drawable/ic_menu_camera" />
    
        <PreferenceCategory
            android:title="@string/inline_preferences">
    
            <CheckBoxPreference
                android:key="checkbox_preference"
                android:title="@string/title_checkbox_preference"
                android:summary="@string/summary_checkbox_preference" />
    
            <SwitchPreference
                android:key="switch_preference"
                android:title="Switch preference"
                android:summary="This is a switch" />
    
            <DropDownPreference
                android:key="dropdown_preference"
                android:title="@string/title_dropdown_preference"
                android:summary="@string/summary_dropdown_preference"
                android:entries="@array/entries_list_preference"
                android:entryValues="@array/entryvalues_list_preference" />
    
        </PreferenceCategory>
    
        <PreferenceCategory
            android:title="@string/dialog_based_preferences">
    
            <EditTextPreference
                android:key="edittext_preference"
                android:title="@string/title_edittext_preference"
                android:summary="@string/summary_edittext_preference"
                android:dialogTitle="@string/dialog_title_edittext_preference" />
    
            <ListPreference
                android:key="list_preference"
                android:title="@string/title_list_preference"
                android:summary="@string/summary_list_preference"
                android:entries="@array/entries_list_preference"
                android:entryValues="@array/entryvalues_list_preference"
                android:dialogTitle="@string/dialog_title_list_preference" />
    
            <MultiSelectListPreference
                android:key="multi_select_list_preference"
                android:title="@string/title_multi_list_preference"
                android:summary="@string/summary_multi_list_preference"
                android:entries="@array/entries_list_preference"
                android:entryValues="@array/entryvalues_list_preference"
                android:dialogTitle="@string/dialog_title_multi_list_preference" />
    
        </PreferenceCategory>
    
        <PreferenceCategory
            android:title="@string/launch_preferences">
    
            <!-- This PreferenceScreen tag serves as a screen break (similar to page break
                 in word processing). Like for other preference types, we assign a key
                 here so it is able to save and restore its instance state. -->
            <PreferenceScreen
                android:key="screen_preference"
                android:title="@string/title_screen_preference"
                android:summary="@string/summary_screen_preference">
    
                <!-- You can place more preferences here that will be shown on the next screen. -->
    
                <CheckBoxPreference
                    android:key="next_screen_checkbox_preference"
                    android:title="@string/title_next_screen_toggle_preference"
                    android:summary="@string/summary_next_screen_toggle_preference" />
    
            </PreferenceScreen>
    
            <PreferenceScreen
                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" />
    
            </PreferenceScreen>
    
        </PreferenceCategory>
    
        <PreferenceCategory
            android:title="@string/preference_attributes">
    
            <CheckBoxPreference
                android:key="parent_checkbox_preference"
                android:title="@string/title_parent_preference"
                android:summary="@string/summary_parent_preference" />
    
            <!-- The visual style of a child is defined by this styled theme attribute. -->
            <CheckBoxPreference
                android:key="child_checkbox_preference"
                android:dependency="parent_checkbox_preference"
                android:layout="?android:attr/preferenceLayoutChild"
                android:title="@string/title_child_preference"
                android:summary="@string/summary_child_preference" />
    
        </PreferenceCategory>
    
    </PreferenceScreen>

    The fragment implementation itself simply populates the preferences when created. Note that the preferences framework takes care of loading the current values out of the app preferences and writing them when changed:

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

    Summary

    Nested classes

    interface PreferenceFragmentCompat.OnPreferenceDisplayDialogCallback

     

    interface PreferenceFragmentCompat.OnPreferenceStartFragmentCallback

    Interface that PreferenceFragment's containing activity should implement to be able to process preference items that wish to switch to a specified fragment. 

    interface