FileDocCategorySizeDatePackage
PreferenceScreen.javaAPI DocAndroid 1.5 API8940Wed May 06 22:41:56 BST 2009android.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).

see
PreferenceCategory

Fields Summary
private android.widget.ListAdapter
mRootAdapter
private android.app.Dialog
mDialog
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} 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 || 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)

        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();
        ListView listView = new ListView(context);
        bind(listView);

        Dialog dialog = mDialog = new Dialog(context, com.android.internal.R.style.Theme_NoTitleBar);
        dialog.setContentView(listView);
        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();