PreferenceFragment

Added in 1.0.0
Deprecated in 1.1.0

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

Known indirect subclasses

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:

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.

Summary

Nested types

Interface that the fragment's containing activity should implement to be able to process preference items that wish to display a dialog.

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 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

Public constructors

Public methods

void
addPreferencesFromResource(@XmlRes int preferencesResId)

This method is deprecated.

Use PreferenceFragmentCompat instead

T

This method is deprecated.

Use PreferenceFragmentCompat instead

final RecyclerView

This method is deprecated.

Use PreferenceFragmentCompat instead

PreferenceManager

This method is deprecated.

Use PreferenceFragmentCompat instead

PreferenceScreen

This method is deprecated.

Use PreferenceFragmentCompat instead

void
onCreate(@Nullable Bundle savedInstanceState)

This method is deprecated.

@NonNull RecyclerView.LayoutManager

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

This method is deprecated.

void

This method is deprecated.

Use PreferenceFragmentCompat instead

void

This method is deprecated.

Use PreferenceFragmentCompat instead

boolean

This method is deprecated.

Use PreferenceFragmentCompat instead

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

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

This method is deprecated.

void

This method is deprecated.

Use PreferenceFragmentCompat instead

void

This method is deprecated.

Use PreferenceFragmentCompat instead

void

This method is deprecated.

Use PreferenceFragmentCompat instead

void
setDividerHeight(int height)

This method is deprecated.

Use PreferenceFragmentCompat instead

void

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

This method is deprecated.

Use PreferenceFragmentCompat instead

Inherited Constants

From android.content.ComponentCallbacks2
static final int
static final int
static final int
static final int
static final int
static final int
static final int

Inherited methods

From android.app.Fragment
void
dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)

This method is deprecated.

final boolean

This method is deprecated.

final Activity

This method is deprecated.

boolean

This method is deprecated.

boolean

This method is deprecated.

final Bundle

This method is deprecated.

final FragmentManager

This method is deprecated.

Context

This method is deprecated.

Transition

This method is deprecated.

Transition

This method is deprecated.

final FragmentManager

This method is deprecated.

final Object

This method is deprecated.

final int

This method is deprecated.

final LayoutInflater

This method is deprecated.

LoaderManager

This method is deprecated.

final Fragment

This method is deprecated.

Transition

This method is deprecated.

final Resources

This method is deprecated.

final boolean

This method is deprecated.

Transition

This method is deprecated.

Transition

This method is deprecated.

Transition

This method is deprecated.

final String
getString(int resId)

This method is deprecated.

final String

This method is deprecated.

final Fragment

This method is deprecated.

final int

This method is deprecated.

final CharSequence
getText(int resId)

This method is deprecated.

boolean

This method is deprecated.

View

This method is deprecated.

final int

This method is deprecated.

static Fragment
instantiate(Context context, String fname)

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

This method is deprecated.

final boolean

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

This method is deprecated.

boolean

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

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

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

This method is deprecated.

void
onMultiWindowModeChanged(
    boolean isInMultiWindowMode,
    Configuration newConfig
)

This method is deprecated.

boolean

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void
onPictureInPictureModeChanged(
    boolean isInPictureInPictureMode,
    Configuration newConfig
)

This method is deprecated.

void

This method is deprecated.

void
onRequestPermissionsResult(
    int requestCode,
    String[] permissions,
    int[] grantResults
)

This method is deprecated.

void

This method is deprecated.

void
onTrimMemory(int level)

This method is deprecated.

void
onViewStateRestored(Bundle savedInstanceState)

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

final void
requestPermissions(String[] permissions, int requestCode)

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void
setHasOptionsMenu(boolean hasMenu)

This method is deprecated.

void

This method is deprecated.

void
setMenuVisibility(boolean menuVisible)

This method is deprecated.

void

This method is deprecated.

void
setRetainInstance(boolean retain)

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void

This method is deprecated.

void
setTargetFragment(Fragment fragment, int requestCode)

This method is deprecated.

void
setUserVisibleHint(boolean isVisibleToUser)

This method is deprecated.

boolean

This method is deprecated.

void

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

This method is deprecated.

String

This method is deprecated.

void

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.

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