Android Guides | Samples

Android.Preferences.PreferenceActivity Class

This is the base class for an activity to show a hierarchy of preferences to the user.

See Also: PreferenceActivity

Syntax

[Android.Runtime.Register("android/preference/PreferenceActivity", DoNotGenerateAcw=true)]
public abstract class PreferenceActivity : ListActivity, PreferenceFragment+IOnPreferenceStartFragmentCallback, IDisposable

Remarks

This is the base class for an activity to show a hierarchy of preferences to the user. Prior to Build+VERSION_CODES.Honeycomb this class only allowed the display of a single set of preference; this functionality should now be found in the new 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 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:

  • On a small screen it may display only the headers as a single list when first launched. Selecting one of the header items will re-launch the activity with it only showing the PreferenceFragment of that header.
  • On a large screen in may display both the headers and current PreferenceFragment together as panes. Selecting a header item switches to showing the correct PreferenceFragment for that item.

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.

Developer Guides

For information about using PreferenceActivity, read the Settings guide.

Sample Code

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 PreferenceFragment for information on implementing the fragments themselves.

[Android Documentation]

Requirements

Namespace: Android.Preferences
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 1

The members of Android.Preferences.PreferenceActivity are listed below.

See Also: ListActivity

Public Constructors

Protected Constructors

A constructor used when creating managed representations of JNI objects; called by the runtime.

Public Fields

const
ExtraNoHeadersString. When starting this activity, the invoking Intent can contain this extra boolean that the header list should not be displayed.
const
ExtraShowFragmentString. When starting this activity, the invoking Intent can contain this extra string to specify which fragment should be initially displayed.
const
ExtraShowFragmentArgumentsString. When starting this activity and using PreferenceActivity.ExtraShowFragment, this extra can also be specified to supply a Bundle of arguments to pass to that fragment when it is instantiated during the initial creation of PreferenceActivity.
const
ExtraShowFragmentShortTitleString. When starting this activity and using PreferenceActivity.ExtraShowFragment, this extra can also be specify to supply the short title to be shown for that fragment.
const
ExtraShowFragmentTitleString. When starting this activity and using PreferenceActivity.ExtraShowFragment, this extra can also be specify to supply the title to be shown for that fragment.
const
HeaderIdUndefinedInt64 (-1). Default value for NoType:android/preference/PreferenceActivity$Header;Href=../../../reference/android/preference/PreferenceActivity.Header.html#id indicating that no identifier value is set.

Public Properties

[read-only]
HasHeadersBoolean. Returns true if this activity is currently showing the header list.
[read-only]
IsMultiPaneBoolean. Returns true if this activity is showing multiple panes -- the headers and a preference fragment.
[read-only]
PreferenceManagerPreferenceManager. Returns the PreferenceManager used by this activity.
PreferenceScreenPreferenceScreen. Gets the root of the preference hierarchy that this activity is showing.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

AddPreferencesFromIntent(Intent)
Adds preferences from activities that match the given Intent.
AddPreferencesFromResource(Int32)
Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.
FindPreference(ICharSequence) : Preference
Finds a Preference based on its key.
FindPreference(String) : Preference
FinishPreferencePanel(Fragment, Result, Intent)
Called by a preference panel fragment to finish itself.
InvalidateHeaders()
Call when you need to change the headers being displayed.
LoadHeadersFromResource(Int32, IList<PreferenceActivity.Header>)
OnBuildHeaders(IList<PreferenceActivity.Header>)
OnBuildStartFragmentIntent(String, Bundle, Int32, Int32) : Intent
Called by PreferenceActivity.StartWithFragment(String,Bundle,Bundle,Bundle,Bundle,Bundle) when in single-pane mode, to build an Intent to launch a new activity showing the selected fragment.
OnGetInitialHeader() : PreferenceActivity+Header
Called to determine the initial header to be shown.
OnGetNewHeader() : PreferenceActivity+Header
Called after the header list has been updated (PreferenceActivity.onBuildHeaders(java.util.List<android.preference.PreferenceActivity.Header>) has been called and returned due to PreferenceActivity.InvalidateHeaders) to specify the header that should now be selected.
OnHeaderClick(PreferenceActivity+Header, Int32)
Called when the user selects an item in the header list.
OnIsHidingHeaders() : Boolean
Called to determine whether the header list should be hidden.
OnIsMultiPane() : Boolean
Called to determine if the activity should run in multi-pane mode.
OnPreferenceStartFragment(PreferenceFragment, Preference) : Boolean
Called when the user has clicked on a Preference that has a fragment class name associated with it.
OnPreferenceTreeClick(PreferenceScreen, Preference) : Boolean
SetListFooter(View)
Set a footer that should be shown at the bottom of the header list.
SetParentTitle(ICharSequence, ICharSequence, View+IOnClickListener)
Should be called after onCreate to ensure that the breadcrumbs, if any, were created.
SetParentTitle(String, String, View+IOnClickListener)
ShowBreadCrumbs(ICharSequence, ICharSequence)
Change the base title of the bread crumbs for the current preferences.
ShowBreadCrumbs(String, String)
StartPreferenceFragment(Fragment, Boolean)
Start a new fragment.
StartPreferencePanel(String, Bundle, Int32, ICharSequence, Fragment, Int32)
Start a new fragment containing a preference panel.
StartPreferencePanel(String, Bundle, Int32, String, Fragment, Int32)
StartWithFragment(String, Bundle, Fragment, Int32)
Like PreferenceActivity.StartWithFragment(String,Bundle,Bundle,Bundle,Bundle,Bundle) but uses a 0 titleRes.
StartWithFragment(String, Bundle, Fragment, Int32, Int32, Int32)
Start a new instance of this activity, showing only the given preference fragment.
SwitchToHeader(PreferenceActivity+Header)
When in two-pane mode, switch to the fragment pane to show the given preference fragment.
SwitchToHeader(String, Bundle)
When in two-pane mode, switch the fragment pane to show the given preference fragment.

Protected Methods

IsValidFragment(String) : Boolean
Subclasses should override this method and verify that the given fragment is a valid type to be attached to this activity.