See Also: PreferenceActivity Members
This is the base class for an activity to show a hierarchy of preferences to the user. Prior to NoType:android/os/Build$VERSION_CODES;Href=../../../reference/android/os/Build.VERSION_CODES.html#HONEYCOMB this class only allowed the display of a single set of preference; this functionality should now be found in the new Android.Preferences.PreferenceFragment class. If you are using PreferenceActivity in its old mode, the documentation there applies to the deprecated APIs here.
This activity shows one or more headers of preferences, each of which is associated with a Android.Preferences.PreferenceFragment to display the preferences of that header. The actual layout and display of these associations can however vary; currently there are two major approaches it may take:
Subclasses of PreferenceActivity should implement PreferenceActivity.onBuildHeaders(java.util.List<android.preference.PreferenceActivity.Header>) to populate the header list with the desired items. Doing this implicitly switches the class into its new "headers + fragments" mode rather than the old style of just showing a single preferences list.
For information about using PreferenceActivity, read the Settings guide.
The following sample code shows a simple preference activity that has two different sets of preferences. The implementation, consisting of the activity itself as well as its two preference fragments is:
java Example
public class PreferenceWithHeaders extends PreferenceActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Add a button to the header list.
if (hasHeaders()) {
Button button = new Button(this);
button.setText("Some action");
setListFooter(button);
}
}
/**
* Populate the activity with the top-level headers.
*/
@Override
public void onBuildHeaders(List<Header> target) {
loadHeadersFromResource(R.xml.preference_headers, target);
}
/**
* This fragment shows the preferences for the first header.
*/
public static class Prefs1Fragment extends PreferenceFragment {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Make sure default values are applied. In a real app, you would
// want this in a shared function that is used to retrieve the
// SharedPreferences wherever they are needed.
PreferenceManager.setDefaultValues(getActivity(),
R.xml.advanced_preferences, false);
// Load the preferences from an XML resource
addPreferencesFromResource(R.xml.fragmented_preferences);
}
}
/**
* This fragment contains a second-level set of preference that you
* can get to by tapping an item in the first preferences fragment.
*/
public static class Prefs1FragmentInner extends PreferenceFragment {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Can retrieve arguments from preference XML.
Log.i("args", "Arguments: " + getArguments());
// Load the preferences from an XML resource
addPreferencesFromResource(R.xml.fragmented_preferences_inner);
}
}
/**
* This fragment shows the preferences for the second header.
*/
public static class Prefs2Fragment extends PreferenceFragment {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Can retrieve arguments from headers XML.
Log.i("args", "Arguments: " + getArguments());
// Load the preferences from an XML resource
addPreferencesFromResource(R.xml.preference_dependencies);
}
}
}The preference_headers resource describes the headers to be displayed and the fragments associated with them. It is:
xml Example
<preference-headers
xmlns:android="http://schemas.android.com/apk/res/android">
<header android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs1Fragment"
android:icon="@drawable/ic_settings_applications"
android:title="Prefs 1"
android:summary="An example of some preferences." />
<header android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs2Fragment"
android:icon="@drawable/ic_settings_display"
android:title="Prefs 2"
android:summary="Some other preferences you can see.">
<!-- Arbitrary key/value pairs can be included with a header as
arguments to its fragment. -->
<extra android:name="someKey" android:value="someHeaderValue" />
</header>
<header android:icon="@drawable/ic_settings_display"
android:title="Intent"
android:summary="Launches an Intent.">
<intent android:action="android.intent.action.VIEW"
android:data="http://www.android.com" />
</header>
</preference-headers>The first header is shown by Prefs1Fragment, which populates itself from the following XML resource:
xml Example
<PreferenceScreen
xmlns:android="http://schemas.android.com/apk/res/android">
<PreferenceCategory
android:title="@string/inline_preferences">
<CheckBoxPreference
android:key="checkbox_preference"
android:title="@string/title_checkbox_preference"
android:summary="@string/summary_checkbox_preference" />
</PreferenceCategory>
<PreferenceCategory
android:title="@string/dialog_based_preferences">
<EditTextPreference
android:key="edittext_preference"
android:title="@string/title_edittext_preference"
android:summary="@string/summary_edittext_preference"
android:dialogTitle="@string/dialog_title_edittext_preference" />
<ListPreference
android:key="list_preference"
android:title="@string/title_list_preference"
android:summary="@string/summary_list_preference"
android:entries="@array/entries_list_preference"
android:entryValues="@array/entryvalues_list_preference"
android:dialogTitle="@string/dialog_title_list_preference" />
</PreferenceCategory>
<PreferenceCategory
android:title="@string/launch_preferences">
<!-- This PreferenceScreen tag sends the user to a new fragment of
preferences. If running in a large screen, they can be embedded
inside of the overall preferences UI. -->
<PreferenceScreen
android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs1FragmentInner"
android:title="@string/title_fragment_preference"
android:summary="@string/summary_fragment_preference">
<!-- Arbitrary key/value pairs can be included for fragment arguments -->
<extra android:name="someKey" android:value="somePrefValue" />
</PreferenceScreen>
<!-- This PreferenceScreen tag sends the user to a completely different
activity, switching out of the current preferences UI. -->
<PreferenceScreen
android:title="@string/title_intent_preference"
android:summary="@string/summary_intent_preference">
<intent android:action="android.intent.action.VIEW"
android:data="http://www.android.com" />
</PreferenceScreen>
</PreferenceCategory>
<PreferenceCategory
android:title="@string/preference_attributes">
<CheckBoxPreference
android:key="parent_checkbox_preference"
android:title="@string/title_parent_preference"
android:summary="@string/summary_parent_preference" />
<!-- The visual style of a child is defined by this styled theme attribute. -->
<CheckBoxPreference
android:key="child_checkbox_preference"
android:dependency="parent_checkbox_preference"
android:layout="?android:attr/preferenceLayoutChild"
android:title="@string/title_child_preference"
android:summary="@string/summary_child_preference" />
</PreferenceCategory>
</PreferenceScreen>Note that this XML resource contains a preference screen holding another fragment, the Prefs1FragmentInner implemented here. This allows the user to traverse down a hierarchy of preferences; pressing back will pop each fragment off the stack to return to the previous preferences.
See Android.Preferences.PreferenceFragment for information on implementing the fragments themselves.