Google is committed to advancing racial equity for Black communities. See how.
Added in API level 1
Deprecated in API level 29

PreferenceScreen

class PreferenceScreen : PreferenceGroup, AdapterView.OnItemClickListener, DialogInterface.OnDismissListener
kotlin.Any
   ↳ 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 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 a Context#startActivity(android.content.Intent) from the Preference#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).

Summary

Inherited XML attributes

Inherited constants

Public methods

Unit
bind(listView: ListView!)

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

Dialog!

Used to get a handle to the dialog.

ListAdapter!

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

Unit

Unit
onItemClick(parent: AdapterView<Adapter!>!, view: View!, position: Int, id: Long)

Protected methods

Boolean

Unit

ListAdapter!

Creates the root adapter.

Unit

Parcelable!

Inherited functions

Public methods

bind

Added in API level 1
Deprecated in API level 29
fun bind(listView: ListView!): Unit

Deprecated.

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
Deprecated in API level 29
fun getDialog(): Dialog!

Deprecated.

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.

getRootAdapter

Added in API level 1
Deprecated in API level 29
fun getRootAdapter(): ListAdapter!

Deprecated.

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.

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

onDismiss

Added in API level 1
Deprecated in API level 29
fun onDismiss(dialog: DialogInterface!): Unit

Deprecated.

Parameters
dialog DialogInterface!: the dialog that was dismissed will be passed into the method

onItemClick

Added in API level 1
Deprecated in API level 29
fun onItemClick(
    parent: AdapterView<Adapter!>!,
    view: View!,
    position: Int,
    id: Long
): Unit

Deprecated.

Parameters
parent AdapterView<Adapter!>!: The AdapterView where the click happened.
view View!: The view within the AdapterView that was clicked (this will be a view provided by the adapter)
position Int: The position of the view in the adapter.
id Long: The row id of the item that was clicked.

Protected methods

isOnSameScreenAsChildren

Added in API level 1
Deprecated in API level 29
protected fun isOnSameScreenAsChildren(): Boolean

Deprecated.

Return
Boolean True if the contained preferences should be shown on the same screen as this preference.

onClick

Added in API level 1
Deprecated in API level 29
protected fun onClick(): Unit

Deprecated.

onCreateRootAdapter

Added in API level 1
Deprecated in API level 29
protected fun onCreateRootAdapter(): ListAdapter!

Deprecated.

Creates the root adapter.

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

onRestoreInstanceState

Added in API level 1
Deprecated in API level 29
protected fun onRestoreInstanceState(state: Parcelable!): Unit

Deprecated.

Parameters
state Parcelable!: The saved state that had previously been returned by onSaveInstanceState.

onSaveInstanceState

Added in API level 1
Deprecated in API level 29
protected fun onSaveInstanceState(): Parcelable!

Deprecated.

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