android.preference
Class PreferenceActivity

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

All Implemented Interfaces:

ComponentCallbacks, PreferenceManager.OnPreferenceTreeClickListener, KeyEvent.Callback, LayoutInflater.Factory, View.OnCreateContextMenuListener, Window.Callback

public abstract class PreferenceActivity
extends ListActivity
implements PreferenceManager.OnPreferenceTreeClickListener

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 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 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(android.content.Intent). Each Activity can specify meta-data in the manifest (via the key 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 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:

Preference, PreferenceScreen

Field Summary

Fields inherited from class android.app.ListActivity

mAdapter, mList

Fields inherited from class android.app.Activity

DEFAULT_KEYS_DIALER, DEFAULT_KEYS_DISABLE, DEFAULT_KEYS_SEARCH_GLOBAL, DEFAULT_KEYS_SEARCH_LOCAL, DEFAULT_KEYS_SHORTCUT, FOCUSED_STATE_SET, RESULT_CANCELED, RESULT_FIRST_USER, RESULT_OK

Fields inherited from class android.content.Context

ACTIVITY_SERVICE, ALARM_SERVICE, AUDIO_SERVICE, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BLUETOOTH_SERVICE, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, KEYGUARD_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MODE_APPEND, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NOTIFICATION_SERVICE, POWER_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, STATUS_BAR_SERVICE, TELEPHONY_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_SERVICE, WINDOW_SERVICE

Constructor Summary

PreferenceActivity()

Method Summary

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.
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.
void	onContentChanged() Updates the screen state (current list and other views) when the content changes.
protected void	onCreate(Bundle savedInstanceState) Called when the activity is starting.
protected void	onDestroy() Perform any final cleanup before an activity is destroyed.
protected void	onNewIntent(Intent intent) This is called for activities that set launchMode to "singleTop" in their package, or if a client used the Intent.FLAG_ACTIVITY_SINGLE_TOP flag when calling Activity.startActivity(android.content.Intent).
boolean	onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference) Called when a preference in the tree rooted at this PreferenceScreen has been clicked.
protected void	onRestoreInstanceState(Bundle state) Ensures the list view has been created before Activity restores all of the view states.
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 Activity.onCreate(android.os.Bundle) or Activity.onRestoreInstanceState(android.os.Bundle) (the Bundle populated by this method will be passed to both).
protected void	onStop() Called when you are no longer visible to the user.
void	setPreferenceScreen(PreferenceScreen preferenceScreen) Sets the root of the preference hierarchy that this activity is showing.

Methods inherited from class android.app.ListActivity

getListAdapter, getListView, getSelectedItemId, getSelectedItemPosition, onListItemClick, setListAdapter, setSelection

Methods inherited from class android.app.Activity

addContentView, closeOptionsMenu, createPendingResult, dismissDialog, dispatchKeyEvent, dispatchTouchEvent, dispatchTrackballEvent, finalize, findViewById, finish, finishActivity, finishActivityFromChild, finishFromChild, getApplication, getCallingActivity, getCallingPackage, getChangingConfigurations, getComponentName, getCurrentFocus, getInstanceCount, getIntent, getLastNonConfigurationInstance, getLayoutInflater, getLocalClassName, getMenuInflater, getParent, getPreferences, getRequestedOrientation, getSystemService, getTaskId, getTitle, getTitleColor, getVolumeControlStream, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, getWindow, getWindowManager, isChild, isFinishing, isTaskRoot, managedCommitUpdates, managedQuery, managedQuery, moveTaskToBack, onApplyThemeResource, onChildTitleChanged, onConfigurationChanged, onContextItemSelected, onContextMenuClosed, onCreateContextMenu, onCreateDescription, onCreateDialog, onCreateOptionsMenu, onCreatePanelMenu, onCreatePanelView, onCreateThumbnail, onCreateView, onKeyDown, onKeyMultiple, onKeyUp, onLowMemory, onMenuItemSelected, onMenuOpened, onOptionsItemSelected, onOptionsMenuClosed, onPanelClosed, onPause, onPostCreate, onPostResume, onPrepareDialog, onPrepareOptionsMenu, onPreparePanel, onRestart, onResume, onRetainNonConfigurationInstance, onSearchRequested, onStart, onTitleChanged, onTouchEvent, onTrackballEvent, onWindowAttributesChanged, onWindowFocusChanged, openContextMenu, openOptionsMenu, registerForContextMenu, removeDialog, requestWindowFeature, runOnUiThread, setContentView, setContentView, setContentView, setDefaultKeyMode, setFeatureDrawable, setFeatureDrawableAlpha, setFeatureDrawableResource, setFeatureDrawableUri, setIntent, setPersistent, setProgress, setProgressBarIndeterminate, setProgressBarIndeterminateVisibility, setProgressBarVisibility, setRequestedOrientation, setResult, setResult, setSecondaryProgress, setTitle, setTitle, setTitleColor, setVolumeControlStream, showDialog, startActivity, startActivityForResult, startActivityFromChild, startActivityIfNeeded, startManagingCursor, startNextMatchingActivity, startSearch, stopManagingCursor, takeKeyEvents, unregisterForContextMenu

Methods inherited from class android.view.ContextThemeWrapper

attachBaseContext, getTheme, setTheme

Methods inherited from class android.content.ContextWrapper

bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkUriPermission, checkUriPermission, clearWallpaper, createPackageContext, databaseList, deleteDatabase, deleteFile, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getAssets, getBaseContext, getCacheDir, getClassLoader, getContentResolver, getDatabasePath, getDir, getFilesDir, getFileStreamPath, getMainLooper, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getWallpaper, grantUriPermission, openFileInput, openFileOutput, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, revokeUriPermission, sendBroadcast, sendBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendStickyBroadcast, setWallpaper, setWallpaper, startInstrumentation, startService, stopService, unbindService, unregisterReceiver

Methods inherited from class android.content.Context

getString, getString, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PreferenceActivity

public PreferenceActivity()

Method Detail

onCreate

protected void onCreate(Bundle savedInstanceState)

Description copied from class: Activity

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

You can call Activity.finish() from within this function, in which case onDestroy() will be immediately called without any of the rest of the activity lifecycle (Activity.onStart(), Activity.onResume(), Activity.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.

Overrides:

onCreate in class Activity

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 Activity.onSaveInstanceState(android.os.Bundle). Note: Otherwise it is null.

See Also:

Activity.onStart(), Activity.onSaveInstanceState(android.os.Bundle), Activity.onRestoreInstanceState(android.os.Bundle), Activity.onPostCreate(android.os.Bundle)

onStop

protected void onStop()

Description copied from class: Activity

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

Overrides:

onStop in class Activity

See Also:

Activity.onRestart(), Activity.onResume(), Activity.onSaveInstanceState(android.os.Bundle), Activity.onDestroy()

onDestroy

protected void onDestroy()

Description copied from class: Activity

Perform any final cleanup before an activity is destroyed. This can happen either because the activity is finishing (someone called Activity.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 Activity.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 Activity.onPause() or Activity.onSaveInstanceState(android.os.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.

Overrides:

onDestroy in class Activity

See Also:

Activity.onPause(), Activity.onStop(), Activity.finish(), Activity.isFinishing()

onSaveInstanceState

protected void onSaveInstanceState(Bundle outState)

Description copied from class: Activity

Called to retrieve per-instance state from an activity before being killed so that the state can be restored in Activity.onCreate(android.os.Bundle) or Activity.onRestoreInstanceState(android.os.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 Activity.onCreate(android.os.Bundle) or Activity.onRestoreInstanceState(android.os.Bundle).

Do not confuse this method with activity lifecycle callbacks such as Activity.onPause(), which is always called when an activity is being placed in the background or on its way to destruction, or Activity.onStop() which is called before destruction. One example of when Activity.onPause() and Activity.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 Activity.onSaveInstanceState(android.os.Bundle) on B because that particular instance will never be restored, so the system avoids calling it. An example when Activity.onPause() is called and not Activity.onSaveInstanceState(android.os.Bundle) is when activity B is launched in front of activity A: the system may avoid calling Activity.onSaveInstanceState(android.os.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 View.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 Activity.onRestoreInstanceState(android.os.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 Activity.onStop(). There are no guarantees about whether it will occur before or after Activity.onPause().

Overrides:

onSaveInstanceState in class Activity

Parameters:

outState - Bundle in which to place your saved state.

See Also:

Activity.onCreate(android.os.Bundle), Activity.onRestoreInstanceState(android.os.Bundle), Activity.onPause()

onRestoreInstanceState

protected void onRestoreInstanceState(Bundle state)

Description copied from class: ListActivity

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

Overrides:

onRestoreInstanceState in class ListActivity

Parameters:

state - the data most recently supplied in Activity.onSaveInstanceState(android.os.Bundle).

See Also:

Activity.onRestoreInstanceState(Bundle)

onActivityResult

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

Description copied from class: Activity

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

Overrides:

onActivityResult in class Activity

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

See Also:

Activity.startActivityForResult(android.content.Intent, int), Activity.createPendingResult(int, android.content.Intent, int), Activity.setResult(int)

onContentChanged

public void onContentChanged()

Description copied from class: ListActivity

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

Specified by:

onContentChanged in interface Window.Callback

Overrides:

onContentChanged in class ListActivity

See Also:

Activity.onContentChanged()

getPreferenceManager

public PreferenceManager getPreferenceManager()

Returns the PreferenceManager used by this activity.

Returns:

The PreferenceManager.

setPreferenceScreen

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.

getPreferenceScreen

public PreferenceScreen getPreferenceScreen()

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

Returns:

The PreferenceScreen that is the root of the preference hierarchy.

addPreferencesFromIntent

public void addPreferencesFromIntent(Intent intent)

Adds preferences from activities that match the given Intent.

Parameters:

intent - The Intent to query activities.

addPreferencesFromResource

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.

onPreferenceTreeClick

public boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen,
                                     Preference preference)

Called when a preference in the tree rooted at this PreferenceScreen has been clicked.

Specified by:

onPreferenceTreeClick in interface PreferenceManager.OnPreferenceTreeClickListener

Parameters:

preferenceScreen - The PreferenceScreen that the preference is located in.

preference - The preference that was clicked.

Returns:

Whether the click was handled.

findPreference

public Preference findPreference(CharSequence key)

Finds a Preference based on its key.

Parameters:

key - The key of the preference to retrieve.

Returns:

The Preference with the key, or null.

See Also:

PreferenceGroup.findPreference(CharSequence)

onNewIntent

protected void onNewIntent(Intent intent)

Description copied from class: Activity

This is called for activities that set launchMode to "singleTop" in their package, or if a client used the Intent.FLAG_ACTIVITY_SINGLE_TOP flag when calling Activity.startActivity(android.content.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 Activity.onResume() being called after this method.

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

Overrides:

onNewIntent in class Activity

Parameters:

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

See Also:

Activity.getIntent(), Activity.setIntent(android.content.Intent), Activity.onResume()