PreferenceFragment

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

java.lang.Object
   ↳ android.app.Fragment
     ↳ androidx.preference.PreferenceFragment


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.

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

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

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

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