lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey
added in version 24.1.0
belongs to Maven artifact com.android.support:preference-v7:28.0.0-alpha1

PreferenceScreen

public final class PreferenceScreen
extends PreferenceGroup

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


Represents a top-level Preference that is the root of a Preference hierarchy. A PreferenceFragmentCompat points to an instance of this class to show the preferences. To instantiate this class, use createPreferenceScreen(android.content.Context).

    This class can appear in two places:
  • When a PreferenceFragmentCompat 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 PreferenceFragment or PreferenceFragmentCompat. 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.support.v7.preference.PreferenceGroup
From class android.support.v7.preference.Preference

Inherited constants

From class android.support.v7.preference.Preference

Public methods

void setShouldUseGeneratedIds(boolean shouldUseGeneratedIds)

Set whether the adapter created for this screen should attempt to use the preference IDs generated by addPreference(Preference) as stable item IDs.

boolean shouldUseGeneratedIds()

See setShouldUseGeneratedIds(boolean)

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.

Inherited methods

From class android.support.v7.preference.PreferenceGroup
From class android.support.v7.preference.Preference
From class java.lang.Object
From interface java.lang.Comparable

Public methods

setShouldUseGeneratedIds

added in version 24.1.0
void setShouldUseGeneratedIds (boolean shouldUseGeneratedIds)

Set whether the adapter created for this screen should attempt to use the preference IDs generated by addPreference(Preference) as stable item IDs. Setting this to false can suppress unwanted animations if Preference objects are frequently removed from and re-added to their containing PreferenceGroup.

This method may only be called when the preference screen is not attached to the hierarchy.

Default value is true.

Parameters
shouldUseGeneratedIds boolean: true if the adapter should use the preference ID as a stable ID, or false to disable the use of stable IDs

shouldUseGeneratedIds

added in version 24.1.0
boolean shouldUseGeneratedIds ()

See setShouldUseGeneratedIds(boolean)

Returns
boolean true if the adapter should use the preference IDs generated by addPreference(Preference) as stable item IDs

Protected methods

isOnSameScreenAsChildren

added in version 24.1.0
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 version 24.1.0
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.