PreferenceScreen
public
final
class
PreferenceScreen
extends PreferenceGroup
implements
AdapterView.OnItemClickListener,
DialogInterface.OnDismissListener
java.lang.Object | |||
↳ | android.preference.Preference | ||
↳ | android.preference.PreferenceGroup | ||
↳ | android.preference.PreferenceScreen |
This class was deprecated
in API level 29.
Use the AndroidX
Preference Library for consistent behavior across all devices. For more information on
using the AndroidX Preference Library see
Settings.
Represents a top-level Preference
that
is the root of a Preference hierarchy. A PreferenceActivity
points to an instance of this class to show the preferences. To instantiate
this class, use PreferenceManager#createPreferenceScreen(Context)
.
-
This class can appear in two places:
- When a
PreferenceActivity
points to this, it is used as the root and is not shown (only the contained preferences are shown). - When it appears inside another preference hierarchy, it is shown and
serves as the gateway to another screen of preferences (either by showing
another screen of preferences as a
Dialog
or via aContext#startActivity(android.content.Intent)
from thePreference#getIntent()
). The children of thisPreferenceScreen
are NOT shown in the screen that thisPreferenceScreen
is shown in. Instead, a separate screen will be shown when this preference is clicked.
Here's an example XML layout of a PreferenceScreen:
<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android" android:key="first_preferencescreen"> <CheckBoxPreference android:key="wifi enabled" android:title="WiFi" /> <PreferenceScreen android:key="second_preferencescreen" android:title="WiFi settings"> <CheckBoxPreference android:key="prefer wifi" android:title="Prefer WiFi" /> ... other preferences here ... </PreferenceScreen> </PreferenceScreen>
In this example, the "first_preferencescreen" will be used as the root of the
hierarchy and given to a PreferenceActivity
. The first screen will
show preferences "WiFi" (which can be used to quickly enable/disable WiFi)
and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when
clicked will show another screen of preferences such as "Prefer WiFi" (and
the other preferences that are children of the "second_preferencescreen" tag).
Developer Guides
For information about building a settings UI with Preferences, read the Settings guide.
See also:
Summary
Inherited XML attributes | |
---|---|
Inherited constants |
---|
Public methods | |
---|---|
void
|
bind(ListView listView)
Binds a |
Dialog
|
getDialog()
Used to get a handle to the dialog. |
ListAdapter
|
getRootAdapter()
Returns an adapter that can be attached to a |
void
|
onDismiss(DialogInterface dialog)
This method will be invoked when the dialog is dismissed. |
void
|
onItemClick(AdapterView<T extends Adapter> parent, View view, int position, long id)
|
Protected methods | |
---|---|
boolean
|
isOnSameScreenAsChildren()
Whether this preference group should be shown on the same screen as its contained preferences. |
void
|
onClick()
Processes a click on the preference. |
ListAdapter
|
onCreateRootAdapter()
Creates the root adapter. |
void
|
onRestoreInstanceState(Parcelable state)
Hook allowing a Preference to re-apply a representation of its internal state that had
previously been generated by |
Parcelable
|
onSaveInstanceState()
Hook allowing a Preference to generate a representation of its internal state that can later be used to create a new instance with that same state. |
Inherited methods | |
---|---|
Public methods
bind
public void bind (ListView listView)
Binds a ListView
to the preferences contained in this PreferenceScreen
via
getRootAdapter()
. It also handles passing list item clicks to the corresponding
Preference
contained by this PreferenceScreen
.
Parameters | |
---|---|
listView |
ListView : The list view to attach to. |
getDialog
public Dialog getDialog ()
Used to get a handle to the dialog. This is useful for cases where we want to manipulate the dialog as we would with any other activity or view.
Returns | |
---|---|
Dialog |
getRootAdapter
public ListAdapter getRootAdapter ()
Returns an adapter that can be attached to a PreferenceActivity
or PreferenceFragment
to show the preferences contained in this
PreferenceScreen
.
This PreferenceScreen
will NOT appear in the returned adapter, instead
it appears in the hierarchy above this PreferenceScreen
.
This adapter's Adapter#getItem(int)
should always return a
subclass of Preference
.
Returns | |
---|---|
ListAdapter |
An adapter that provides the Preference contained in this
PreferenceScreen . |
onDismiss
public void onDismiss (DialogInterface dialog)
This method will be invoked when the dialog is dismissed.
Parameters | |
---|---|
dialog |
DialogInterface : the dialog that was dismissed will be passed into the
method |
onItemClick
public void onItemClick (AdapterView<T extends Adapter> parent, View view, int position, long id)
Parameters | |
---|---|
parent |
AdapterView |
view |
View |
position |
int |
id |
long |
Protected methods
isOnSameScreenAsChildren
protected boolean isOnSameScreenAsChildren ()
Whether this preference group should be shown on the same screen as its contained preferences.
Returns | |
---|---|
boolean |
True if the contained preferences should be shown on the same screen as this preference. |
onClick
protected void onClick ()
Processes a click on the preference. This includes saving the value to
the SharedPreferences
. However, the overridden method should
call callChangeListener(java.lang.Object)
to make sure the client wants to
update the preference's state with the new value.
onCreateRootAdapter
protected ListAdapter onCreateRootAdapter ()
Creates the root adapter.
Returns | |
---|---|
ListAdapter |
An adapter that contains the preferences contained in this PreferenceScreen . |
See also:
onRestoreInstanceState
protected void onRestoreInstanceState (Parcelable state)
Hook allowing a Preference to re-apply a representation of its internal state that had
previously been generated by onSaveInstanceState()
. This function will never be called
with a null
state.
Parameters | |
---|---|
state |
Parcelable : The saved state that had previously been returned by
onSaveInstanceState() . |
onSaveInstanceState
protected Parcelable onSaveInstanceState ()
Hook allowing a Preference to generate a representation of its internal state that can later be used to create a new instance with that same state. This state should only contain information that is not persistent or can be reconstructed later.
Returns | |
---|---|
Parcelable |
A Parcelable object containing the current dynamic state of this Preference, or
null if there is nothing interesting to save. The default implementation
returns null . |