Preference Settings

  • Written by  Clive

Preference Settings

Android Preference Settings icon

Preference Settings allow the user to select basic settings for an app. It’s a way of customising the app to suite the user.

This tutorial will show you how you can create your own custom Preference Settings for your apps.

We’ll be using fragments and Headers so this tutorial is suitable for apps developed for devices running Android 3.0 and up.

There are four parts to the Preference Framework. We’ll cover all of them:

  • Preference Screen Layout –the xml file defining your settings items
  • Preference Activity and Fragment – these host the Preference screens. The activity hosts the fragment and the fragment hosts the Preference Screen, displaying your settings
  • Preference Headers – these are lists of subscreens. An xml file defines the Preference Fragments used for the Headers subscreens
  • Shared Preference Change Listener – listens for any changes in the Shared Preference values

Each Preference appears as an item in a list. The user is able to modify these preference settings.

Each preference has a corresponding key/value pair. These are saved in a SharedPreferences file.

You should only read this file in your app and only make changes to it in the Settings.

The values are saved as:

  • Boolean
  • Float
  • Long
  • Int
  • String
  • String set

The tutorial app

Here’s a quick overview of our tutorial app.

It displays a Settings screen when the app starts. This screen has a few check boxes and an edit text field. It also has a preference item that triggers an intent to start a new activity.

We use the new activity to demonstrate Preference Headers. Preference Headers is a feature that lets you build a list of subscreens. Selecting one of the list items displays a subscreen in a fragment.

The tutorial also shows you how to:

  • use a list of preferences
  • use a multiple choice list of preferences

We also show you how to listen for when preference settings are changed and how to read the saved preferences from the SharedPreferences file.

Android Preference Settings tutorial app screenshot 1

The main Settings screen is on the left. Selecting the Headers Preferences option displays a list of subscreens. Selecting either of these options displays the settings for that subscreen

Android Preference Settings tutorial app screenshot 2

The Galactic Transport subscreen. Choosing the Select Transport option displays the list on the right

Android Preference Settings tutorial app screenshot 3

The Galactic Cuisine subscreen. Choosing the Select your food option displays the list on the top-right where you can choose one item. Choosing the Try MultiListChoice option displays the list on the bottom-right where you can choose multiple items

Android Preference Settings display shared preferences

Choosing Read saved preferences displays this screen which shows all the settings values read from the saved preference file

Android Preference Settings tutorial diagram

A diagrammatic representation of our tutorial preference settings app

The basic Settings: The Main Activity includes the Preference Fragment

This is the entry point to the app. It hosts a fragment that displays our basic preference settings.

Here’s the code:

Android Preference Settings main activity

Our MainActivity activity hosts the MainSettingsFragment that displays our preference settings

Note the following:

  • We have an activity that includes an inner fragment class
  • In the activity’s onCreate() we begin a transaction to display the fragment
  • addPreferencesFromResource – inflates our preference resource file into the fragment, displaying our Settings

The preferences.xml file

We define the Settings in an xml file, preferences.xml which is saved in the res/xml folder. These are the settings that will be displayed on the first screen.

The root node for the preference file must be <PreferenceScreen>.

Each Setting preference item is then added.

You can group items together. There are two ways of doing this:

  • You can group items together with a title. Use <PreferenceCategory> to do this
  • You can also group items together, including a title by using <PreferenceScreen>. Clicking on the title displays a subscreen containing the preference items

You can also include an intent as a preference item. You can use this to open a new activity.

Android Preference Settings screenshot

A screenshot of our basic Settings using the preferences.xml file

Here’s the first part of code for our preferences.xml file:

Android Preference Settings preferences.xml

We group a number of CheckBoxPreference items using the PreferenceCategory element

Note the following:

  • This is the first part of our preferences.xml file
  • <PreferenceScreen> - the root node for our preference file
  • <PreferenceCategory> - groups our preference items and includes a title
  • <CheckBoxPreference> - a check box that can be set to true or false
  • android:dependency – this check box depends on the one above. If that one is not enabled then neither is this one
  • android:layout – this attribute determines the layout for this checkbox
  • the basic attributes that each preference should include are:
    • android:key – the Shared Preference key which identifies this preferences value
    • android:title – the displayed title for this preference
    • android:summary – displays extra information about this preference
    • android:defaultValue – the default value that will be used for this preference if no other is selected

Here’s the second part of code for our preferences.xml file:

Android Preference Settings preferences.xml

We use the PreferenceScreen element to display a new screen when the item is clicked

Note the following:

  • This is the second part of our preferences.xml file
  • <EditTextPreference> - allows users to enter string values
  • <intent> - when clicked, invokes an intent to start a new activity
  • android:targetPackage – the package part of the component name to assign to the Intent
  • android:targetClass – the class part of the component name to assign to the Intent

The Headers list of subscreens: The Headers Activity and Fragment

Headers are a list of subscreens. Selecting an item from the list displays the subscreen in a fragment.

Preference Headers are defined in an xml resource file. They describe how our Preference Fragments should be grouped and displayed within a Preference Activity.

Each of our headers identifies the same fragment to be displayed when the header item is clicked. We pass extra data as an argument to identify which preference resource to display in the fragment.

The HeadersActivity activity

Our HeadersActivity includes the HeadersFragment fragment as an inner class.

The activity builds the headers list in the included HeadersFragment fragment.

Here’s the code:

Android Preference Settings Headers activity

Include onBuildHeaders() in the Headers activity to build the list of headers

Note the following:

  • there’s no onCreate()
  • onBuildHeaders –is called for the activity to build the list of headers. The list is displayed in the HeadersFragment fragment

The Headers preference file: The preference_headers.xml file

Our preference headers are defined in an xml resource file, preference_headers.xml saved in the res/xml folder.

Here’s the code:

Android Preference Settings header Preference Xml

Our Header preference file. We use the same HeadersFragment fragment for both header items. The extra argument determines which preference file to inflate in the fragment

Note the following:

  • android:fragment – the fragment that will be displayed when this header is selected
  • android:summary – the summary text for this header item
  • android:title – the title for this header item
  • extra – we pass an extra piece of data as an argument to the HeadersFragment fragment. It’ll use it to select the correct preference resource file

The HeadersFragment fragment

The HeadersFragment fragment displays the list of headers.

You may want to read Dynamic layouts using fragments for more on fragments.

Android Preference Settings Headers list

Selecting Headers Preferences from the first Settings screen displays this Headers list subscreen

The extra data passed as an argument determines which preference resource file to use.

Here’s the code for the fragment:

Android Preference Settings Headers Fragment

The HeadersFragment fragment displays the list of headers

Note the following:

  • onSharedPreferenceChangeListener – we use this interface to listen for when a preference value is changed
  • getArguments().getString() – we get the argument passed to the fragment when the headers item was clicked. We assign it to our settings object
  • if statement – we use an if statement to filter the settings string and select the appropriate preference file for the selected header item
  • addPreferencesFromResource – we inflate the preference resource file in the fragment. It shows the preference settings defined by that resource file
  • registerOnSharedPreferenceChangeListener – we register a callback to be invoked when a preference item’s value has changed. It’s registered  in onResume() when the fragment is visible to the user
  • unregisterOnSharedPreferenceChangeListener – we unregister the callback in onPause() when the fragment may not be entirely visible as another activity has taken focus
  • onSharedPreferenceChanged – called when a preference item’s value has changed
  • if statement – we’re interested in the food_preference preference item. If the key matches food_preference then we set the summary text to display the selected value

Selecting a Headers item

If the user selected the Galactic Cuisine header item then the argument received by the HeadersFragment fragment would be two. The preference_header_two.xml resource file will be inflated in the fragment.

Android Preference Settings Headers Fragment subscreen

Here are the preference items for the Galactic Cuisine option

Here’s the code for the preference_header_two.xml resource file:

Android Preference Settings Headers Fragment subscreen

Our preference file includes a ListPreference for single choice items and a MultiSelectListPreference for multiple choice items

Note the following:

  • there are 3 preference items:
    • list preference – displays a list of items. The user can select one item from the list. Selecting an item triggers onSharedPreferenceChangeListener() in the fragment and the list preference’s summary text is changed to reflect the selected item

Android Preference Settings list

The single choice list

    • MultiSelectListPreference –displays a list of items. The user can select multiple items from the list. This list is defined within its own <PreferenceScreen> and will display as a subscreen

Android Preference Settings multiple choice list

The multiple choice list

    • intent – selecting the intent starts the ShowPreferences activity which gets and displays all the shared preferences
  • android:dialogTitle – this is the title that appears in the dialog window displaying the list
  • android:entries – this is the array that is displayed in the list
  • android:entryValues – this is the array of values that are saved in the preference file when a list item is selected
  • android:defaultValue – in the case of the list, you can provide a single item as the default. In the case of the multiple choice list, you can either provide an empty array if you don’t want to supply any default values, or you can provide an array that contains the values that you want to be set as the defaults

The list Arrays

The string arrays used in the lists are saved in the arrays.xml file in the res/values folder.

Here’s the code:

Android Preference Settings list string arrays

The String arrays used in the preference lists

Getting and showing the saved preferences: The ShowPreferences Activity

At anytime and anywhere in your app, you can retrieve the preference values that have been set and saved in the SharedPreferences file.

We’ve done it in the ShowPreferences activity.

Android Preference Settings display preferences

We get all the preferences out of the SharedPreferences file and display them in text views

Here’s a code snippet from the ShowPreferences activity:

Android Preference Settings display preferences get Preferences

Get a SharedPreferences object and then get the preferences out of the object

Note the following:

  • sharedPreferences – we get an instance of SharedPreferences and assign it to sharedPreferences
  • getBoolean – we use this to get the boolean value for the PARENT_EXPLORER_PREFERENCE key. If there is no value, we supply the default of true that will be used. There are other get<type> methods that you can use to get the saved preferences out of the SharedPreferences object
  • PARENT_EXPLORER_PREFERENCE – this is a constant that we’ve declared for the parent_explorer_preference preference. The values are saved as key/value pairs. We use the preference key, as defined by the key attribute (android:key) in the preference file, as the key

I hope that you have found this tutorial helpful.

This tutorial was created using Android Studio. You can download the project files here Download icon

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.