Preference / Settings
(Android phone – how-to/example)
An android.preference.PreferenceActivity “shows a hierarchy of Preference objects as lists, possibly spanning multiple screens. These preferences will automatically save to SharedPreferences as the user interacts with them. Furthermore, the preferences shown will follow the visual style of system preferences. It is easy to create a hierarchy of preferences (that can be shown on multiple screens) via XML. For these reasons, it is recommended to use this activity (as a superclass) to deal with preferences in applications.” For example:
public final class PreferencesActivity extends android.preference.PreferenceActivity
implements OnSharedPreferenceChangeListener
{
In order to display the preferences the PreferenceActivity may call addPreferencesFromResource(int preferencesResId) method where preferencesResId is the id of preference.xml.
A preference.xml may look like this:
< PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
< PreferenceCategory android:title="First category">
< ListPreference
android:key="preferences_set_1"
android:title="First SET 1"/>
< EditTextPreference
android:key="preferences_set_2"
android:title="First SET 2"/>
< CheckBoxPreference
android:key="preferences_set_3"
android:defaultValue="true"
android:title="First SET 3"/>
< /PreferenceCategory>< PreferenceCategory android:title="Second category">
< CheckBoxPreference
android:key="preferences_set_4"
android:defaultValue="false"
android:title="Second Set 4"/>
< Preference
android:key="preferences_set_5"
android:title="Second Set 5"/>
< /PreferenceCategory>< /PreferenceScreen>
Note: The full documentation for PreferenceCategory, EditTextPreference, CheckBoxPreference, Preference may be found on http://developer.android.com/reference/android/preference/PreferenceActivity.html
Every preference must have a key defined in XML and in code. Example:
public static final String KEY_SET_1 = “preferences_set_1″;
To link the XML to the java code you need to do the folowing steps:
1. Create a PreferenceScreen object.“android.preference.PreferenceScreen represents a top-level Preference that is the root of a Preference hierarchy. A PreferenceActivity points to an instance of this class to show the preferences.”
Example: PreferenceScreen preferences;
2. Initialize PreferenceScreen object using getPreferenceScreen method. “android.preference.PreferenceActivity.getPreferenceScreen() method gets the root of the preference hierarchy that this activity is showing.”
Example: preferences = getPreferenceScreen();
3. Create a preference object that is also in XML and use findPreference(CharSequence key) method where key is the key of the preference. “android.preference.PreferenceGroup.findPreference(CharSequence key) finds a Preference based on its key.”
Example: CheckBoxPreference m_cbpSET1 = (CheckBoxPreference) preferences.findPreference(KEY_SET_1);
If you want to add an action when the preference is changed you must use the setOnPreferenceChangeListener method. This method “sets the callback to be invoked when this Preference is changed by the user (but before the internal state has been updated).”
Example:
m_cbpSET1.setOnPreferenceChangeListener(new OnPreferenceChangeListener() {
public boolean onPreferenceChange(Preference preference, Object newValue) {
/* your code here */
return true;
}
});
Code example: you may find useful to see the whole implementation of this in the Mezzofanti application – google code. The code is released under Apache License, ver 2.0, so you can freely use it free of charge in your own code. Consult the class PreferenceActivity.java.
