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
fun bind(listView: ListView!): Unit

Deprecated: Deprecated in Java.

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
fun getDialog(): Dialog!

Deprecated: Deprecated in Java.

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
fun getRootAdapter(): ListAdapter!

Deprecated: Deprecated in Java.

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
fun onDismiss(dialog: DialogInterface!): Unit

Deprecated: Deprecated in Java.

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

onItemClick

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

Deprecated: Deprecated in Java.

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
protected fun isOnSameScreenAsChildren(): Boolean

Deprecated: Deprecated in Java.

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

onClick

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

Deprecated: Deprecated in Java.

onCreateRootAdapter

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

Deprecated: Deprecated in Java.

Creates the root adapter.

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

onRestoreInstanceState

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

Deprecated: Deprecated in Java.

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

onSaveInstanceState

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

Deprecated: Deprecated in Java.

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.