public abstract class PreferenceFragment extends Fragment implements PreferenceManager.OnPreferenceTreeClickListener, PreferenceManager.OnDisplayPreferenceDialogListener, PreferenceManager.OnNavigateToScreenListener, DialogPreference.TargetFragment
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:
Activities
that each specify its own
preferences in an XML file via Activity
meta-data
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)
.
For information about using PreferenceFragment
,
read the Settings
guide.
The following sample code shows a simple preference fragment that is populated from a resource. The resource it loads is:
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:
Preference
,
PreferenceScreen
Modifier and Type | Class and Description |
---|---|
static interface |
PreferenceFragment.OnPreferenceDisplayDialogCallback |
static interface |
PreferenceFragment.OnPreferenceStartFragmentCallback
Interface that PreferenceFragment's containing activity should
implement to be able to process preference items that wish to
switch to a specified fragment.
|
static interface |
PreferenceFragment.OnPreferenceStartScreenCallback
Interface that PreferenceFragment's containing activity should
implement to be able to process preference items that wish to
switch to a new screen of preferences.
|
Fragment.InstantiationException, Fragment.SavedState
Modifier and Type | Field and Description |
---|---|
static String |
ARG_PREFERENCE_ROOT
Fragment argument used to specify the tag of the desired root
PreferenceScreen object. |
TRIM_MEMORY_BACKGROUND, TRIM_MEMORY_COMPLETE, TRIM_MEMORY_MODERATE, TRIM_MEMORY_RUNNING_CRITICAL, TRIM_MEMORY_RUNNING_LOW, TRIM_MEMORY_RUNNING_MODERATE, TRIM_MEMORY_UI_HIDDEN
Constructor and Description |
---|
PreferenceFragment() |
Modifier and Type | Method and Description |
---|---|
void |
addPreferencesFromResource(int preferencesResId)
Inflates the given XML resource and adds the preference hierarchy to the current
preference hierarchy.
|
Preference |
findPreference(CharSequence key)
Finds a
Preference based on its key. |
Fragment |
getCallbackFragment()
Basically a wrapper for getParentFragment which is v17+.
|
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 |
onActivityCreated(Bundle savedInstanceState)
Called when the fragment's activity has been created and this
fragment's view hierarchy instantiated.
|
protected void |
onBindPreferences() |
void |
onCreate(Bundle savedInstanceState)
Called to do initial creation of a fragment.
|
protected RecyclerView.Adapter |
onCreateAdapter(PreferenceScreen preferenceScreen)
Creates the root adapter.
|
RecyclerView.LayoutManager |
onCreateLayoutManager()
Called from
onCreateRecyclerView(android.view.LayoutInflater, android.view.ViewGroup, android.os.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
Fragment.onCreateView(android.view.LayoutInflater, android.view.ViewGroup, android.os.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 of 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.
|
protected void |
onUnbindPreferences() |
void |
onViewCreated(View view,
Bundle savedInstanceState)
Called immediately after
Fragment.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 . |
dump, equals, getActivity, getAllowEnterTransitionOverlap, getAllowReturnTransitionOverlap, getArguments, getChildFragmentManager, getContext, getEnterTransition, getExitTransition, getFragmentManager, getHost, getId, getLayoutInflater, getLoaderManager, getParentFragment, getReenterTransition, getResources, getRetainInstance, getReturnTransition, getSharedElementEnterTransition, getSharedElementReturnTransition, getString, getString, getTag, getTargetFragment, getTargetRequestCode, getText, getUserVisibleHint, getView, hashCode, instantiate, instantiate, isAdded, isDetached, isHidden, isInLayout, isRemoving, isResumed, isVisible, onActivityResult, onAttach, onAttach, onAttachFragment, onConfigurationChanged, onContextItemSelected, onCreateAnimator, onCreateContextMenu, onCreateOptionsMenu, onDestroy, onDestroyOptionsMenu, onDetach, onHiddenChanged, onInflate, onInflate, onInflate, onLowMemory, onMultiWindowModeChanged, onOptionsItemSelected, onOptionsMenuClosed, onPause, onPictureInPictureModeChanged, onPrepareOptionsMenu, onRequestPermissionsResult, onResume, onTrimMemory, onViewStateRestored, registerForContextMenu, requestPermissions, setAllowEnterTransitionOverlap, setAllowReturnTransitionOverlap, setArguments, setEnterSharedElementCallback, setEnterSharedElementTransitionCallback, setEnterTransition, setExitSharedElementCallback, setExitSharedElementTransitionCallback, setExitTransition, setHasOptionsMenu, setInitialSavedState, setMenuVisibility, setReenterTransition, setRetainInstance, setReturnTransition, setSharedElementEnterTransition, setSharedElementReturnTransition, setTargetFragment, setUserVisibleHint, shouldShowRequestPermissionRationale, startActivity, startActivity, startActivityForResult, startActivityForResult, startIntentSenderForResult, toString, unregisterForContextMenu
public static final String ARG_PREFERENCE_ROOT
PreferenceScreen
object.public void onCreate(Bundle savedInstanceState)
Fragment
Fragment.onAttach(Activity)
and before
Fragment.onCreateView(LayoutInflater, ViewGroup, Bundle)
, but is not called if the fragment
instance is retained across Activity re-creation (see Fragment.setRetainInstance(boolean)
).
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, see Fragment.onActivityCreated(Bundle)
.
If your app's targetSdkVersion
is Build.VERSION_CODES.M
or lower, child fragments being restored from the savedInstanceState are restored after
onCreate
returns. When targeting Build.VERSION_CODES.N
or
above and running on an N or newer platform version
they are restored by Fragment.onCreate
.
public abstract void onCreatePreferences(Bundle savedInstanceState, String rootKey)
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)
.savedInstanceState
- If the fragment is being re-created from
a previous saved state, this is the state.rootKey
- If non-null, this preference fragment should be rooted at the
PreferenceScreen
with this key.public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)
Fragment
Fragment.onCreate(Bundle)
and Fragment.onActivityCreated(Bundle)
.
If you return a View from here, you will later be called in
Fragment.onDestroyView()
when the view is being released.
onCreateView
in class Fragment
inflater
- The LayoutInflater object that can be used to inflate
any views in the fragment,container
- 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
- If non-null, this fragment is being re-constructed
from a previous saved state as given here.public void setDivider(Drawable divider)
Note: If the drawable does not have an intrinsic
height, you should also call setDividerHeight(int)
.
divider
- the drawable to usepublic void setDividerHeight(int height)
setDivider(Drawable)
height
- The new height of the divider in pixels.public void onViewCreated(View view, Bundle savedInstanceState)
Fragment
Fragment.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.onViewCreated
in class Fragment
view
- The View returned by Fragment.onCreateView(LayoutInflater, ViewGroup, Bundle)
.savedInstanceState
- If non-null, this fragment is being re-constructed
from a previous saved state as given here.public void onActivityCreated(Bundle savedInstanceState)
Fragment
Fragment.setRetainInstance(boolean)
to retain their instance,
as this callback tells the fragment when it is fully associated with
the new activity instance. This is called after Fragment.onCreateView(android.view.LayoutInflater, android.view.ViewGroup, android.os.Bundle)
and before Fragment.onViewStateRestored(Bundle)
.onActivityCreated
in class Fragment
savedInstanceState
- If the fragment is being re-created from
a previous saved state, this is the state.public void onStart()
Fragment
Activity.onStart
of the containing
Activity's lifecycle.public void onStop()
Fragment
Activity.onStop
of the containing
Activity's lifecycle.public void onDestroyView()
Fragment
Fragment.onCreateView(android.view.LayoutInflater, android.view.ViewGroup, android.os.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 Fragment.onStop()
and before Fragment.onDestroy()
. It is called
regardless of whether Fragment.onCreateView(android.view.LayoutInflater, android.view.ViewGroup, android.os.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.onDestroyView
in class Fragment
public void onSaveInstanceState(Bundle outState)
Fragment
Fragment.onCreate(Bundle)
,
Fragment.onCreateView(LayoutInflater, ViewGroup, Bundle)
, and
Fragment.onActivityCreated(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 Fragment.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.
onSaveInstanceState
in class Fragment
outState
- Bundle in which to place your saved state.public PreferenceManager getPreferenceManager()
PreferenceManager
used by this fragment.PreferenceManager
.public void setPreferenceScreen(PreferenceScreen preferenceScreen)
preferenceScreen
- The root PreferenceScreen
of the preference hierarchy.public PreferenceScreen getPreferenceScreen()
PreferenceScreen
that is the root of the preference
hierarchy.public void addPreferencesFromResource(@XmlRes int preferencesResId)
preferencesResId
- The XML resource ID to inflate.public void setPreferencesFromResource(@XmlRes int preferencesResId, @Nullable String key)
key
.preferencesResId
- The XML resource ID to inflate.key
- The preference key of the PreferenceScreen
to use as the root of the preference hierarchy, or null to use the root
PreferenceScreen
.public boolean onPreferenceTreeClick(Preference preference)
PreferenceScreen
has been clicked.onPreferenceTreeClick
in interface PreferenceManager.OnPreferenceTreeClickListener
preference
- The preference that was clicked.public void onNavigateToScreen(PreferenceScreen preferenceScreen)
PreferenceScreen.onClick()
in order to navigate to a
new screen of preferences. Calls
PreferenceFragment.OnPreferenceStartScreenCallback.onPreferenceStartScreen(android.support.v14.preference.PreferenceFragment, android.support.v7.preference.PreferenceScreen)
if the target fragment or containing activity implements
PreferenceFragment.OnPreferenceStartScreenCallback
.onNavigateToScreen
in interface PreferenceManager.OnNavigateToScreenListener
preferenceScreen
- The PreferenceScreen
to
navigate to.public Preference findPreference(CharSequence key)
Preference
based on its key.findPreference
in interface DialogPreference.TargetFragment
key
- The key of the preference to retrieve.Preference
with the key, or null.PreferenceGroup.findPreference(CharSequence)
protected void onBindPreferences()
protected void onUnbindPreferences()
public final RecyclerView getListView()
public RecyclerView onCreateRecyclerView(LayoutInflater inflater, ViewGroup parent, Bundle savedInstanceState)
RecyclerView
used to display the preferences.
Subclasses may override this to return a customized
RecyclerView
.inflater
- The LayoutInflater object that can be used to inflate the
RecyclerView
.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 LayoutParams of the view.savedInstanceState
- If non-null, this view is being re-constructed from a previous
saved state as given herepublic RecyclerView.LayoutManager onCreateLayoutManager()
onCreateRecyclerView(android.view.LayoutInflater, android.view.ViewGroup, android.os.Bundle)
to create the
RecyclerView.LayoutManager
for the created
RecyclerView
.RecyclerView.LayoutManager
instance.protected RecyclerView.Adapter onCreateAdapter(PreferenceScreen preferenceScreen)
preferenceScreen
- Preference screen object to create the adapter for.PreferenceScreen
.public void onDisplayPreferenceDialog(Preference preference)
onDisplayPreferenceDialog
in interface PreferenceManager.OnDisplayPreferenceDialogListener
preference
- The Preference object requesting the dialog.public Fragment getCallbackFragment()
public void scrollToPreference(String key)
public void scrollToPreference(Preference preference)