Home | History | Annotate | Download | only in preference 
      1 /*
      2  * Copyright (C) 2007 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.preference;
     18 
     19 import android.app.Dialog;
     20 import android.content.Context;
     21 import android.content.DialogInterface;
     22 import android.content.res.TypedArray;
     23 import android.graphics.drawable.Drawable;
     24 import android.os.Bundle;
     25 import android.os.Parcel;
     26 import android.os.Parcelable;
     27 import android.text.TextUtils;
     28 import android.util.AttributeSet;
     29 import android.view.LayoutInflater;
     30 import android.view.View;
     31 import android.view.Window;
     32 import android.widget.Adapter;
     33 import android.widget.AdapterView;
     34 import android.widget.ListAdapter;
     35 import android.widget.ListView;
     36 import android.widget.TextView;
     37 
     38 /**
     39  * Represents a top-level {@link Preference} that
     40  * is the root of a Preference hierarchy. A {@link PreferenceActivity}
     41  * points to an instance of this class to show the preferences. To instantiate
     42  * this class, use {@link PreferenceManager#createPreferenceScreen(Context)}.
     43  * <ul>
     44  * This class can appear in two places:
     45  * <li> When a {@link PreferenceActivity} points to this, it is used as the root
     46  * and is not shown (only the contained preferences are shown).
     47  * <li> When it appears inside another preference hierarchy, it is shown and
     48  * serves as the gateway to another screen of preferences (either by showing
     49  * another screen of preferences as a {@link Dialog} or via a
     50  * {@link Context#startActivity(android.content.Intent)} from the
     51  * {@link Preference#getIntent()}). The children of this {@link PreferenceScreen}
     52  * are NOT shown in the screen that this {@link PreferenceScreen} is shown in.
     53  * Instead, a separate screen will be shown when this preference is clicked.
     54  * </ul>
     55  * <p>Here's an example XML layout of a PreferenceScreen:</p>
     56  * <pre>
     57 &lt;PreferenceScreen
     58         xmlns:android="http://schemas.android.com/apk/res/android"
     59         android:key="first_preferencescreen"&gt;
     60     &lt;CheckBoxPreference
     61             android:key="wifi enabled"
     62             android:title="WiFi" /&gt;
     63     &lt;PreferenceScreen
     64             android:key="second_preferencescreen"
     65             android:title="WiFi settings"&gt;
     66         &lt;CheckBoxPreference
     67                 android:key="prefer wifi"
     68                 android:title="Prefer WiFi" /&gt;
     69         ... other preferences here ...
     70     &lt;/PreferenceScreen&gt;
     71 &lt;/PreferenceScreen&gt; </pre>
     72  * <p>
     73  * In this example, the "first_preferencescreen" will be used as the root of the
     74  * hierarchy and given to a {@link PreferenceActivity}. The first screen will
     75  * show preferences "WiFi" (which can be used to quickly enable/disable WiFi)
     76  * and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when
     77  * clicked will show another screen of preferences such as "Prefer WiFi" (and
     78  * the other preferences that are children of the "second_preferencescreen" tag).
     79  *
     80  * <div class="special reference">
     81  * <h3>Developer Guides</h3>
     82  * <p>For information about building a settings UI with Preferences,
     83  * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
     84  * guide.</p>
     85  * </div>
     86  *
     87  * @see PreferenceCategory
     88  */
     89 public final class PreferenceScreen extends PreferenceGroup implements AdapterView.OnItemClickListener,
     90         DialogInterface.OnDismissListener {
     91 
     92     private ListAdapter mRootAdapter;
     93 
     94     private Dialog mDialog;
     95 
     96     private ListView mListView;
     97 
     98     private int mLayoutResId = com.android.internal.R.layout.preference_list_fragment;
     99     private Drawable mDividerDrawable;
    100     private boolean mDividerSpecified;
    101 
    102     /**
    103      * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}.
    104      * @hide-
    105      */
    106     public PreferenceScreen(Context context, AttributeSet attrs) {
    107         super(context, attrs, com.android.internal.R.attr.preferenceScreenStyle);
    108 
    109         TypedArray a = context.obtainStyledAttributes(null,
    110                 com.android.internal.R.styleable.PreferenceScreen,
    111                 com.android.internal.R.attr.preferenceScreenStyle,
    112                 0);
    113 
    114         mLayoutResId = a.getResourceId(
    115                 com.android.internal.R.styleable.PreferenceScreen_screenLayout,
    116                 mLayoutResId);
    117         if (a.hasValueOrEmpty(com.android.internal.R.styleable.PreferenceScreen_divider)) {
    118             mDividerDrawable =
    119                     a.getDrawable(com.android.internal.R.styleable.PreferenceScreen_divider);
    120             mDividerSpecified = true;
    121         }
    122 
    123         a.recycle();
    124     }
    125 
    126     /**
    127      * Returns an adapter that can be attached to a {@link PreferenceActivity}
    128      * or {@link PreferenceFragment} to show the preferences contained in this
    129      * {@link PreferenceScreen}.
    130      * <p>
    131      * This {@link PreferenceScreen} will NOT appear in the returned adapter, instead
    132      * it appears in the hierarchy above this {@link PreferenceScreen}.
    133      * <p>
    134      * This adapter's {@link Adapter#getItem(int)} should always return a
    135      * subclass of {@link Preference}.
    136      *
    137      * @return An adapter that provides the {@link Preference} contained in this
    138      *         {@link PreferenceScreen}.
    139      */
    140     public ListAdapter getRootAdapter() {
    141         if (mRootAdapter == null) {
    142             mRootAdapter = onCreateRootAdapter();
    143         }
    144 
    145         return mRootAdapter;
    146     }
    147 
    148     /**
    149      * Creates the root adapter.
    150      *
    151      * @return An adapter that contains the preferences contained in this {@link PreferenceScreen}.
    152      * @see #getRootAdapter()
    153      */
    154     protected ListAdapter onCreateRootAdapter() {
    155         return new PreferenceGroupAdapter(this);
    156     }
    157 
    158     /**
    159      * Binds a {@link ListView} to the preferences contained in this {@link PreferenceScreen} via
    160      * {@link #getRootAdapter()}. It also handles passing list item clicks to the corresponding
    161      * {@link Preference} contained by this {@link PreferenceScreen}.
    162      *
    163      * @param listView The list view to attach to.
    164      */
    165     public void bind(ListView listView) {
    166         listView.setOnItemClickListener(this);
    167         listView.setAdapter(getRootAdapter());
    168 
    169         onAttachedToActivity();
    170     }
    171 
    172     @Override
    173     protected void onClick() {
    174         if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
    175             return;
    176         }
    177 
    178         showDialog(null);
    179     }
    180 
    181     private void showDialog(Bundle state) {
    182         Context context = getContext();
    183         if (mListView != null) {
    184             mListView.setAdapter(null);
    185         }
    186 
    187         LayoutInflater inflater = (LayoutInflater)
    188                 context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    189         View childPrefScreen = inflater.inflate(mLayoutResId, null);
    190         View titleView = childPrefScreen.findViewById(android.R.id.title);
    191         mListView = (ListView) childPrefScreen.findViewById(android.R.id.list);
    192         if (mDividerSpecified) {
    193             mListView.setDivider(mDividerDrawable);
    194         }
    195 
    196         bind(mListView);
    197 
    198         // Set the title bar if title is available, else no title bar
    199         final CharSequence title = getTitle();
    200         Dialog dialog = mDialog = new Dialog(context, context.getThemeResId());
    201         if (TextUtils.isEmpty(title)) {
    202             if (titleView != null) {
    203                 titleView.setVisibility(View.GONE);
    204             }
    205             dialog.getWindow().requestFeature(Window.FEATURE_NO_TITLE);
    206         } else {
    207             if (titleView instanceof TextView) {
    208                 ((TextView) titleView).setText(title);
    209                 titleView.setVisibility(View.VISIBLE);
    210             } else {
    211                 dialog.setTitle(title);
    212             }
    213         }
    214         dialog.setContentView(childPrefScreen);
    215         dialog.setOnDismissListener(this);
    216         if (state != null) {
    217             dialog.onRestoreInstanceState(state);
    218         }
    219 
    220         // Add the screen to the list of preferences screens opened as dialogs
    221         getPreferenceManager().addPreferencesScreen(dialog);
    222 
    223         dialog.show();
    224     }
    225 
    226     public void onDismiss(DialogInterface dialog) {
    227         mDialog = null;
    228         getPreferenceManager().removePreferencesScreen(dialog);
    229     }
    230 
    231     /**
    232      * Used to get a handle to the dialog.
    233      * This is useful for cases where we want to manipulate the dialog
    234      * as we would with any other activity or view.
    235      */
    236     public Dialog getDialog() {
    237         return mDialog;
    238     }
    239 
    240     public void onItemClick(AdapterView parent, View view, int position, long id) {
    241         // If the list has headers, subtract them from the index.
    242         if (parent instanceof ListView) {
    243             position -= ((ListView) parent).getHeaderViewsCount();
    244         }
    245         Object item = getRootAdapter().getItem(position);
    246         if (!(item instanceof Preference)) return;
    247 
    248         final Preference preference = (Preference) item;
    249         preference.performClick(this);
    250     }
    251 
    252     @Override
    253     protected boolean isOnSameScreenAsChildren() {
    254         return false;
    255     }
    256 
    257     @Override
    258     protected Parcelable onSaveInstanceState() {
    259         final Parcelable superState = super.onSaveInstanceState();
    260         final Dialog dialog = mDialog;
    261         if (dialog == null || !dialog.isShowing()) {
    262             return superState;
    263         }
    264 
    265         final SavedState myState = new SavedState(superState);
    266         myState.isDialogShowing = true;
    267         myState.dialogBundle = dialog.onSaveInstanceState();
    268         return myState;
    269     }
    270 
    271     @Override
    272     protected void onRestoreInstanceState(Parcelable state) {
    273         if (state == null || !state.getClass().equals(SavedState.class)) {
    274             // Didn't save state for us in onSaveInstanceState
    275             super.onRestoreInstanceState(state);
    276             return;
    277         }
    278 
    279         SavedState myState = (SavedState) state;
    280         super.onRestoreInstanceState(myState.getSuperState());
    281         if (myState.isDialogShowing) {
    282             showDialog(myState.dialogBundle);
    283         }
    284     }
    285 
    286     private static class SavedState extends BaseSavedState {
    287         boolean isDialogShowing;
    288         Bundle dialogBundle;
    289 
    290         public SavedState(Parcel source) {
    291             super(source);
    292             isDialogShowing = source.readInt() == 1;
    293             dialogBundle = source.readBundle();
    294         }
    295 
    296         @Override
    297         public void writeToParcel(Parcel dest, int flags) {
    298             super.writeToParcel(dest, flags);
    299             dest.writeInt(isDialogShowing ? 1 : 0);
    300             dest.writeBundle(dialogBundle);
    301         }
    302 
    303         public SavedState(Parcelable superState) {
    304             super(superState);
    305         }
    306 
    307         public static final Parcelable.Creator<SavedState> CREATOR =
    308                 new Parcelable.Creator<SavedState>() {
    309             public SavedState createFromParcel(Parcel in) {
    310                 return new SavedState(in);
    311             }
    312 
    313             public SavedState[] newArray(int size) {
    314                 return new SavedState[size];
    315             }
    316         };
    317     }
    318 
    319 }
    320