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:
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).
PreferenceActivity() |
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. |
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. |
preferencesResId | The XML resource ID to inflate. |
---|
key | The key of the preference to retrieve. |
---|
preferenceScreen | The root PreferenceScreen of the preference hierarchy. |
---|
You will receive this call immediately before onResume() when your activity is re-starting.
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"). |
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.
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. |
---|
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.
intent | The new intent that was started for the activity. |
---|
state | the data most recently supplied in onSaveInstanceState(Bundle). |
---|
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().
outState | Bundle in which to place your saved state. |
---|
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:56 |