Creating Your First Preference Screen
Creating preferences using the PreferenceActivity and a preference XML file is a fairly straightforward process. The first thing you do is create the preference XML file, which defines the layout of the preferences and the string resource values that show up on the screen. These string resources are presented as TextViews on the screen to help the user determine what the preference is for.
The PreferenceScreen I am building is for the Task Reminder application. I want to be able to give my users the chance to set the default time for a reminder (in minutes) and a default title for a new task. As the application stands right now, the default title is empty and the default reminder time is set to the current time. These preferences allow the user to save a couple of steps while building new tasks. For example, if the user normally builds tasks with a reminder time of 60 minutes from now, the user can now set that in the preferences. This new value becomes the value of the reminder time when the user creates a new task.
Building the preferences file
To build your first preference screen, you need to create a res/xml folder in your project. Inside the res/xml folder, create an XML file — I'm naming mine task_preferences.xml. Listing 17-1 outlines what should be in the file.
Listing 17-1: The task_preferences.xml File
<?xml version=“1.0” encoding=“utf-8”?>
<PreferenceScreen →2
xmlns:android=“http://schemas.android.com/apk/res/android”>
<PreferenceCategory →4
android:key=“@string/pref_category_task_defaults_key” →5
android:title=“@string/pref_category_task_defaults_title”> →6
<EditTextPreference →7
android:key=“@string/pref_task_title_key” →8
android:dialogTitle=“@string/pref_task_title_dialog_title” →9
android:dialogMessage=“@string/pref_task_title_message” →10
android:summary=“@string/pref_task_title_summary” →11
android:title=“@string/pref_task_title_title” /> →12
</PreferenceCategory>
<PreferenceCategory →14
android:key=“@string/pref_category_datetime_key” →15
android:title=“@string/pref_category_datetime_title”> →16
<EditTextPreference →17
android:key=“@string/pref_default_time_from_now_key” →18
android:dialogTitle=“@string/pref_default_time_from_now_dialog_title” →19
android:dialogMessage=“@string/pref_default_time_from_now_message” →20
android:summary=“@string/pref_default_time_from_now_summary” →21
android:title=“@string/pref_default_time_from_now_title” /> →22
</PreferenceCategory>
</PreferenceScreen>
Quite a few string resources are introduced in Listing 17-1. They are listed in Listing 17-2. Each numbered line of code is explained as follows:
| →2 | This line is the root-level PreferenceScreen. It is the container for the screen itself. All other preferences live below this declaration. |
| →4 | This line is a PreferenceCategory that defines the category for task defaults, such as title or body. As you may have noticed, on line 13, you declare another PreferenceCategory for the default task time. Normally you would have placed these two items into the same category, but in this instance I asked you to separate them to demonstrate how to use multiple PreferenceCategory elements on one screen. |
| →5 | This line defines the key that is used to store and retrieve the preference from the SharedPreferences. This key must be unique. |
| →6 | This line defines the category title. |
| →7 | This line contains the definition of the EditTextPreference, which is responsible for storing the preference for the default title of a task. |
| →8 | This line contains the key for the default title text EditTextPreference. |
| →9 | The EditTextPreference is a child class of DialogPreference, which means that when you select the preference, you will receive a dialog box similar to the one shown in Figure 17-2. This line of code defines the title for that dialog box. |
| →10 | This line defines the message that appears in the dialog box. |
| →11 | This line defines the summary text that is present on the preferences screen, as shown in Figure 17-1. |
| →12 | This line defines the title of the preference on the preference screen. |
| →14 | This line defines the PreferenceCategory for the default task time. |
| →15 | This line defines the category key. |
| →16 | This line defines the title of the category. |
| →17 | This line is the start of the definition of the EditTextPreference, which stores the default time in minutes (digits) that the task reminder time will default to from the current time. |
| →18 | This line defines the key for the default task time preference. |
| →19 | This line defines the title of the dialog box that presents when the preference is selected. |
| →20 | This line defines the message that will be present in the dialog box. |
| →21 | This line defines the summary of the preference that is present on the main preference screen, as shown in Figure 17-1. |
| →22 | This line defines the title of the preference on the preference screen. |
Adding string resources
For your application to compile, you need the string resources for the preferences. In your res/values/strings.xml file, add the following values:
<!-- Preferences -->
<string name=“pref_category_task_defaults_key”>task_default_category</string>
<string name=“pref_category_task_defaults_title”>Task Title Default</string>
<string name=“pref_task_title_key”>default_reminder_title</string>
<string name=“pref_task_title_dialog_title”>Default Reminder Title</string>
<string name=“pref_task_title_message”>The default title for a reminder.</
string>
<string name=“pref_task_title_summary”>Default title for reminders.</string>
<string name=“pref_task_title_title”>Default Reminder Title</string>
<string name=“pref_category_datetime_key”>date_time_default_category</string>
<string name=“pref_category_datetime_title”>Date Time Defaults</string>
<string name=“pref_default_time_from_now_key”>time_from_now_default</string>
<string name=“pref_default_time_from_now_dialog_title”>Time From Now</string>
<string name=“pref_default_time_from_now_message”>The default time from now (in
minutes) that a new reminder should be set to.</string>
<string name=“pref_default_time_from_now_summary”>Sets the default time for a
reminder.</string>
<string name=“pref_default_time_from_now_title”>Default Reminder Time</string>
You should now be able to compile your application.
Defining a preference screen was fairly simple — provide the values to the attributes needed and you're done. Although the preference screen may be defined in XML, simply defining it in XML does not mean that it will show up on the screen. To get your preference screen to display on the screen, you need to create a PreferenceActivity.