FileDocCategorySizeDatePackage
PreferenceScreen.javaAPI DocAndroid 5.1 API10179Thu Mar 12 22:22:10 GMT 2015android.preference

PreferenceScreen

public final class PreferenceScreen extends PreferenceGroup implements DialogInterface.OnDismissListener, AdapterView.OnItemClickListener
Represents a top-level {@link Preference} that is the root of a Preference hierarchy. A {@link PreferenceActivity} points to an instance of this class to show the preferences. To instantiate this class, use {@link PreferenceManager#createPreferenceScreen(Context)}.
    This class can appear in two places:
  • When a {@link 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 {@link Dialog} or via a {@link Context#startActivity(android.content.Intent)} from the {@link Preference#getIntent()}). The children of this {@link PreferenceScreen} are NOT shown in the screen that this {@link 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 {@link 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
PreferenceCategory

Fields Summary
private android.widget.ListAdapter
mRootAdapter
private android.app.Dialog
mDialog
private android.widget.ListView
mListView
Constructors Summary
public PreferenceScreen(android.content.Context context, android.util.AttributeSet attrs)
Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}.

hide-

        super(context, attrs, com.android.internal.R.attr.preferenceScreenStyle);
Methods Summary
public voidbind(android.widget.ListView listView)
Binds a {@link ListView} to the preferences contained in this {@link PreferenceScreen} via {@link #getRootAdapter()}. It also handles passing list item clicks to the corresponding {@link Preference} contained by this {@link PreferenceScreen}.

param
listView The list view to attach to.

        listView.setOnItemClickListener(this);
        listView.setAdapter(getRootAdapter());
        
        onAttachedToActivity();
public android.app.DialoggetDialog()
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.

        return mDialog;
public android.widget.ListAdaptergetRootAdapter()
Returns an adapter that can be attached to a {@link PreferenceActivity} or {@link PreferenceFragment} to show the preferences contained in this {@link PreferenceScreen}.

This {@link PreferenceScreen} will NOT appear in the returned adapter, instead it appears in the hierarchy above this {@link PreferenceScreen}.

This adapter's {@link Adapter#getItem(int)} should always return a subclass of {@link Preference}.

return
An adapter that provides the {@link Preference} contained in this {@link PreferenceScreen}.

        if (mRootAdapter == null) {
            mRootAdapter = onCreateRootAdapter();
        }
        
        return mRootAdapter;
protected booleanisOnSameScreenAsChildren()

        return false;
protected voidonClick()

        if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
            return;
        }
        
        showDialog(null);
protected android.widget.ListAdapteronCreateRootAdapter()
Creates the root adapter.

return
An adapter that contains the preferences contained in this {@link PreferenceScreen}.
see
#getRootAdapter()

        return new PreferenceGroupAdapter(this);
public voidonDismiss(android.content.DialogInterface dialog)

        mDialog = null;
        getPreferenceManager().removePreferencesScreen(dialog);
public voidonItemClick(android.widget.AdapterView parent, android.view.View view, int position, long id)

        // If the list has headers, subtract them from the index.
        if (parent instanceof ListView) {
            position -= ((ListView) parent).getHeaderViewsCount();
        }
        Object item = getRootAdapter().getItem(position);
        if (!(item instanceof Preference)) return;

        final Preference preference = (Preference) item; 
        preference.performClick(this);
protected voidonRestoreInstanceState(android.os.Parcelable state)

        if (state == null || !state.getClass().equals(SavedState.class)) {
            // Didn't save state for us in onSaveInstanceState
            super.onRestoreInstanceState(state);
            return;
        }
         
        SavedState myState = (SavedState) state;
        super.onRestoreInstanceState(myState.getSuperState());
        if (myState.isDialogShowing) {
            showDialog(myState.dialogBundle);
        }
protected android.os.ParcelableonSaveInstanceState()

        final Parcelable superState = super.onSaveInstanceState();
        final Dialog dialog = mDialog;
        if (dialog == null || !dialog.isShowing()) {
            return superState;
        }
        
        final SavedState myState = new SavedState(superState);
        myState.isDialogShowing = true;
        myState.dialogBundle = dialog.onSaveInstanceState();
        return myState;
private voidshowDialog(android.os.Bundle state)

        Context context = getContext();
        if (mListView != null) {
            mListView.setAdapter(null);
        }

        LayoutInflater inflater = (LayoutInflater)
                context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        View childPrefScreen = inflater.inflate(
                com.android.internal.R.layout.preference_list_fragment, null);
        mListView = (ListView) childPrefScreen.findViewById(android.R.id.list);
        bind(mListView);

        // Set the title bar if title is available, else no title bar
        final CharSequence title = getTitle();
        Dialog dialog = mDialog = new Dialog(context, context.getThemeResId());
        if (TextUtils.isEmpty(title)) {
            dialog.getWindow().requestFeature(Window.FEATURE_NO_TITLE);
        } else {
            dialog.setTitle(title);
        }
        dialog.setContentView(childPrefScreen);
        dialog.setOnDismissListener(this);
        if (state != null) {
            dialog.onRestoreInstanceState(state);
        }

        // Add the screen to the list of preferences screens opened as dialogs
        getPreferenceManager().addPreferencesScreen(dialog);
        
        dialog.show();