Skip to content

Most visited

Recently visited

navigation

PreferenceScreen

public final class PreferenceScreen
extends PreferenceGroup implements AdapterView.OnItemClickListener, DialogInterface.OnDismissListener

java.lang.Object
   ↳ android.preference.Preference
     ↳ android.preference.PreferenceGroup
       ↳ android.preference.PreferenceScreen


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 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 a startActivity(android.content.Intent) from the getIntent()). The children of this PreferenceScreen are NOT shown in the screen that this PreferenceScreen 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

From class android.preference.PreferenceGroup
From class android.preference.Preference

Inherited constants

From class android.preference.Preference

Public methods

void bind(ListView listView)

Binds a ListView to the preferences contained in this PreferenceScreen via getRootAdapter().

Dialog getDialog()

Used to get a handle to the dialog.

ListAdapter getRootAdapter()

Returns an adapter that can be attached to a PreferenceActivity or PreferenceFragment to show the preferences contained in this PreferenceScreen.

void onDismiss(DialogInterface dialog)

This method will be invoked when the dialog is dismissed.

void onItemClick(AdapterView 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 onSaveInstanceState().

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

From class android.preference.PreferenceGroup
From class android.preference.Preference
From class java.lang.Object
From interface java.lang.Comparable
From interface android.widget.AdapterView.OnItemClickListener
From interface android.content.DialogInterface.OnDismissListener

Public methods

bind

Added in API level 1
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

Added in API level 1
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

Added in API level 1
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 getItem(int) should always return a subclass of Preference.

Returns
ListAdapter An adapter that provides the Preference contained in this PreferenceScreen.

onDismiss

Added in API level 1
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

Added in API level 1
void onItemClick (AdapterView parent, 
                View view, 
                int position, 
                long id)

Parameters
parent AdapterView
view View
position int
id long

Protected methods

isOnSameScreenAsChildren

Added in API level 1
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

Added in API level 1
void onClick ()

Processes a click on the preference. This includes saving the value to the SharedPreferences. However, the overridden method should call callChangeListener(Object) to make sure the client wants to update the preference's state with the new value.

onCreateRootAdapter

Added in API level 1
ListAdapter onCreateRootAdapter ()

Creates the root adapter.

Returns
ListAdapter An adapter that contains the preferences contained in this PreferenceScreen.

See also:

onRestoreInstanceState

Added in API level 1
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

Added in API level 1
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.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.