PreferenceFragmentCompat
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 |
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 Preference
s 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:
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 |
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 |
final
RecyclerView
|
getListView()
|
PreferenceManager
|
getPreferenceManager()
Returns the |
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 |
abstract
void
|
onCreatePreferences(Bundle savedInstanceState, String rootKey)
Called during |
RecyclerView
|
onCreateRecyclerView(LayoutInflater inflater, ViewGroup parent, Bundle savedInstanceState)
Creates the |
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 |
void
|
onDisplayPreferenceDialog(Preference preference)
Called when a preference in the tree requests to display a dialog. |
void
|
onNavigateToScreen(PreferenceScreen preferenceScreen)
Called by |
boolean
|
onPreferenceTreeClick(Preference preference)
Called when a preference in the tree rooted at this |
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 |
void
|
scrollToPreference(Preference preference)
|
void
|
scrollToPreference(String key)
|
void
|
setDivider(Drawable divider)
Sets the |
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 |
Protected methods | |
---|---|
Adapter
|
onCreateAdapter(PreferenceScreen preferenceScreen)
Creates the root adapter. |
Inherited methods | |
---|---|
Constants
ARG_PREFERENCE_ROOT
public static final String ARG_PREFERENCE_ROOT
Fragment argument used to specify the tag of the desired root PreferenceScreen
object.
Constant Value: "androidx.preference.PreferenceFragmentCompat.PREFERENCE_ROOT"
Public constructors
PreferenceFragmentCompat
public PreferenceFragmentCompat ()
Public methods
addPreferencesFromResource
public void addPreferencesFromResource (int preferencesResId)
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)
Finds a Preference
with the given key. Returns null
if no
Preference
could be found with the given key.
Parameters | |
---|---|
key |
CharSequence : The key of the Preference to retrieve |
Returns | |
---|---|
T |
The Preference with the key, or null |
getPreferenceManager
public PreferenceManager getPreferenceManager ()
Returns the PreferenceManager
used by this fragment.
Returns | |
---|---|
PreferenceManager |
The PreferenceManager used by this fragment
|
getPreferenceScreen
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
public void onCreate (Bundle savedInstanceState)
Called to do initial creation of a fragment. This is called after
onAttach(Activity)
and before
onCreateView(LayoutInflater, ViewGroup, Bundle)
.
Note that this can be called while the fragment's activity is
still in the process of being created. As such, you can not rely
on things like the activity's content view hierarchy being initialized
at this point. If you want to do work once the activity itself is
created, add a LifecycleObserver
on the
activity's Lifecycle, removing it when it receives the
Lifecycle.State.CREATED
callback.
Any restored child fragments will be created before the base
Fragment.onCreate
method returns.
Parameters | |
---|---|
savedInstanceState |
Bundle : If the fragment is being re-created from
a previous saved state, this is the state.
|
onCreateLayoutManager
public RecyclerView.LayoutManager onCreateLayoutManager ()
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)
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)
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 ViewGroup 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)
Called to have the fragment instantiate its user interface view.
This is optional, and non-graphical fragments can return null. This will be called between
onCreate(Bundle)
and onViewCreated(View, Bundle)
.
A default View can be returned by calling Fragment(int)
in your
constructor. Otherwise, this method returns null.
It is recommended to only inflate the layout in this method and move
logic that operates on the returned View to onViewCreated(View, Bundle)
.
If you return a View from here, you will later be called in
onDestroyView()
when the view is being released.
Parameters | |
---|---|
inflater |
LayoutInflater : The LayoutInflater object that can be used to inflate
any views in the fragment, |
container |
ViewGroup : If non-null, this is the parent view that the fragment's
UI should be attached to. The fragment should not add the view itself,
but this can be used to generate the LayoutParams of the view. |
savedInstanceState |
Bundle : If non-null, this fragment is being re-constructed
from a previous saved state as given here. |
Returns | |
---|---|
View |
Return the View for the fragment's UI, or null. |
onDestroyView
public void onDestroyView ()
Called when the view previously created by onCreateView(LayoutInflater, ViewGroup, Bundle)
has
been detached from the fragment. The next time the fragment needs
to be displayed, a new view will be created. This is called
after onStop()
and before onDestroy()
. It is called
regardless of whether onCreateView(LayoutInflater, ViewGroup, Bundle)
returned a
non-null view. Internally it is called after the view's state has
been saved but before it has been removed from its parent.
onDisplayPreferenceDialog
public void onDisplayPreferenceDialog (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 | |
---|---|
preference |
Preference : The Preference object requesting the dialog
|
onNavigateToScreen
public void onNavigateToScreen (PreferenceScreen preferenceScreen)
Called by PreferenceScreen.onClick()
in order to navigate to a new screen of
preferences. Calls
PreferenceFragmentCompat.OnPreferenceStartScreenCallback.onPreferenceStartScreen(PreferenceFragmentCompat, PreferenceScreen)
if the target fragment or containing activity implements
PreferenceFragmentCompat.OnPreferenceStartScreenCallback
.
Parameters | |
---|---|
preferenceScreen |
PreferenceScreen : The PreferenceScreen to navigate to
|
onPreferenceTreeClick
public boolean onPreferenceTreeClick (Preference preference)
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)
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. If a new instance of the fragment later needs to be
created, the data you place in the Bundle here will be available
in the Bundle given to onCreate(Bundle)
,
onCreateView(LayoutInflater, ViewGroup, Bundle)
, and
onViewCreated(View, Bundle)
.
This corresponds to Activity.onSaveInstanceState(Bundle)
and most of the discussion there
applies here as well. Note however: this method may be called
at any time before onDestroy()
. There are many situations
where a fragment may be mostly torn down (such as when placed on the
back stack with no UI showing), but its state will not be saved until
its owning activity actually needs to save its state.
Parameters | |
---|---|
outState |
Bundle : Bundle in which to place your saved state.
|
onStart
public void onStart ()
Called when the Fragment is visible to the user. This is generally
tied to Activity.onStart
of the containing
Activity's lifecycle.
onStop
public void onStop ()
Called when the Fragment is no longer started. This is generally
tied to Activity.onStop
of the containing
Activity's lifecycle.
onViewCreated
public 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.
This gives subclasses a chance to initialize themselves once
they know their view hierarchy has been completely created. The fragment's
view hierarchy is not however attached to its parent at this point.
Parameters | |
---|---|
view |
View : The View returned by onCreateView(LayoutInflater, ViewGroup, Bundle) . |
savedInstanceState |
Bundle : If non-null, this fragment is being re-constructed
from a previous saved state as given here.
|
scrollToPreference
public void scrollToPreference (Preference preference)
Parameters | |
---|---|
preference |
Preference |
scrollToPreference
public void scrollToPreference (String key)
Parameters | |
---|---|
key |
String |
setDivider
public void setDivider (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(int)
.
Parameters | |
---|---|
divider |
Drawable : The drawable to use
R.attr.divider
|
setDividerHeight
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(Drawable)
.
Parameters | |
---|---|
height |
int : The new height of the divider in pixels
R.attr.dividerHeight
|
setPreferenceScreen
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
public 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
.
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)
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
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.