This is the base class for an activity to show a hierarchy of preferences
to the user. Prior to HONEYCOMB
this class only allowed the display of a single set of preference; this
functionality should now be found in the new PreferenceFragment
class. If you are using PreferenceActivity in its old mode, the documentation
there applies to the deprecated APIs here.

This activity shows one or more headers of preferences, each of which
is associated with a PreferenceFragment to display the preferences
of that header. The actual layout and display of these associations can
however vary; currently there are two major approaches it may take:

On a small screen it may display only the headers as a single list when first launched.
Selecting one of the header items will only show the PreferenceFragment of that header (on
Android N and lower a new Activity is launched).

On a large screen in may display both the headers and current PreferenceFragment together as
panes. Selecting a header item switches to showing the correct PreferenceFragment for that item.

Subclasses of PreferenceActivity should implement
onBuildHeaders(List) to populate the header list with the desired
items. Doing this implicitly switches the class into its new "headers
+ fragments" mode rather than the old style of just showing a single
preferences list.

Developer Guides

For information about using PreferenceActivity,
read the Settings
guide.

Sample Code

The following sample code shows a simple preference activity that
has two different sets of preferences. The implementation, consisting
of the activity itself as well as its two preference fragments is:

Note that this XML resource contains a preference screen holding another
fragment, the Prefs1FragmentInner implemented here. This allows the user
to traverse down a hierarchy of preferences; pressing back will pop each
fragment off the stack to return to the previous preferences.

When starting this activity and using EXTRA_SHOW_FRAGMENT,
this extra can also be specified to supply a Bundle of arguments to pass
to that fragment when it is instantiated during the initial creation
of PreferenceActivity.

Flag for bindService(Intent, ServiceConnection, int): If binding from an activity, allow the
target service's process importance to be raised based on whether the
activity is visible to the user, regardless whether another flag is
used to reduce the amount that the client process's overall importance
is used to impact it.

This constant was deprecated
in API level 23.
MODE_MULTI_PROCESS does not work reliably in
some versions of Android, and furthermore does not provide any
mechanism for reconciling concurrent modifications across
processes. Applications should not attempt to use it. Instead,
they should use an explicit cross-process data management
approach such as ContentProvider.

This constant was deprecated
in API level 17.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

This constant was deprecated
in API level 17.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly
discouraged; instead, applications should use more formal
mechanism for interactions such as ContentProvider,
BroadcastReceiver, and Service.
There are no guarantees that this access mode will remain on
a file, such as when it goes through a backup and restore.

Level for onTrimMemory(int): the process is around the middle
of the background LRU list; freeing memory can help the system keep
other processes running later in the list for better overall performance.

Level for onTrimMemory(int): the process is not an expendable
background process, but the device is running extremely low on memory
and is about to not be able to keep any background processes running.

If this activity is being destroyed because it can not handle a
configuration parameter being changed (and thus its
onConfigurationChanged(Configuration) method is
not being called), then you can use this method to discover
the set of changes that have occurred while in the process of being
destroyed.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 23.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

Constants

EXTRA_NO_HEADERS

When starting this activity, the invoking Intent can contain this extra
boolean that the header list should not be displayed. This is most often
used in conjunction with EXTRA_SHOW_FRAGMENT to launch
the activity to display a specific fragment that the user has navigated
to.

EXTRA_SHOW_FRAGMENT_ARGUMENTS

When starting this activity and using EXTRA_SHOW_FRAGMENT,
this extra can also be specified to supply a Bundle of arguments to pass
to that fragment when it is instantiated during the initial creation
of PreferenceActivity.

onBuildHeaders

Called when the activity needs its list of headers build. By
implementing this and adding at least one item to the list, you
will cause the activity to run in its modern fragment mode. Note
that this function may not always be called; for example, if the
activity has been asked to display a particular fragment without
the header list, there is no need to build the headers.

onBuildStartFragmentIntent

Called by startWithFragment(String, Bundle, Fragment, int, int, int) when
in single-pane mode, to build an Intent to launch a new activity showing
the selected fragment. The default implementation constructs an Intent
that re-launches the current activity with the appropriate arguments to
display the fragment.

onGetInitialHeader

Called to determine the initial header to be shown. The default
implementation simply returns the fragment of the first header. Note
that the returned Header object does not actually need to exist in
your header list -- whatever its fragment is will simply be used to
show for the initial UI.

onGetNewHeader

Called after the header list has been updated (onBuildHeaders(List)
has been called and returned due to invalidateHeaders()) to
specify the header that should now be selected. The default implementation
returns null to keep whatever header is currently selected.

onIsHidingHeaders

Called to determine whether the header list should be hidden.
The default implementation returns the
value given in EXTRA_NO_HEADERS or false if it is not supplied.
This is set to false, for example, when the activity is being re-launched
to show a particular preference activity.

onOptionsItemSelected

This hook is called whenever an item in your options menu is selected.
The default implementation simply returns false to have the normal
processing happen (calling the item's Runnable or sending a message to
its Handler as appropriate). You can use this method for any items
for which you would like to do processing without those other
facilities.

Derived classes should call through to the base class for it to
perform the default menu handling.

startPreferencePanel

Start a new fragment containing a preference panel. If the preferences
are being displayed in multi-pane mode, the given fragment class will
be instantiated and placed in the appropriate pane. If running in
single-pane mode, a new activity will be launched in which to show the
fragment.

Parameters

fragmentClass

String: Full name of the class implementing the fragment.

args

Bundle: Any desired arguments to supply to the fragment.

titleRes

int: Optional resource identifier of the title of this
fragment.

titleText

CharSequence: Optional text of the title of this fragment.

resultTo

Fragment: Optional fragment that result data should be sent to.
If non-null, resultTo.onActivityResult() will be called when this
preference panel is done. The launched panel must use
finishPreferencePanel(Fragment, int, Intent) when done.

resultRequestCode

int: If resultTo is non-null, this is the caller's
request code to be received with the result.

startWithFragment

Start a new instance of this activity, showing only the given
preference fragment. When launched in this mode, the header list
will be hidden and the given preference fragment will be instantiated
and fill the entire activity.

Parameters

fragmentName

String: The name of the fragment to display.

args

Bundle: Optional arguments to supply to the fragment.

resultTo

Fragment: Option fragment that should receive the result of
the activity launch.

resultRequestCode

int: If resultTo is non-null, this is the request
code in which to report the result.

titleRes

int: Resource ID of string to display for the title of
this set of preferences.

shortTitleRes

int: Resource ID of string to display for the short title of
this set of preferences.

Protected methods

isValidFragment

Subclasses should override this method and verify that the given fragment is a valid type
to be attached to this activity. The default implementation returns true for
apps built for android:targetSdkVersion older than
KITKAT. For later versions, it will throw an exception.

Parameters

fragmentName

String: the class name of the Fragment about to be attached to this activity.

Returns

boolean

true if the fragment class name is valid for this Activity and false otherwise.

onActivityResult

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.

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

Bundle: 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.

onDestroy

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.

onListItemClick

This method will be called when an item in the list is selected.
Subclasses should override. Subclasses can call
getListView().getItemAtPosition(position) if they need to access the
data associated with the selected item.

Parameters

l

ListView: The ListView where the click happened

v

View: The view that was clicked within the ListView

position

int: The position of the view in the list

id

long: The row id of the item that was clicked

onNewIntent

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.

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