Introduction to Android Application Development, Fourth Edition (2014)

Implementing a PreferenceActivity-based solution requires the following steps:

1. Define the preference set in a preference resource file.

2. Implement a PreferenceFragment class and tie it to the preference resource file. Note that PreferenceFragment will work only on Android 3.0 and above. In the interest of backward compatibility, a PreferenceActivity without the PreferenceFragment can be used to support legacy platform versions as needed.

3. Implement a PreferenceActivity class and add the PreferenceFragment you just created.

4. Hook up the Activity within your application as you normally would. For example, register it in the manifest file, start the Activity as normal, and so on.

Now let’s look at these steps in more detail.

Creating a Preference Resource File

First, you create an XML resource file to define the preferences your users are allowed to edit. A preference resource file contains a root-level <PreferenceScreen> tag, followed by various preference types. These preference types are based on the Preference class (android.preference.Preference) and its subclasses, such as CheckBoxPreference, EditTextPreference, ListPreference, MultiSelectListPreference, and more. Some preferences have been around since the Android SDK was first released, whereas others, such as theMultiSelectListPreference class, were introduced in Android API Level 11 and are not backward compatible with older devices.

Each preference should have some metadata, such as a title and some summary text that will be displayed to the user. You can also specify default values and, for those preferences that launch dialogs, the dialog prompt. For the specific metadata associated with a given preference type, see its subclass attributes in the Android SDK documentation. Here are some common Preference attributes that most preferences should set:

The android:key attribute is used to specify the key name for the shared preference.

The android:title attribute is used to specify the friendly name of the preference, as shown on the editing screen.

The android:summary attribute is used to give more details about the preference, as shown on the editing screen.

The android:defaultValue attribute is used to specify a default value of the preference.

Like any resource files, preference resource files can use raw strings or reference string resources. The following preference resource file example does a bit of both (the string array resources are defined elsewhere in the strings.xml resource file):

<?xml version="1.0" encoding="utf-8"?>
<PreferenceScreen
xmlns:android="http://schemas.android.com/apk/res/android">
<EditTextPreference
android:key="username"
android:title="Username"
android:summary="This is your ACME Service username"
android:defaultValue=""
android:dialogTitle="Enter your ACME Service username:" />
<EditTextPreference
android:key="email"
android:title="Configure Email"
android:summary="Enter your email address"
android:defaultValue="your@email.com" />
<PreferenceCategory
android:title="Game Settings">
<CheckBoxPreference
android:key="bSoundOn"
android:title="Enable Sound"
android:summary="Turn sound on and off in the game"
android:defaultValue="true" />
<CheckBoxPreference
android:key="bAllowCheats"
android:title="Enable Cheating"
android:summary="Turn the ability to cheat on and off in the game"
android:defaultValue="false" />
</PreferenceCategory>
<PreferenceCategory
android:title="Game Character Settings">
<ListPreference
android:key="gender"
android:title="Game Character Gender"
android:summary="This is the gender of your game character"
android:entries="@array/char_gender_types"
android:entryValues="@array/char_genders"
android:dialogTitle="Choose a gender for your character:" />
<ListPreference
android:key="race"
android:title="Game Character Race"
android:summary="This is the race of your game character"
android:entries="@array/char_race_types"
android:entryValues="@array/char_races"
android:dialogTitle="Choose a race for your character:" />
</PreferenceCategory>
</PreferenceScreen>

This XML preference file is organized into two categories and defines fields for collecting several pieces of information, including a username (String), sound setting (boolean), cheat setting (boolean), character gender (fixed String), and character race (fixed String).

For instance, this example uses the CheckBoxPreference type to manage boolean shared preference values, for example, game settings such as whether or not sound is enabled or whether cheating is allowed. Boolean values are checked on and off straight from the screen. The example uses the EditTextPreference type to manage the username, and it uses ListPreference types to allow the user to choose from a list of options. Finally, the settings are organized into categories using <PreferenceCategory> tags.

Next, you need to wire up your PreferenceActivity class and tell it about your preference resource file.

Using the PreferenceActivity Class

The PreferenceActivity class (android.preference.PreferenceActivity) is a helper class that is capable of displaying a PreferenceFragment. This PreferenceFragment loads up your XML preference resource file and transforms it into a standard settings screen, much as you see in the Android device settings. Figure 11.1 shows what the screen for the preference resource file discussed in the previous section looks like when loaded into a PreferenceActivity class.

Figure 11.1 Game settings managed with PreferenceActivity.

To wire up your new preference resource file, create a new class that extends the PreferenceActivity class within your application. Next, override the onCreate() method of your class. Retrieve the FragmentManager for the Activity, start a FragmentTransaction, insert yourPreferenceFragment into the Activity, and then call commit(). Tie the preference resource file to the PreferenceFragment class using the addPreferencesFromResource() method. You will also want to retrieve an instance of the PreferenceManager (android.preference.PreferenceManager) and set the name of these preferences for use in the rest of your application at this time, if you’re using a name other than the default. Here is the complete implementation of the SimpleUserPrefsActivity class, which encapsulates these steps:

public class SimpleUserPrefsActivity extends PreferenceActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
FragmentManager manager = getFragmentManager();
FragmentTransaction transaction = manager.beginTransaction();
transaction.replace(android.R.id.content,
new SimpleUserPrefsFragment());
transaction.commit();
}


public static class SimpleUserPrefsFragment extends PreferenceFragment {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
PreferenceManager manager = getPreferenceManager();
manager.setSharedPreferencesName("user_prefs");
addPreferencesFromResource(R.xml.userprefs);
}
}
}

Now you can simply wire up the Activity as you normally would. Don’t forget to register it within your application’s Android manifest file. When you run the application and start the UserPrefsActivity, you should see a screen that looks like Figure 11.1. Trying to edit all other preferences will launch a dialog with the appropriate type of prompt (EditText or Spinner control), as shown in Figures 11.2 and 11.3.

Figure 11.2 Editing an EditText (String) preference.

Figure 11.3 Editing a ListPreference (String array) preference.

Use the EditTextPreference type to manage String shared preference values, such as username, as shown in Figure 11.2.

Use the ListPreference type to force the user to choose from a list of options, as shown in Figure 11.3.

Organizing Preferences with Headers

The concept of Preference headers was added in Android 3.0 (API Level 11). The headers feature allows your application to present a list of options for navigating to setting subscreens. A very good example of a system application that uses the headers feature is the Android system Settings application. On large-screen devices, the left pane displays the setting list items and, depending on which setting item is selected, determines what setting options are displayed in the right pane. There are a few setup steps for making your application ready for incorporating the preference headers feature:

1. Create individual PreferenceFragment classes for each setting collection.

2. Define the header list using the <preference-headers> tag in a new XML file.

3. Create a new PreferenceActivity class that calls the method onBuildHeaders for loading the headers resource file.