Android
android.preference
public abstract class

android.preference.PreferenceActivity

java.lang.Object
android.content.Context
android.content.ContextWrapper
android.view.ContextThemeWrapper
android.app.Activity ComponentCallbacks KeyEvent.Callback LayoutInflater.Factory View.OnCreateContextMenuListener Window.Callback
android.app.ListActivity
android.preference.PreferenceActivity

The PreferenceActivity activity shows a hierarchy of preferences 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).

  • Summary

    Constants inherited from class android.app.Activity
    Constants inherited from class android.content.Context
    Fields inherited from class android.app.ListActivity

    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  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.
    Methods inherited from class android.app.ListActivity
    Methods inherited from class android.app.Activity
    Methods inherited from class android.view.ContextThemeWrapper
    Methods inherited from class android.content.ContextWrapper
    Methods inherited from class android.content.Context
    Methods inherited from class java.lang.Object
    Methods inherited from interface android.content.ComponentCallbacks
    Methods inherited from interface android.view.KeyEvent.Callback
    Methods inherited from interface android.view.LayoutInflater.Factory
    Methods inherited from interface android.view.View.OnCreateContextMenuListener
    Methods inherited from interface android.view.Window.Callback

    Details

    Public Constructors

    public PreferenceActivity()

    Public Methods

    public void addPreferencesFromIntent(Intent intent)

    Adds preferences from activities that match the given Intent.

    Parameters

    intent The Intent to query activities.

    public void addPreferencesFromResource(int preferencesResId)

    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)

    Finds a Preference based on its key.

    Parameters

    key The key of the preference to retrieve.

    Returns

    public PreferenceManager getPreferenceManager()

    Returns the PreferenceManager used by this activity.

    Returns

    public PreferenceScreen getPreferenceScreen()

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

    Returns

    public void onContentChanged()

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

    public boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference)

    public void setPreferenceScreen(PreferenceScreen preferenceScreen)

    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)

    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)

    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 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). 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)

    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)

    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()

    Called when you are no longer visible to the user. You will next receive either onStart(), 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.

    Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48