public abstract class

PreferenceActivity

extends ListActivity
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.view.ContextThemeWrapper
         ↳ android.app.Activity
           ↳ android.app.ListActivity
             ↳ android.preference.PreferenceActivity

Class Overview

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. To retrieve an instance of SharedPreferences that the preference hierarchy in this activity will use, call 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 PreferenceScreen object should be at the top of the preference hierarchy. Furthermore, subsequent PreferenceScreen in the hierarchy denote a screen break--that is the preferences contained within subsequent 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 Activities that each specify its own preferences in an XML file via Activity meta-data
  • From an object hierarchy rooted with PreferenceScreen

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

    To specify an Intent to query Activities that each have preferences, use addPreferencesFromIntent(Intent). Each Activity can specify meta-data in the manifest (via the key 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 PreferenceScreen, use setPreferenceScreen(PreferenceScreen).

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

    See Also

    • Summary

    [Expand]
    Inherited Constants
    From class android.app.Activity
    From class android.content.Context
    Public Constructors
    PreferenceActivity()
    Public Methods
    void addPreferencesFromIntent(Intent intent)
    Adds preferences from activities that match the given Intent.
    void addPreferencesFromResource(int preferencesResId)
    Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.
    Preference findPreference(CharSequence key)
    Finds a Preference based on its key.
    PreferenceManager getPreferenceManager()
    Returns the PreferenceManager used by this activity.
    PreferenceScreen getPreferenceScreen()
    Gets the root of the preference hierarchy that this activity is showing.
    void onContentChanged()
    Updates the screen state (current list and other views) when the content changes.
    boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference)
    void setPreferenceScreen(PreferenceScreen preferenceScreen)
    Sets the root of the preference hierarchy that this activity is showing.
    Protected Methods
    void onActivityResult(int requestCode, int resultCode, Intent data)
    Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it.
    void onCreate(Bundle savedInstanceState)
    Called when the activity is starting.
    void onDestroy()
    Perform any final cleanup before an activity is destroyed.
    void onNewIntent(Intent intent)
    This is called for activities that set launchMode to "singleTop" in their package, or if a client used the FLAG_ACTIVITY_SINGLE_TOP flag when calling startActivity(Intent).
    void onRestoreInstanceState(Bundle state)
    Ensures the list view has been created before Activity restores all of the view states.
    void onSaveInstanceState(Bundle outState)
    Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundle populated by this method will be passed to both).
    void onStop()
    Called when you are no longer visible to the user.
    [Expand]
    Inherited Methods
    From class android.app.ListActivity
    From class android.app.Activity
    From class android.view.ContextThemeWrapper
    From class android.content.ContextWrapper
    From class android.content.Context
    From class java.lang.Object
    From interface android.content.ComponentCallbacks
    From interface android.view.KeyEvent.Callback
    From interface android.view.LayoutInflater.Factory
    From interface android.view.View.OnCreateContextMenuListener
    From interface android.view.Window.Callback

    Public Constructors

    public PreferenceActivity ()

    Since: API Level 1

    Public Methods

    public void addPreferencesFromIntent (Intent intent)

    Since: API Level 1

    Adds preferences from activities that match the given Intent.

    Parameters
    intent The Intent to query activities.

    public void addPreferencesFromResource (int preferencesResId)

    Since: API Level 1

    Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

    Parameters
    preferencesResId The XML resource ID to inflate.

    public Preference findPreference (CharSequence key)

    Since: API Level 1

    Finds a Preference based on its key.

    Parameters
    key The key of the preference to retrieve.
    Returns
    See Also

    public PreferenceManager getPreferenceManager ()

    Since: API Level 1

    Returns the PreferenceManager used by this activity.

    Returns

    public PreferenceScreen getPreferenceScreen ()

    Since: API Level 1

    Gets the root of the preference hierarchy that this activity is showing.

    Returns

    public void onContentChanged ()

    Since: API Level 1

    Updates the screen state (current list and other views) when the content changes.

    public boolean onPreferenceTreeClick (PreferenceScreen preferenceScreen, Preference preference)

    Since: API Level 1

    public void setPreferenceScreen (PreferenceScreen preferenceScreen)

    Since: API Level 1

    Sets the root of the preference hierarchy that this activity is showing.

    Parameters
    preferenceScreen The root PreferenceScreen of the preference hierarchy.

    Protected Methods

    protected void onActivityResult (int requestCode, int resultCode, Intent data)

    Since: API Level 1

    Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it. The resultCode will be RESULT_CANCELED if the activity explicitly returned that, didn't return any result, or crashed during its operation.

    You will receive this call immediately before onResume() when your activity is re-starting.

    Parameters
    requestCode The integer request code originally supplied to startActivityForResult(), allowing you to identify who this result came from.
    resultCode The integer result code returned by the child activity through its setResult().
    data An Intent, which can return result data to the caller (various data can be attached to Intent "extras").

    protected void onCreate (Bundle savedInstanceState)

    Since: API Level 1

    Called when the activity is starting. This is where most initialization should go: calling setContentView(int) to inflate the activity's UI, using findViewById(int) to programmatically interact with widgets in the UI, calling managedQuery(android.net.Uri, String[], String, String[], String) to retrieve cursors for data being displayed, etc.

    You can call finish() from within this function, in which case onDestroy() will be immediately called without any of the rest of the activity lifecycle (onStart(), onResume(), onPause(), etc) executing.

    Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

    Parameters
    savedInstanceState If the activity is being re-initialized after previously being shut down then this Bundle contains the data it most recently supplied in onSaveInstanceState(Bundle). Note: Otherwise it is null.

    protected void onDestroy ()

    Since: API Level 1

    Perform any final cleanup before an activity is destroyed. This can happen either because the activity is finishing (someone called finish() on it, or because the system is temporarily destroying this instance of the activity to save space. You can distinguish between these two scenarios with the isFinishing() method.

    Note: do not count on this method being called as a place for saving data! For example, if an activity is editing data in a content provider, those edits should be committed in either onPause() or onSaveInstanceState(Bundle), not here. This method is usually implemented to free resources like threads that are associated with an activity, so that a destroyed activity does not leave such things around while the rest of its application is still running. There are situations where the system will simply kill the activity's hosting process without calling this method (or any others) in it, so it should not be used to do things that are intended to remain around after the process goes away.

    Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

    protected void onNewIntent (Intent intent)

    Since: API Level 1

    This is called for activities that set launchMode to "singleTop" in their package, or if a client used the FLAG_ACTIVITY_SINGLE_TOP flag when calling startActivity(Intent). In either case, when the activity is re-launched while at the top of the activity stack instead of a new instance of the activity being started, onNewIntent() will be called on the existing instance with the Intent that was used to re-launch it.

    An activity will always be paused before receiving a new intent, so you can count on onResume() being called after this method.

    Note that getIntent() still returns the original Intent. You can use setIntent(Intent) to update it to this new Intent.

    Parameters
    intent The new intent that was started for the activity.

    protected void onRestoreInstanceState (Bundle state)

    Since: API Level 1

    Ensures the list view has been created before Activity restores all of the view states.

    Parameters
    state the data most recently supplied in onSaveInstanceState(Bundle).

    protected void onSaveInstanceState (Bundle outState)

    Since: API Level 1

    Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundle populated by this method will be passed to both).

    This method is called before an activity may be killed so that when it comes back some time in the future it can restore its state. For example, if activity B is launched in front of activity A, and at some point activity A is killed to reclaim resources, activity A will have a chance to save the current state of its user interface via this method so that when the user returns to activity A, the state of the user interface can be restored via onCreate(Bundle) or onRestoreInstanceState(Bundle).

    Do not confuse this method with activity lifecycle callbacks such as onPause(), which is always called when an activity is being placed in the background or on its way to destruction, or onStop() which is called before destruction. One example of when onPause() and onStop() is called and not this method is when a user navigates back from activity B to activity A: there is no need to call onSaveInstanceState(Bundle) on B because that particular instance will never be restored, so the system avoids calling it. An example when onPause() is called and not onSaveInstanceState(Bundle) is when activity B is launched in front of activity A: the system may avoid calling onSaveInstanceState(Bundle) on activity A if it isn't killed during the lifetime of B since the state of the user interface of A will stay intact.

    The default implementation takes care of most of the UI per-instance state for you by calling onSaveInstanceState() on each view in the hierarchy that has an id, and by saving the id of the currently focused view (all of which is restored by the default implementation of onRestoreInstanceState(Bundle)). If you override this method to save additional information not captured by each individual view, you will likely want to call through to the default implementation, otherwise be prepared to save all of the state of each view yourself.

    If called, this method will occur before onStop(). There are no guarantees about whether it will occur before or after onPause().

    Parameters
    outState Bundle in which to place your saved state.

    protected void onStop ()

    Since: API Level 1

    Called when you are no longer visible to the user. You will next receive either onRestart(), onDestroy(), or nothing, depending on later user activity.

    Note that this method may never be called, in low memory situations where the system does not have enough memory to keep your activity's process running after its onPause() method is called.

    Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.