Beginning Android

return a Boolean preference). The getters also take a default value, which is returned if there is no preference set under the specified key.

Stating Your Preference

Given the appropriate SharedPreferences object, you can use edit() to get an “editor” for the preferences. This object has a group of setters that mirror the getters on the parent SharedPreferences object. It also has the following:

• remove() to get rid of a single named preference

• clear() to get rid of all preferences

• commit() to persist your changes made via the editor

The last one is important — if you modify preferences via the editor and fail to commit() the changes, those changes will evaporate once the editor goes out of scope.

Conversely, since the preferences object supports live changes, if one part of your application (say, an activity) modifies shared preferences, another part of your application (say, a service) will have access to the changed value immediately.

And Now, a Word from Our Framework

Beginning with the 0.9 SDK, Android has a framework for managing preferences. This framework does not change anything mentioned previously. Instead, the framework is more for presenting consistent preference-setting options for users so different applications do not have to reinvent the wheel.

The linchpin to the preferences framework is yet another XML data structure. You can describe your application’s preferences in an XML file stored in your project’s res/xml/ directory. Given that, Android can present a pleasant UI for manipulating those preferences, which are then stored in the SharedPreferences you get back from getDefaultSharedPreferences().

The following is the preference XML for the Prefs/Simple preferences sample project available in the Source Code section at http://apress.com:

<PreferenceScreen
 xmlns:android='http://schemas.android.com/apk/res/android'>
 <CheckBoxPreference
  android:key='@string/checkbox'
  android:title='Checkbox Preference'
  android:summary='Check it on, check it off' />
 <RingtonePreference
  android:key='@string/ringtone'
  android:title='Ringtone Preference'
  android:showDefault='true'
  android:showSilent='true'
  android:summary='Pick a tone, any tone' />
</PreferenceScreen>

The root of the preference XML is a PreferenceScreen element. (I will explain why it is named that later in this chapter; for now, take it on faith that it is a sensible name.) One of the things you can have inside a PreferenceScreen element, not surprisingly, is preference definitions — subclasses of Preference, such as CheckBoxPreference or RingtonePreference, as shown in the preceding code. As one might expect, these allow you to check a checkbox and choose a ringtone, respectively. In the case of RingtonePreference, you have the option of allowing users to choose the system-default ringtone or to choose “silence” as a ringtone.

Letting Users Have Their Say

Given that you have set up the preference XML, you can use a nearly built-in activity for allowing your users to set their preferences. The activity is “nearly built-in” because you merely need to subclass it and point it to your preference XML, plus hook the activity into the rest of your application.

So, for example, here is the EditPreferences activity of the Prefs/Simple project available on the Apress Web site:

package com.commonsware.android.prefs;
import android.app.Activity;
import android.os.Bundle;
import android.preference.PreferenceActivity;
public class EditPreferences extends PreferenceActivity {
 @Override
 public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  addPreferencesFromResource(R.xml.preferences);
 }
}

As you can see, there is not much to see. All you need to do is call addPreferencesFromResource() and specify the XML resource containing your preferences. You will also need to add this as an activity to your AndroidManifest.xml file:

<?xml version='1.0' encoding='utf-8'?>
<manifest xmlns:android='http://schemas.android.com/apk/res/android'
 package='com.commonsware.android.prefs'>
 <application android:label='@string/app_name'>
  <activity
   android:name='.SimplePrefsDemo'
   android:label='@string/app_name'>
   <intent-filter>
    <action android:name='android.intent.action.MAIN' />
    <category android:name='android.intent.category.LAUNCHER' />
   </intent-filter>
  </activity>
  <activity
   android:name='.EditPreferences'
   android:label='@string/app_name'>
  </activity>
 </application>
</manifest>