How to develop Android apps with Preferences

Abstract

In this post I'll show you how to develop an Android app to be able to accept user configurations throw the API Preferences. Using this API you can easy show, store and retreive user configurations, without care about how those informations are stored. As you will see, this is actually easy to do, just write an XML file and some bunch of Java code.

Before start

In order to show how Preferences works, I'll write a simple Android app that only shows the user configuration and open the configuration menù. This menù is made using only the layout files, without hard coding. In this example I'll use the SDK 11 (Honeycomb), beacause the older versions are not compatible.

What we need

For use Preferences, you don't need nothing but the Android SDK, because this API is integrated in it. So, if you don't have the IDE, download it from here.

Preferences.xml

The preferences options are stored in a XML file, just like a normal Activity layout file. Every option is identified by an android:key attribute, a string key that allow you to retrive the option value.

The root element is PreferenceScreen that define the menù option layout.

The option elements are:

• CheckBoxPreference: a checkbox that rappresent a boolean value
• EditTextPreference: shows a EditText of free-text string
• ListPreference: shows a list of selectable items
• MultiSelectListPreference: like the above, but allows user to select several items
• RingtonePreference: shows a list of the ringtones from on the device
• SwitchPreference: similar to CheckBoxPreference but shows a toggleable switch

You can also group the option throw a PreferenceCategory, for logically separate items. It also shows a title for the group.

Ready, steady, code!

Finally we are ready to code our preferences menù. First of all, lets define what options we want to show. For example I'll create a simple menù with a checkbox and an edittext in 2 different categories.
Well, check if res/xml directory exists (if not make it) and add a preferences.xml file. So, write the following code:
<?xml version="1.0" encoding="utf-8"?>
<PreferenceScreen
  xmlns:android="http://schemas.android.com/apk/res/android">

 <PreferenceCategory
   android:title="First PreferenceCategory">

  <CheckBoxPreference
    android:key="checkbox_preference"
    android:title="title checkbox preference"
    android:summary="summary of the checkbox preference" />
 </PreferenceCategory>

 <PreferenceCategory
   android:title="Second PreferenceCategory">

  <EditTextPreference
    android:key="edittext_preference"
    android:title="title edittext preference"
    android:summary="summary of the edittext preference"
    android:dialogTitle="dialog title edittext preference" />

 </PreferenceCategory>

</PreferenceScreen>


Then create a class that rappresent the menù. The class extends android.preference.PreferenceFragment, and it displays the menù itself. In the method onCreate we call addPreferencesFromResource to load graphical interface from the file preferences.xml, like so:
package com.blogspot.virtualinsanity106.preferences.fragments;

import com.blogspot.virtualinsanity106.preferences.R; //NOT android.R

import android.os.Bundle;
import android.preference.PreferenceFragment;
import android.util.Log;

public class PreferencesTest extends PreferenceFragment {
 private static final String TAG = "PreferencesTest";
 @Override
 public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  //create the fragment content from preferences.xml
  addPreferencesFromResource(R.xml.preferences);
  Log.d(TAG, "Content created");
 }
}


In order to store and display the user option, I'll create 2 activities: one, MainActivity, shows the user options and the other, SetPreferencesActivity, displays the menù and store the values.
The MainActivity layout file (res/layout/main.xml) has 2 TextView and a button for lunch the SetPreferencesActivity as follows:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
 android:layout_width="match_parent"
 android:layout_height="match_parent"
 android:orientation="vertical" >
 <!-- this shows the edittext_preference preference -->
 <TextView
  android:id="@+id/textview_edittext"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:text=""
  android:textAppearance="?android:attr/textAppearanceLarge" />
 <!-- this shows the checkbox_preference preference -->
 <TextView
  android:id="@+id/textview_checkbox"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:text="" />
 <!-- this shows the SetPreferencesActivity activity-->
 <Button
  android:id="@+id/button_edit"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:text="@string/button_edit_label"
  android:onClick="onEditClick"/><!-- function to show the edit activity -->

</LinearLayout>

The SetPreferencesActivity layout file (res/layout/setpreferences.xml) shows the fragment created above and a button for come back to MainActivity, just like that:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
 android:layout_width="match_parent"
 android:layout_height="match_parent"
 android:orientation="vertical" >
 <!-- this is the preferences fragment -->
 <fragment
  android:id="@+id/fragment_preferences"
  android:name="com.blogspot.virtualinsanity106.preferences.fragments.PreferencesTest"
  android:layout_width="match_parent"
  android:layout_height="wrap_content" />
 <!-- this is the "Back" button -->
 <Button
  android:id="@+id/button_back"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:text="@string/button_back_label"
  android:onClick="onBackClick"/><!-- function to come back to the main activity -->

</LinearLayout>


Now create the 2 Java classes for the activities. The SetPreferencesActivity class create the content from the file setpreferences.xml and close itself on button back click, in this way:
package com.blogspot.virtualinsanity106.preferences;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;

public class SetPreferencesActivity extends Activity {
 @Override
 protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.setpreferences);
 }
 public void onBackClick(View v){
  setResult(RESULT_OK);
  finish();
 }
}

The MainActivity class provides to load the graphics from main.xml file, then load the user preferences at the boot. On the edit button click shows the SetPreferencesActivity and, then this one ends, reload the properties, as follows:
package com.blogspot.virtualinsanity106.preferences;

import android.os.Bundle;
import android.preference.PreferenceManager;
import android.util.Log;
import android.view.View;
import android.widget.TextView;
import android.app.Activity;
import android.content.Intent;
import android.content.SharedPreferences;

public class MainActivity extends Activity {
 private static final String TAG = "MainActivity";
 private TextView txtDisplayEditText;
 private TextView txtDisplayCheck;
 @Override
 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  loadPreferences(); //when the preferencesactivity ends, reload preferences when properties activity close
 }
 @Override
 protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);//set the content from main.xml
 txtDisplayEditText = (TextView) findViewById(R.id.textview_edittext);
  txtDisplayCheck = (TextView) findViewById(R.id.textview_checkbox);
  loadPreferences();//load the edited preferences
 }
 public void onEditClick(View v){
  //open the properties activity
  Log.d(TAG, "Start edit");
  Intent intent = new Intent();
  intent.setClass(MainActivity.this, SetPreferencesActivity.class);
  startActivityForResult(intent, 0);
 }
 private void loadPreferences(){
  SharedPreferences sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this); //load the preferences
  txtDisplayEditText.setText(sharedPreferences.getString("edittext_preference", getString(R.string.edittext_default_text))); //by default show the edittext_default_text string
  boolean isCheckboxSelected = sharedPreferences.getBoolean("checkbox_preference", false);//by default the checkbox isn't selected
  if(isCheckboxSelected)//if the checkbox is selected, show the "checkbox_true" string, otherwise show the "checkbox_false" string
   txtDisplayCheck.setText(getString(R.string.checkbox_true));
  else
   txtDisplayCheck.setText(getString(R.string.checkbox_false));
 }
}


Don't forget to add SetPreferencesActivity in your AndroidManifest.xml in order to correct display then, in this manner:
<activity android:name="SetPreferencesActivity"></activity>

Conclusions

In this post I showed you how to display and store an options menù in an Android app, and how read the user options throw the Preferences API. This API is included in the Android SDK, so we don't need to add jars in our project. In this post I had added some "non-option element" (like the Back button) in the menù without using a work-around for emulate the functions but just add that in the menù layout.

Some files are not included in this post, you can download the entire project here