FileDocCategorySizeDatePackage
PreferenceActivity.javaAPI DocAndroid 1.5 API10228Wed May 06 22:41:56 BST 2009android.preference

PreferenceActivity

public abstract class PreferenceActivity extends android.app.ListActivity implements PreferenceManager.OnPreferenceTreeClickListener
Shows a hierarchy of {@link Preference} objects as lists, possibly spanning multiple screens. These preferences will automatically save to {@link SharedPreferences} as the user interacts with them. To retrieve an instance of {@link SharedPreferences} that the preference hierarchy in this activity will use, call {@link PreferenceManager#getDefaultSharedPreferences(android.content.Context)} with a context in the same package as this activity.

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.

A {@link PreferenceScreen} object should be at the top of the preference hierarchy. Furthermore, subsequent {@link PreferenceScreen} in the hierarchy denote a screen break--that is the preferences contained within subsequent {@link PreferenceScreen} should be shown on another screen. The preference framework handles showing these other screens from the preference hierarchy.

The preference hierarchy can be formed in multiple ways:

  • From an XML file specifying the hierarchy
  • From different {@link Activity Activities} that each specify its own preferences in an XML file via {@link Activity} meta-data
  • From an object hierarchy rooted with {@link PreferenceScreen}

    To inflate from XML, use the {@link #addPreferencesFromResource(int)}. The root element should be a {@link PreferenceScreen}. Subsequent elements can point to actual {@link Preference} subclasses. As mentioned above, subsequent {@link PreferenceScreen} in the hierarchy will result in the screen break.

    To specify an {@link Intent} to query {@link Activity Activities} that each have preferences, use {@link #addPreferencesFromIntent}. Each {@link Activity} can specify meta-data in the manifest (via the key {@link PreferenceManager#METADATA_KEY_PREFERENCES}) that points to an XML resource. These XML resources will be inflated into a single preference hierarchy and shown by this activity.

    To specify an object hierarchy rooted with {@link PreferenceScreen}, use {@link #setPreferenceScreen(PreferenceScreen)}.

    As a convenience, this activity implements a click listener for any preference in the current hierarchy, see {@link #onPreferenceTreeClick(PreferenceScreen, Preference)}.

    • see
    Preference
    see
    PreferenceScreen

    Fields Summary
    private static final String
    PREFERENCES_TAG
    private PreferenceManager
    mPreferenceManager
    private static final int
    FIRST_REQUEST_CODE
    The starting request code given out to preference framework.
    private static final int
    MSG_BIND_PREFERENCES
    private android.os.Handler
    mHandler
    Constructors Summary
    Methods Summary
    public voidaddPreferencesFromIntent(android.content.Intent intent)
    Adds preferences from activities that match the given {@link Intent}.

    param
    intent The {@link Intent} to query activities.

            requirePreferenceManager();
        
        setPreferenceScreen(mPreferenceManager.inflateFromIntent(intent, getPreferenceScreen()));
    public voidaddPreferencesFromResource(int preferencesResId)
    Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

    param
    preferencesResId The XML resource ID to inflate.

            requirePreferenceManager();
        
        setPreferenceScreen(mPreferenceManager.inflateFromResource(this, preferencesResId,
                getPreferenceScreen()));
    private voidbindPreferences()

            final PreferenceScreen preferenceScreen = getPreferenceScreen();
        if (preferenceScreen != null) {
            preferenceScreen.bind(getListView());
        }
    public PreferencefindPreference(java.lang.CharSequence key)
    Finds a {@link Preference} based on its key.

    param
    key The key of the preference to retrieve.
    return
    The {@link Preference} with the key, or null.
    see
    PreferenceGroup#findPreference(CharSequence)

            
        if (mPreferenceManager == null) {
            return null;
        }
        
        return mPreferenceManager.findPreference(key);
    public PreferenceManagergetPreferenceManager()
    Returns the {@link PreferenceManager} used by this activity.

    return
    The {@link PreferenceManager}.

            return mPreferenceManager;
    public PreferenceScreengetPreferenceScreen()
    Gets the root of the preference hierarchy that this activity is showing.

    return
    The {@link PreferenceScreen} that is the root of the preference hierarchy.

            return mPreferenceManager.getPreferenceScreen();
    protected voidonActivityResult(int requestCode, int resultCode, android.content.Intent data)

            super.onActivityResult(requestCode, resultCode, data);
        
        mPreferenceManager.dispatchActivityResult(requestCode, resultCode, data);
    public voidonContentChanged()

            super.onContentChanged();
        postBindPreferences();
    protected voidonCreate(android.os.Bundle savedInstanceState)

    
    
        
        super.onCreate(savedInstanceState);

        setContentView(com.android.internal.R.layout.preference_list_content);
        
        mPreferenceManager = onCreatePreferenceManager();
        getListView().setScrollBarStyle(View.SCROLLBARS_INSIDE_OVERLAY);
    private PreferenceManageronCreatePreferenceManager()
    Creates the {@link PreferenceManager}.

    return
    The {@link PreferenceManager} used by this activity.

            PreferenceManager preferenceManager = new PreferenceManager(this, FIRST_REQUEST_CODE);
        preferenceManager.setOnPreferenceTreeClickListener(this);
        return preferenceManager;
    protected voidonDestroy()

            super.onDestroy();
        
        mPreferenceManager.dispatchActivityDestroy();
    protected voidonNewIntent(android.content.Intent intent)

            if (mPreferenceManager != null) {
            mPreferenceManager.dispatchNewIntent(intent);
        }
    public booleanonPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference)
    {@inheritDoc}

            return false;
    protected voidonRestoreInstanceState(android.os.Bundle state)

            super.onRestoreInstanceState(state);

        Bundle container = state.getBundle(PREFERENCES_TAG);
        if (container != null) {
            final PreferenceScreen preferenceScreen = getPreferenceScreen();
            if (preferenceScreen != null) {
                preferenceScreen.restoreHierarchyState(container);
            }
        }
    protected voidonSaveInstanceState(android.os.Bundle outState)

            super.onSaveInstanceState(outState);

        final PreferenceScreen preferenceScreen = getPreferenceScreen();
        if (preferenceScreen != null) {
            Bundle container = new Bundle();
            preferenceScreen.saveHierarchyState(container);
            outState.putBundle(PREFERENCES_TAG, container);
        }
    protected voidonStop()

            super.onStop();
        
        mPreferenceManager.dispatchActivityStop();
    private voidpostBindPreferences()
    Posts a message to bind the preferences to the list view.

    Binding late is preferred as any custom preference types created in {@link #onCreate(Bundle)} are able to have their views recycled.

            if (mHandler.hasMessages(MSG_BIND_PREFERENCES)) return;
        mHandler.obtainMessage(MSG_BIND_PREFERENCES).sendToTarget();
    private voidrequirePreferenceManager()

            if (mPreferenceManager == null) {
            throw new RuntimeException("This should be called after super.onCreate.");
        }
    public voidsetPreferenceScreen(PreferenceScreen preferenceScreen)
    Sets the root of the preference hierarchy that this activity is showing.

    param
    preferenceScreen The root {@link PreferenceScreen} of the preference hierarchy.

            if (mPreferenceManager.setPreferences(preferenceScreen) && preferenceScreen != null) {
            postBindPreferences();
            CharSequence title = getPreferenceScreen().getTitle();
            // Set the title of the activity
            if (title != null) {
                setTitle(title);
            }
        }