Build 1.0_r1(from source)

android.preference
Class PreferenceActivity

java.lang.Object
  extended by android.content.Context
      extended by android.content.ContextWrapper
          extended by android.view.ContextThemeWrapper
              extended by android.app.Activity
                  extended by android.app.ListActivity
                      extended by 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()

    Build 1.0_r1(from source)

    Please submit a feedback, bug or feature