Types of Preferences

The elements in the preference XML will refer to subclasses of androidx.preference.Preference. There are several of these in the current AndroidX Preference library, and most may be added in the future. You can also create your own, such as by extending DialogPreference and calling various methods to build up the content of the dialog (e.g., setDialogTitle(), setDialogLayoutResource()).

CheckBoxPreference and SwitchPreference

The sample application shown above a CheckBoxPreference. As noted, a CheckBoxPreference is an “inline” preference, in that the widget the user interacts with (in this case, a CheckBox) is part of the preference screen itself, rather than contained in a separate dialog.

SwitchPreference is functionally equivalent to CheckBoxPreference, insofar as both collect boolean values from the user. The difference is that SwitchPreference uses a Switch widget that the user slides left and right to toggle between “on” and “off” states.

The value that will be stored in the SharedPreferences is a boolean — we will explore how to read and manipulate these values from your own code later in this chapter.

EditTextPreference

EditTextPreference, when tapped by the user, pops up a dialog that contains an EditText widget. You can configure this widget via attributes on the <EditTextPreference> element — in addition to standard preference attributes like android:key, you can include any attribute understood by EditText, such as android:inputType. Also, as the sample app shows, you can have android:dialogTitle to provide the title for the dialog that wraps the EditText widget.

The value stored in the SharedPreferences is a string.

ListPreference and MultiSelectListPreference

A ListPreference displays a dialog with your choice of entries. Each is accompanied by a RadioButton, with the checked RadioButton indicating the current value (if any). A MultiSelectListPreference has the same look, except it has checkboxes for each entry, and the user can choose multiple values, not just one.

To configure what appears in the list, you provide two attributes in the ListPreference or MultiSelectListPreference element:

• android:entries provides what the user sees
• android:entryValues provides the corresponding values that are saved in the SharedPreferences

In the preference XML, these attributes need to point to string-array resources. String resources hold individual strings; string array resources hold a collection of strings. Typically, you will find string array resources in res/values/arrays.xml and related resource sets for translation. The <string-array> element has the name attribute to identify the resource, along with child <item> elements for the individual strings in the array.

So, our sample app has a pair of <string-array> resources in res/values/arrays.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string-array name="cities">
    <item>Philadelphia</item>
    <item>Pittsburgh</item>
    <item>Allentown/Bethlehem</item>
    <item>Erie</item>
    <item>Reading</item>
    <item>Scranton</item>
    <item>Lancaster</item>
    <item>Altoona</item>
    <item>Harrisburg</item>
  </string-array>
  <string-array name="airportCodes">
    <item>PHL</item>
    <item>PIT</item>
    <item>ABE</item>
    <item>ERI</item>
    <item>RDG</item>
    <item>AVP</item>
    <item>LNS</item>
    <item>AOO</item>
    <item>MDT</item>
  </string-array>
</resources>

Here, the actual strings are written in-line. They could just as easily be references to string resource. For user-facing strings, like those in the cities array, having them as string resources may make it easier for you to manage your translations.

The sample app then uses those arrays in a ListPreference:

  <ListPreference
    android:dialogTitle="@string/listDialogTitle"
    android:entries="@array/cities"
    android:entryValues="@array/airportCodes"
    android:key="list"
    android:summary="@string/listSummary"
    android:title="@string/listTitle"/>

The dialog will show the strings in the android:entries array. The value that matches, position-wise, from the android:entryValues array is what gets saved in the SharedPreferences. So, if the user chooses Pittsburgh as the city, PIT will be the value saved in the SharedPreferences. If you want the user-visible strings to be the same as what goes into the SharedPreferences, just use the same string-array resource for both android:entries and android:entryValues.

A ListPreference saves a string to SharedPreferences. A MultiSelectListPreference saves a Set of strings to the SharedPreferences.

There is also DropDownPreference, which works like a ListPreference but uses a drop-down list presentation, rather than a pop-up dialog.

SeekBarPreference

A SeekBarPreference shows a SeekBar widget, to allow the user to specify a value in a range. It saves its value as an int to the SharedPreferences.