Customize your settings Part of Android Jetpack.
This document describes how to customize
Preference
objects in your hierarchy.
Find preferences
To access an individual Preference
, such as when getting or setting a
Preference
value, use
PreferenceFragmentCompat.findPreference()
.
This method searches the entire hierarchy for a Preference
with the given key.
For example, to access an
EditTextPreference
with a
key of "signature"
, do the following:
<EditTextPreference app:key="signature" app:title="Your signature"/>
Retrieve this Preference
by using the following code:
Kotlin
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) val signaturePreference: EditTextPreference? = findPreference("signature") // Do something with this preference. }
Java
@Override public void onCreatePreferences(Bundle savedInstanceState, String rootKey) { setPreferencesFromResource(R.xml.preferences, rootKey); EditTextPreference signaturePreference = findPreference("signature"); // Do something with this preference. }
Control Preference visibility
You can control which Preference
objects are visible to the user when they
navigate to a settings screen. For example, if a particular Preference
is
meaningful only when a corresponding feature is enabled, you might want to hide
that Preference
when the feature is disabled.
To show a Preference
only when a condition is met, first set the Preference
visibility to false in the XML, as shown in the following example:
<EditTextPreference app:key="signature" app:title="Your signature" app:isPreferenceVisible="false"/>
In onCreatePreferences()
, show the Preference
when the corresponding
condition is met:
Kotlin
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) if(/*some feature*/) { val signaturePreference: EditTextPreference? = findPreference("signature") signaturePreference?.isVisible = true } }
Java
@Override public void onCreatePreferences(Bundle savedInstanceState, String rootKey) { setPreferencesFromResource(R.xml.preferences, rootKey); if(/*some feature*/) { EditTextPreference signaturePreference = findPreference("signature"); if (signaturePreference != null) { signaturePreference.setVisible(true); } } }
Dynamically update summaries
A Preference
that persists data must display the current value in its
summary to help the user better understand the current state of the
Preference
. For example, an EditTextPreference
must show the saved text
value, and a ListPreference
must show the selected list entry. You might also
have Preference
objects that need to update their summary based on internal or
external app state—for example, a Preference
that displays a version
number. You can do this by using a
SummaryProvider
.
Use a SimpleSummaryProvider
ListPreference
and
EditTextPreference
include simple SummaryProvider
implementations that automatically display the
saved Preference
value as the summary. If no value is saved, they display "Not
set."
To enable these implementations from XML, set
app:useSimpleSummaryProvider="true"
.
Alternatively, in code you can use
ListPreference.SimpleSummaryProvider.getInstance()
and
EditTextPreference.SimpleSummaryProvider.getInstance()
to get the simple SummaryProvider
instance and then set it on the
Preference
, as shown in the following example:
Kotlin
listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance() editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()
Java
listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance()); editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());
Use a custom SummaryProvider
You can create your own SummaryProvider
and override
provideSummary()
to customize the summary whenever it is requested by the Preference
. For
example, the following EditTextPreference
displays the length of its saved
value as the summary:
As an example, assume the following EditTextPreference
:
<EditTextPreference app:key="counting" app:title="Counting preference"/>
In onCreatePreferences()
, you can create a new SummaryProvider
and override
provideSummary()
to return the summary to be displayed:
Kotlin
val countingPreference: EditTextPreference? = findPreference("counting") countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference -> val text = preference.text if (text.isNullOrEmpty()) { "Not set" } else { "Length of saved value: " + text.length } }
Java
EditTextPreference countingPreference = findPreference("counting"); if (countingPreference != null) { countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() { @Override public CharSequence provideSummary(EditTextPreference preference) { String text = preference.getText(); if (TextUtils.isEmpty(text) || text == null){ return "Not set"; } return "Length of saved value: " + text.length(); } }); }
The Preference
summary displays the length of the saved value or "Not set"
when no saved value exists.
Customize an EditTextPreference dialog
Within an EditTextPreference
dialog, you can customize text field behavior by
attaching an
OnBindEditTextListener
.
This listener is invoked when the dialog is shown to the user.
As an example, you can customize a dialog to accept only numbers. First, create
the EditTextPreference
:
<EditTextPreference app:key="number" app:title="Numbers only preference"/>
Next, in onCreatePreferences()
, create a new OnBindEditTextListener
and
override onBindEditText()
to customize the EditText
when it is shown to the
user.
Kotlin
val numberPreference: EditTextPreference? = findPreference("number") numberPreference?.setOnBindEditTextListener { editText -> editText.inputType = InputType.TYPE_CLASS_NUMBER }
Java
EditTextPreference numberPreference = findPreference("number"); if (numberPreference != null) { numberPreference.setOnBindEditTextListener( new EditTextPreference.OnBindEditTextListener() { @Override public void onBindEditText(@NonNull EditText editText) { editText.setInputType(InputType.TYPE_CLASS_NUMBER); } }); }
Now, when the dialog is shown to the user, the keyboard opens in numeric-only
mode, so the user can enter only numbers into the EditText
.
Preference actions
A Preference
can have a specific action when tapped. For example, a
Preference
can act as a link to a separate part of your app. To add an action
to a Preference
, you can set an Intent
on the Preference
directly or you
can set an
OnPreferenceClickListener
for more specific logic.
Set an Intent
You can set an Intent
on a Preference
to launch a new Fragment
,
Activity
, or separate app whenever the Preference
is tapped. This is the
same as using
Context.startActivity()
with a given Intent
.
You can set an Intent
in XML using a nested <intent>
tag. The following
example defines an Intent
that launches an Activity
:
<Preference app:key="activity" app:title="Launch activity"> <intent android:targetPackage="com.example" android:targetClass="com.example.ExampleActivity"/> </Preference>
Alternatively, you can use setIntent()
directly on a Preference
, as follows:
Kotlin
val intent = Intent(context, ExampleActivity::class.java) activityPreference.setIntent(intent)
Java
Intent intent = new Intent(getContext(), ExampleActivity.class); activityPreference.setIntent(intent);
You can also include extras with an Intent
using XML:
<Preference app:key="activity" app:title="Launch activity"> <intent android:targetPackage="com.example" android:targetClass="com.example.ExampleActivity"> <extra android:name="example_key" android:value="example_value"/> </intent> </Preference>
Here is an example of a Preference
with an Intent
that launches a web page:
<Preference app:key="webpage" app:title="View webpage"> <intent android:action="android.intent.action.VIEW" android:data="http://www.google.com" /> </Preference>
Kotlin
val intent = Intent(Intent.ACTION_VIEW) intent.data = Uri.parse("http://www.google.com") val webpagePreference = findPreference("webpage") webpagePreference?.intent = intent
Java
Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(Uri.parse("http://www.google.com")); webpagePreference.setIntent(intent);
OnPreferenceClickListener
You can set an OnPreferenceClickListener
on a Preference
, which adds a
callback to onPreferenceClick()
when the Preference
is tapped. For example,
you can use the listener to navigate to another Fragment
or Activity
if you
have more complex logic for handling navigation.
To set an OnPreferenceClickListener
, use code similar to the following:
Kotlin
onClickPreference.setOnPreferenceClickListener({ // Do something. true })
Java
onClickPreference.setOnPreferenceClickListener(preference -> { // Do something. return true; });