Android Preferences Tutorial

A commonly used feature in most applications, irrespective of whether they are mobile applications or not, is the ability to save some application/user specific settings. Examples include endpoint URLS, the security access token, certain user preferences like color, title, language, etc. While we can surely implement it using our activity and custom forms, the Android framework makes it easier by providing us some great support. It not only implements core stuff like saving to a preferences file and reading out the values, it also helps in providing a standardized look and feel to managing preferences. This helps conserve the familiarity that the user may have while working with preferences in any Android application.

Let us assume that we want to develop a preferences activity for our application and the preferences that we want to set for our application look something like this:

When you click on Your Name, you get a dialog box, where you can enter the value:

If you click on the Application Updates, you can toggle the option as you want.

The last preference is interesting, when you click it, it will bring up a list containing several values from which you can select one as shown below:

Note that we are demonstrating here, 3 common types of preferences that one would need to set for an application:

• A checkbox type of preference, where you are simply interested in a true or false value.
• A edittext type of preference, where you would like the user to enter a value i.e. a text value.
• A list type of preference, where the user is shown a list of options and he/she selects only one of them as their preference.

Now, let us get into the code.

Step 1: Define the preferences.xml

The Preferences Activity screen is defined in the preferences.xml file as shown below. This file is placed in the res\xml folder

<?xml version="1.0" encoding="utf-8"?>
<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
  <EditTextPreference android:title="Your Name"
                      android:key="username"
                      android:summary="Please provide your username"></EditTextPreference>
  <CheckBoxPreference android:title="Application Updates"
                      android:defaultValue="false"
                      android:summary="This option if selected will allow the application to check for latest versions."
                      android:key="applicationUpdates" />
  <ListPreference     android:title="Download Details"
                      android:summary="Select the kind of data that you would like to download"
                      android:key="downloadType"
                      android:defaultValue="1"
                      android:entries="@array/listArray"
                      android:entryValues="@array/listValues" />
</PreferenceScreen>

As you can see the 3 preference values are declaratively mentioned in the preferences.xml file. The Last preference property i.e. of list type refers to string arrays that are defined in the res/values folder in a file named array.xml. The array.xml file is listed below:

<resources>
<string-array name="listArray">
	<item>Headings</item>
	<item>Headings and Details</item>
	<item>All Data</item>
</string-array>
<string-array name="listValues">
    <item>1</item>
    <item>2</item>
    <item>3</item>
</string-array>
</resources>

Step 2: Create the Preferences Activity

The Preferences Activity class is normally extended from the org.android.preference.PreferenceActivity class. The sample class is shown below:

package com.mycompany.android.preferences;

import android.os.Bundle;
import android.preference.PreferenceActivity;

public class AppPreferences extends PreferenceActivity {

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		// TODO Auto-generated method stub
		super.onCreate(savedInstanceState);
		addPreferencesFromResource(R.xml.preferences);
	}

}

Notice that all we need to do is invoke the addPreferencesFromResource(..) method, where we simply provide the reference to the preferences.xml file and Android takes care of the rest for rendering the activity and also saving the values for you.

Notes:

1. To read the preferences values in any part of your application, you can use the code that is shown below:

SharedPreferences SP = PreferenceManager.getDefaultSharedPreferences(getBaseContext());

String strUserName = SP.getString("username", "NA");
boolean bAppUpdates = SP.getBoolean("applicationUpdates",false);
String downloadType = SP.getString("downloadType","1");

The main class to use is the SharedPreferences class and we get an instance to it through the PreferenceManager.

There are several methods defined on the SharedPreferences class like getString, getBoolean,etc that we use over here. Note that the first parameter is the keyname and the second parameter is the default value to return in case the value is not present.

The preferences are saved by default in the data/data/packagename/shared_prefs/packagename_preferences.xml.

So for our case, it is saved as :

data/data/com.mycompany.android.preferences/shared_prefs/com.mycompany.android.preferences_sharedpreferences.xml and the sample content is shown below:

<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
<string name="downloadType">2</string>
<string name="username">Xoriant</string>
<boolean name="applicationUpdates" value="true" />
</map>

Hope this blog post gets you started with Android Preferences. Please feel free to post your comments.