2 * Copyright (C) 2007 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package android.preference;
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;
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)}.
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.
55 * <p>Here's an example XML layout of a PreferenceScreen:</p>
58 xmlns:android="http://schemas.android.com/apk/res/android"
59 android:key="first_preferencescreen">
60 <CheckBoxPreference
61 android:key="wifi enabled"
62 android:title="WiFi" />
64 android:key="second_preferencescreen"
65 android:title="WiFi settings">
66 <CheckBoxPreference
67 android:key="prefer wifi"
68 android:title="Prefer WiFi" />
69 ... other preferences here ...
70 </PreferenceScreen>
71 </PreferenceScreen> </pre>
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).
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>
87 * @see PreferenceCategory
89 public final class PreferenceScreen extends PreferenceGroup implements AdapterView.OnItemClickListener,
90 DialogInterface.OnDismissListener {
92 private ListAdapter mRootAdapter;
94 private Dialog mDialog;
96 private ListView mListView;
98 private int mLayoutResId = com.android.internal.R.layout.preference_list_fragment;
99 private Drawable mDividerDrawable;
100 private boolean mDividerSpecified;
103 * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}.
106 public PreferenceScreen(Context context, AttributeSet attrs) {
107 super(context, attrs, com.android.internal.R.attr.preferenceScreenStyle);
109 TypedArray a = context.obtainStyledAttributes(null,
110 com.android.internal.R.styleable.PreferenceScreen,
111 com.android.internal.R.attr.preferenceScreenStyle,
114 mLayoutResId = a.getResourceId(
115 com.android.internal.R.styleable.PreferenceScreen_screenLayout,
117 if (a.hasValueOrEmpty(com.android.internal.R.styleable.PreferenceScreen_divider)) {
119 a.getDrawable(com.android.internal.R.styleable.PreferenceScreen_divider);
120 mDividerSpecified = true;
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}.
131 * This {@link PreferenceScreen} will NOT appear in the returned adapter, instead
132 * it appears in the hierarchy above this {@link PreferenceScreen}.
134 * This adapter's {@link Adapter#getItem(int)} should always return a
135 * subclass of {@link Preference}.
137 * @return An adapter that provides the {@link Preference} contained in this
138 * {@link PreferenceScreen}.
140 public ListAdapter getRootAdapter() {
141 if (mRootAdapter == null) {
142 mRootAdapter = onCreateRootAdapter();
149 * Creates the root adapter.
151 * @return An adapter that contains the preferences contained in this {@link PreferenceScreen}.
152 * @see #getRootAdapter()
154 protected ListAdapter onCreateRootAdapter() {
155 return new PreferenceGroupAdapter(this);
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}.
163 * @param listView The list view to attach to.
165 public void bind(ListView listView) {
166 listView.setOnItemClickListener(this);
167 listView.setAdapter(getRootAdapter());
169 onAttachedToActivity();
173 protected void onClick() {
174 if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
181 private void showDialog(Bundle state) {
182 Context context = getContext();
183 if (mListView != null) {
184 mListView.setAdapter(null);
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);
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);
205 dialog.getWindow().requestFeature(Window.FEATURE_NO_TITLE);
207 if (titleView instanceof TextView) {
208 ((TextView) titleView).setText(title);
209 titleView.setVisibility(View.VISIBLE);
211 dialog.setTitle(title);
214 dialog.setContentView(childPrefScreen);
215 dialog.setOnDismissListener(this);
217 dialog.onRestoreInstanceState(state);
220 // Add the screen to the list of preferences screens opened as dialogs
221 getPreferenceManager().addPreferencesScreen(dialog);
226 public void onDismiss(DialogInterface dialog) {
228 getPreferenceManager().removePreferencesScreen(dialog);
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.
236 public Dialog getDialog() {
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();
245 Object item = getRootAdapter().getItem(position);
246 if (!(item instanceof Preference)) return;
248 final Preference preference = (Preference) item;
249 preference.performClick(this);
253 protected boolean isOnSameScreenAsChildren() {
258 protected Parcelable onSaveInstanceState() {
259 final Parcelable superState = super.onSaveInstanceState();
260 final Dialog dialog = mDialog;
261 if (dialog == null || !dialog.isShowing()) {
265 final SavedState myState = new SavedState(superState);
266 myState.isDialogShowing = true;
267 myState.dialogBundle = dialog.onSaveInstanceState();
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);
279 SavedState myState = (SavedState) state;
280 super.onRestoreInstanceState(myState.getSuperState());
281 if (myState.isDialogShowing) {
282 showDialog(myState.dialogBundle);
286 private static class SavedState extends BaseSavedState {
287 boolean isDialogShowing;
290 public SavedState(Parcel source) {
292 isDialogShowing = source.readInt() == 1;
293 dialogBundle = source.readBundle();
297 public void writeToParcel(Parcel dest, int flags) {
298 super.writeToParcel(dest, flags);
299 dest.writeInt(isDialogShowing ? 1 : 0);
300 dest.writeBundle(dialogBundle);
303 public SavedState(Parcelable superState) {
307 public static final Parcelable.Creator<SavedState> CREATOR =
308 new Parcelable.Creator<SavedState>() {
309 public SavedState createFromParcel(Parcel in) {
310 return new SavedState(in);
313 public SavedState[] newArray(int size) {
314 return new SavedState[size];