PreferenceActivity.java revision 48e7b458694acdf3a4fc58e62437f1dbc4f29d83
1d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih/* 2d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * Copyright (C) 2007 The Android Open Source Project 3d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 4d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * Licensed under the Apache License, Version 2.0 (the "License"); 5d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * you may not use this file except in compliance with the License. 6d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * You may obtain a copy of the License at 7d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 8d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * http://www.apache.org/licenses/LICENSE-2.0 9d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 10d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * Unless required by applicable law or agreed to in writing, software 11d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * distributed under the License is distributed on an "AS IS" BASIS, 12d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * See the License for the specific language governing permissions and 14d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * limitations under the License. 15d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih */ 16d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 17d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihpackage android.preference; 18d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 19d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport com.android.internal.util.XmlUtils; 20255735a38b9d5c3755c7b819bdc8fdaf4357d860Pawin Vongmasa 21255735a38b9d5c3755c7b819bdc8fdaf4357d860Pawin Vongmasaimport org.xmlpull.v1.XmlPullParser; 22255735a38b9d5c3755c7b819bdc8fdaf4357d860Pawin Vongmasaimport org.xmlpull.v1.XmlPullParserException; 23255735a38b9d5c3755c7b819bdc8fdaf4357d860Pawin Vongmasa 24d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.app.ActionBar; 25eeb436397a78aa80e41a4929a5f379319eefe0c3Colin Crossimport android.app.Fragment; 26d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.app.FragmentBreadCrumbs; 27d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.app.FragmentManager; 28d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.app.FragmentTransaction; 29d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.app.ListActivity; 30d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.Context; 31d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.Intent; 32d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.res.Configuration; 33d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.res.Resources; 34d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.res.TypedArray; 35d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.content.res.XmlResourceParser; 36d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.os.Bundle; 37d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.os.Handler; 38d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.os.Message; 39d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.os.Parcel; 40d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.os.Parcelable; 41d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.text.TextUtils; 42d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.util.AttributeSet; 43d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.util.TypedValue; 44d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.util.Xml; 45d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.view.LayoutInflater; 46d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.view.View; 47d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.view.View.OnClickListener; 48d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.view.ViewGroup; 49d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.AbsListView; 50d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.ArrayAdapter; 51d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.Button; 52d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.FrameLayout; 53d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.ImageView; 54d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.ListView; 55d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport android.widget.TextView; 56d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 57d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport java.io.IOException; 582860573684ebaf514827cc1b5b144deb194eb8f6Wonsik Kimimport java.util.ArrayList; 59d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihimport java.util.List; 602860573684ebaf514827cc1b5b144deb194eb8f6Wonsik Kim 61d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih/** 62d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * This is the base class for an activity to show a hierarchy of preferences 63d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * to the user. Prior to {@link android.os.Build.VERSION_CODES#HONEYCOMB} 64d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * this class only allowed the display of a single set of preference; this 65d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * functionality should now be found in the new {@link PreferenceFragment} 66d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * class. If you are using PreferenceActivity in its old mode, the documentation 67d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * there applies to the deprecated APIs here. 68d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 69d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>This activity shows one or more headers of preferences, each of with 70d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * is associated with a {@link PreferenceFragment} to display the preferences 71d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * of that header. The actual layout and display of these associations can 72d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * however vary; currently there are two major approaches it may take: 73d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 74d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <ul> 75d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <li>On a small screen it may display only the headers as a single list 76d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * when first launched. Selecting one of the header items will re-launch 77d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * the activity with it only showing the PreferenceFragment of that header. 78d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <li>On a large screen in may display both the headers and current 79d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * PreferenceFragment together as panes. Selecting a header item switches 80d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * to showing the correct PreferenceFragment for that item. 81d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * </ul> 82d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 83d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>Subclasses of PreferenceActivity should implement 84d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * {@link #onBuildHeaders} to populate the header list with the desired 85d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * items. Doing this implicitly switches the class into its new "headers 862860573684ebaf514827cc1b5b144deb194eb8f6Wonsik Kim * + fragments" mode rather than the old style of just showing a single 87d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * preferences list. 88d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 89d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <a name="SampleCode"></a> 90d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <h3>Sample Code</h3> 91d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 92d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>The following sample code shows a simple preference activity that 93d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * has two different sets of preferences. The implementation, consisting 94d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * of the activity itself as well as its two preference fragments is:</p> 95d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 96d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * {@sample development/samples/ApiDemos/src/com/example/android/apis/preference/PreferenceWithHeaders.java 97d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * activity} 98d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 99d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>The preference_headers resource describes the headers to be displayed 100d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * and the fragments associated with them. It is: 101d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 102d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * {@sample development/samples/ApiDemos/res/xml/preference_headers.xml headers} 103d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 104d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>The first header is shown by Prefs1Fragment, which populates itself 105d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * from the following XML resource:</p> 106d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 107d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * {@sample development/samples/ApiDemos/res/xml/fragmented_preferences.xml preferences} 108d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 109d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>Note that this XML resource contains a preference screen holding another 110d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * fragment, the Prefs1FragmentInner implemented here. This allows the user 111d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * to traverse down a hierarchy of preferences; pressing back will pop each 112d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * fragment off the stack to return to the previous preferences. 113d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * 114d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * <p>See {@link PreferenceFragment} for information on implementing the 115d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * fragments themselves. 116d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih */ 117d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shihpublic abstract class PreferenceActivity extends ListActivity implements 118d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih PreferenceManager.OnPreferenceTreeClickListener, 119d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih PreferenceFragment.OnPreferenceStartFragmentCallback { 120d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String TAG = "PreferenceActivity"; 121d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 122d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // Constants for state save/restore 123d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String HEADERS_TAG = ":android:headers"; 124d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String CUR_HEADER_TAG = ":android:cur_header"; 125d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String PREFERENCES_TAG = ":android:preferences"; 126d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 127d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih /** 128d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * When starting this activity, the invoking Intent can contain this extra 129d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * string to specify which fragment should be initially displayed. 130d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih */ 131d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih public static final String EXTRA_SHOW_FRAGMENT = ":android:show_fragment"; 132d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 133d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih /** 134d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * When starting this activity and using {@link #EXTRA_SHOW_FRAGMENT}, 135d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * this extra can also be specify to supply a Bundle of arguments to pass 136d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * to that fragment when it is instantiated during the initial creation 137d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * of PreferenceActivity. 138d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih */ 139d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih public static final String EXTRA_SHOW_FRAGMENT_ARGUMENTS = ":android:show_fragment_args"; 140d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 141d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih /** 142d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * When starting this activity, the invoking Intent can contain this extra 143d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * boolean that the header list should not be displayed. This is most often 144d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * used in conjunction with {@link #EXTRA_SHOW_FRAGMENT} to launch 145d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih * the activity to display a specific fragment that the user has navigated 14622dc508717c7767927064ec7c152def99e54adcbPawin Vongmasa * to. 147d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih */ 14822dc508717c7767927064ec7c152def99e54adcbPawin Vongmasa public static final String EXTRA_NO_HEADERS = ":android:no_headers"; 149d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 150d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String BACK_STACK_PREFS = ":android:prefs"; 151d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 152d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // extras that allow any preference activity to be launched as part of a wizard 153d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 154d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // show Back and Next buttons? takes boolean parameter 155d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // Back will then return RESULT_CANCELED and Next RESULT_OK 156d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String EXTRA_PREFS_SHOW_BUTTON_BAR = "extra_prefs_show_button_bar"; 157d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 158d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // add a Skip button? 159d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private static final String EXTRA_PREFS_SHOW_SKIP = "extra_prefs_show_skip"; 160d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 161f72cefddf378909f360998852e41f49042711299Hangyu Kuang // specify custom text for the Back or Next buttons, or cause a button to not appear 162f72cefddf378909f360998852e41f49042711299Hangyu Kuang // at all by setting it to null 163f72cefddf378909f360998852e41f49042711299Hangyu Kuang private static final String EXTRA_PREFS_SET_NEXT_TEXT = "extra_prefs_set_next_text"; 164f72cefddf378909f360998852e41f49042711299Hangyu Kuang private static final String EXTRA_PREFS_SET_BACK_TEXT = "extra_prefs_set_back_text"; 165f72cefddf378909f360998852e41f49042711299Hangyu Kuang 166d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih // --- State for new mode when showing a list of headers + prefs fragment 167d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 168d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private final ArrayList<Header> mHeaders = new ArrayList<Header>(); 169d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 170d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private HeaderAdapter mAdapter; 171d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 172d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private FrameLayout mListFooter; 173d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 174d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private ViewGroup mPrefsContainer; 175d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 176d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private FragmentBreadCrumbs mFragmentBreadCrumbs; 177d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 178d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private boolean mSinglePane; 179d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih 180d095e65c8c125c555046c60539a0f7abf0ccf271Robert Shih private Header mCurHeader; 181 182 // --- State for old mode when showing a single preference list 183 184 private PreferenceManager mPreferenceManager; 185 186 private Bundle mSavedInstanceState; 187 188 // --- Common state 189 190 private Button mNextButton; 191 192 /** 193 * The starting request code given out to preference framework. 194 */ 195 private static final int FIRST_REQUEST_CODE = 100; 196 197 private static final int MSG_BIND_PREFERENCES = 1; 198 private static final int MSG_BUILD_HEADERS = 2; 199 private Handler mHandler = new Handler() { 200 @Override 201 public void handleMessage(Message msg) { 202 switch (msg.what) { 203 case MSG_BIND_PREFERENCES: { 204 bindPreferences(); 205 } break; 206 case MSG_BUILD_HEADERS: { 207 ArrayList<Header> oldHeaders = new ArrayList<Header>(mHeaders); 208 mHeaders.clear(); 209 onBuildHeaders(mHeaders); 210 if (mAdapter != null) { 211 mAdapter.notifyDataSetChanged(); 212 } 213 Header header = onGetNewHeader(); 214 if (header != null && header.fragment != null) { 215 Header mappedHeader = findBestMatchingHeader(header, oldHeaders); 216 if (mappedHeader == null || mCurHeader != mappedHeader) { 217 switchToHeader(header); 218 } 219 } else if (mCurHeader != null) { 220 Header mappedHeader = findBestMatchingHeader(mCurHeader, mHeaders); 221 if (mappedHeader != null) { 222 setSelectedHeader(mappedHeader); 223 } 224 } 225 } break; 226 } 227 } 228 }; 229 230 private static class HeaderAdapter extends ArrayAdapter<Header> { 231 private static class HeaderViewHolder { 232 ImageView icon; 233 TextView title; 234 TextView summary; 235 } 236 237 private LayoutInflater mInflater; 238 239 public HeaderAdapter(Context context, List<Header> objects) { 240 super(context, 0, objects); 241 mInflater = (LayoutInflater)context.getSystemService(Context.LAYOUT_INFLATER_SERVICE); 242 } 243 244 @Override 245 public View getView(int position, View convertView, ViewGroup parent) { 246 HeaderViewHolder holder; 247 View view; 248 249 if (convertView == null) { 250 view = mInflater.inflate(com.android.internal.R.layout.preference_header_item, 251 parent, false); 252 holder = new HeaderViewHolder(); 253 holder.icon = (ImageView) view.findViewById(com.android.internal.R.id.icon); 254 holder.title = (TextView) view.findViewById(com.android.internal.R.id.title); 255 holder.summary = (TextView) view.findViewById(com.android.internal.R.id.summary); 256 view.setTag(holder); 257 } else { 258 view = convertView; 259 holder = (HeaderViewHolder) view.getTag(); 260 } 261 262 // All view fields must be updated every time, because the view may be recycled 263 Header header = getItem(position); 264 holder.icon.setImageResource(header.iconRes); 265 holder.title.setText(header.getTitle(getContext().getResources())); 266 CharSequence summary = header.getSummary(getContext().getResources()); 267 if (!TextUtils.isEmpty(summary)) { 268 holder.summary.setVisibility(View.VISIBLE); 269 holder.summary.setText(summary); 270 } else { 271 holder.summary.setVisibility(View.GONE); 272 } 273 274 return view; 275 } 276 } 277 278 /** 279 * Default value for {@link Header#id Header.id} indicating that no 280 * identifier value is set. All other values (including those below -1) 281 * are valid. 282 */ 283 public static final long HEADER_ID_UNDEFINED = -1; 284 285 /** 286 * Description of a single Header item that the user can select. 287 */ 288 public static final class Header implements Parcelable { 289 /** 290 * Identifier for this header, to correlate with a new list when 291 * it is updated. The default value is 292 * {@link PreferenceActivity#HEADER_ID_UNDEFINED}, meaning no id. 293 * @attr ref android.R.styleable#PreferenceHeader_id 294 */ 295 public long id = HEADER_ID_UNDEFINED; 296 297 /** 298 * Resource ID of title of the header that is shown to the user. 299 * @attr ref android.R.styleable#PreferenceHeader_title 300 */ 301 public int titleRes; 302 303 /** 304 * Title of the header that is shown to the user. 305 * @attr ref android.R.styleable#PreferenceHeader_title 306 */ 307 public CharSequence title; 308 309 /** 310 * Resource ID of optional summary describing what this header controls. 311 * @attr ref android.R.styleable#PreferenceHeader_summary 312 */ 313 public int summaryRes; 314 315 /** 316 * Optional summary describing what this header controls. 317 * @attr ref android.R.styleable#PreferenceHeader_summary 318 */ 319 public CharSequence summary; 320 321 /** 322 * Resource ID of optional text to show as the title in the bread crumb. 323 * @attr ref android.R.styleable#PreferenceHeader_breadCrumbTitle 324 */ 325 public int breadCrumbTitleRes; 326 327 /** 328 * Optional text to show as the title in the bread crumb. 329 * @attr ref android.R.styleable#PreferenceHeader_breadCrumbTitle 330 */ 331 public CharSequence breadCrumbTitle; 332 333 /** 334 * Resource ID of optional text to show as the short title in the bread crumb. 335 * @attr ref android.R.styleable#PreferenceHeader_breadCrumbShortTitle 336 */ 337 public int breadCrumbShortTitleRes; 338 339 /** 340 * Optional text to show as the short title in the bread crumb. 341 * @attr ref android.R.styleable#PreferenceHeader_breadCrumbShortTitle 342 */ 343 public CharSequence breadCrumbShortTitle; 344 345 /** 346 * Optional icon resource to show for this header. 347 * @attr ref android.R.styleable#PreferenceHeader_icon 348 */ 349 public int iconRes; 350 351 /** 352 * Full class name of the fragment to display when this header is 353 * selected. 354 * @attr ref android.R.styleable#PreferenceHeader_fragment 355 */ 356 public String fragment; 357 358 /** 359 * Optional arguments to supply to the fragment when it is 360 * instantiated. 361 */ 362 public Bundle fragmentArguments; 363 364 /** 365 * Intent to launch when the preference is selected. 366 */ 367 public Intent intent; 368 369 /** 370 * Optional additional data for use by subclasses of PreferenceActivity. 371 */ 372 public Bundle extras; 373 374 public Header() { 375 } 376 377 /** 378 * Return the currently set title. If {@link #titleRes} is set, 379 * this resource is loaded from <var>res</var> and returned. Otherwise 380 * {@link #title} is returned. 381 */ 382 public CharSequence getTitle(Resources res) { 383 if (titleRes != 0) { 384 return res.getText(titleRes); 385 } 386 return title; 387 } 388 389 /** 390 * Return the currently set summary. If {@link #summaryRes} is set, 391 * this resource is loaded from <var>res</var> and returned. Otherwise 392 * {@link #summary} is returned. 393 */ 394 public CharSequence getSummary(Resources res) { 395 if (summaryRes != 0) { 396 return res.getText(summaryRes); 397 } 398 return summary; 399 } 400 401 /** 402 * Return the currently set bread crumb title. If {@link #breadCrumbTitleRes} is set, 403 * this resource is loaded from <var>res</var> and returned. Otherwise 404 * {@link #breadCrumbTitle} is returned. 405 */ 406 public CharSequence getBreadCrumbTitle(Resources res) { 407 if (breadCrumbTitleRes != 0) { 408 return res.getText(breadCrumbTitleRes); 409 } 410 return breadCrumbTitle; 411 } 412 413 /** 414 * Return the currently set bread crumb short title. If 415 * {@link #breadCrumbShortTitleRes} is set, 416 * this resource is loaded from <var>res</var> and returned. Otherwise 417 * {@link #breadCrumbShortTitle} is returned. 418 */ 419 public CharSequence getBreadCrumbShortTitle(Resources res) { 420 if (breadCrumbShortTitleRes != 0) { 421 return res.getText(breadCrumbShortTitleRes); 422 } 423 return breadCrumbShortTitle; 424 } 425 426 @Override 427 public int describeContents() { 428 return 0; 429 } 430 431 @Override 432 public void writeToParcel(Parcel dest, int flags) { 433 dest.writeLong(id); 434 dest.writeInt(titleRes); 435 TextUtils.writeToParcel(title, dest, flags); 436 dest.writeInt(summaryRes); 437 TextUtils.writeToParcel(summary, dest, flags); 438 dest.writeInt(breadCrumbTitleRes); 439 TextUtils.writeToParcel(breadCrumbTitle, dest, flags); 440 dest.writeInt(breadCrumbShortTitleRes); 441 TextUtils.writeToParcel(breadCrumbShortTitle, dest, flags); 442 dest.writeInt(iconRes); 443 dest.writeString(fragment); 444 dest.writeBundle(fragmentArguments); 445 if (intent != null) { 446 dest.writeInt(1); 447 intent.writeToParcel(dest, flags); 448 } else { 449 dest.writeInt(0); 450 } 451 dest.writeBundle(extras); 452 } 453 454 public void readFromParcel(Parcel in) { 455 id = in.readLong(); 456 titleRes = in.readInt(); 457 title = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 458 summaryRes = in.readInt(); 459 summary = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 460 breadCrumbTitleRes = in.readInt(); 461 breadCrumbTitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 462 breadCrumbShortTitleRes = in.readInt(); 463 breadCrumbShortTitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 464 iconRes = in.readInt(); 465 fragment = in.readString(); 466 fragmentArguments = in.readBundle(); 467 if (in.readInt() != 0) { 468 intent = Intent.CREATOR.createFromParcel(in); 469 } 470 extras = in.readBundle(); 471 } 472 473 Header(Parcel in) { 474 readFromParcel(in); 475 } 476 477 public static final Creator<Header> CREATOR = new Creator<Header>() { 478 public Header createFromParcel(Parcel source) { 479 return new Header(source); 480 } 481 public Header[] newArray(int size) { 482 return new Header[size]; 483 } 484 }; 485 } 486 487 @Override 488 protected void onCreate(Bundle savedInstanceState) { 489 super.onCreate(savedInstanceState); 490 491 setContentView(com.android.internal.R.layout.preference_list_content); 492 493 mListFooter = (FrameLayout)findViewById(com.android.internal.R.id.list_footer); 494 mPrefsContainer = (ViewGroup) findViewById(com.android.internal.R.id.prefs_frame); 495 boolean hidingHeaders = onIsHidingHeaders(); 496 mSinglePane = hidingHeaders || !onIsMultiPane(); 497 String initialFragment = getIntent().getStringExtra(EXTRA_SHOW_FRAGMENT); 498 Bundle initialArguments = getIntent().getBundleExtra(EXTRA_SHOW_FRAGMENT_ARGUMENTS); 499 500 if (savedInstanceState != null) { 501 // We are restarting from a previous saved state; used that to 502 // initialize, instead of starting fresh. 503 ArrayList<Header> headers = savedInstanceState.getParcelableArrayList(HEADERS_TAG); 504 if (headers != null) { 505 mHeaders.addAll(headers); 506 int curHeader = savedInstanceState.getInt(CUR_HEADER_TAG, 507 (int)HEADER_ID_UNDEFINED); 508 if (curHeader >= 0 && curHeader < mHeaders.size()) { 509 setSelectedHeader(mHeaders.get(curHeader)); 510 } 511 } 512 513 } else { 514 if (initialFragment != null && mSinglePane) { 515 // If we are just showing a fragment, we want to run in 516 // new fragment mode, but don't need to compute and show 517 // the headers. 518 switchToHeader(initialFragment, initialArguments); 519 520 } else { 521 // We need to try to build the headers. 522 onBuildHeaders(mHeaders); 523 524 // If there are headers, then at this point we need to show 525 // them and, depending on the screen, we may also show in-line 526 // the currently selected preference fragment. 527 if (mHeaders.size() > 0) { 528 if (!mSinglePane) { 529 if (initialFragment == null) { 530 Header h = onGetInitialHeader(); 531 switchToHeader(h); 532 } else { 533 switchToHeader(initialFragment, initialArguments); 534 } 535 } 536 } 537 } 538 } 539 540 // The default configuration is to only show the list view. Adjust 541 // visibility for other configurations. 542 if (initialFragment != null && mSinglePane) { 543 // Single pane, showing just a prefs fragment. 544 findViewById(com.android.internal.R.id.headers).setVisibility(View.GONE); 545 mPrefsContainer.setVisibility(View.VISIBLE); 546 } else if (mHeaders.size() > 0) { 547 mAdapter = new HeaderAdapter(this, mHeaders); 548 setListAdapter(mAdapter); 549 if (!mSinglePane) { 550 // Multi-pane. 551 getListView().setChoiceMode(AbsListView.CHOICE_MODE_SINGLE); 552 if (mCurHeader != null) { 553 setSelectedHeader(mCurHeader); 554 } 555 mPrefsContainer.setVisibility(View.VISIBLE); 556 } 557 } else { 558 // If there are no headers, we are in the old "just show a screen 559 // of preferences" mode. 560 setContentView(com.android.internal.R.layout.preference_list_content_single); 561 mListFooter = (FrameLayout) findViewById(com.android.internal.R.id.list_footer); 562 mPrefsContainer = (ViewGroup) findViewById(com.android.internal.R.id.prefs); 563 mPreferenceManager = new PreferenceManager(this, FIRST_REQUEST_CODE); 564 mPreferenceManager.setOnPreferenceTreeClickListener(this); 565 } 566 567 getListView().setScrollBarStyle(View.SCROLLBARS_INSIDE_OVERLAY); 568 569 // see if we should show Back/Next buttons 570 Intent intent = getIntent(); 571 if (intent.getBooleanExtra(EXTRA_PREFS_SHOW_BUTTON_BAR, false)) { 572 573 findViewById(com.android.internal.R.id.button_bar).setVisibility(View.VISIBLE); 574 575 Button backButton = (Button)findViewById(com.android.internal.R.id.back_button); 576 backButton.setOnClickListener(new OnClickListener() { 577 public void onClick(View v) { 578 setResult(RESULT_CANCELED); 579 finish(); 580 } 581 }); 582 Button skipButton = (Button)findViewById(com.android.internal.R.id.skip_button); 583 skipButton.setOnClickListener(new OnClickListener() { 584 public void onClick(View v) { 585 setResult(RESULT_OK); 586 finish(); 587 } 588 }); 589 mNextButton = (Button)findViewById(com.android.internal.R.id.next_button); 590 mNextButton.setOnClickListener(new OnClickListener() { 591 public void onClick(View v) { 592 setResult(RESULT_OK); 593 finish(); 594 } 595 }); 596 597 // set our various button parameters 598 if (intent.hasExtra(EXTRA_PREFS_SET_NEXT_TEXT)) { 599 String buttonText = intent.getStringExtra(EXTRA_PREFS_SET_NEXT_TEXT); 600 if (TextUtils.isEmpty(buttonText)) { 601 mNextButton.setVisibility(View.GONE); 602 } 603 else { 604 mNextButton.setText(buttonText); 605 } 606 } 607 if (intent.hasExtra(EXTRA_PREFS_SET_BACK_TEXT)) { 608 String buttonText = intent.getStringExtra(EXTRA_PREFS_SET_BACK_TEXT); 609 if (TextUtils.isEmpty(buttonText)) { 610 backButton.setVisibility(View.GONE); 611 } 612 else { 613 backButton.setText(buttonText); 614 } 615 } 616 if (intent.getBooleanExtra(EXTRA_PREFS_SHOW_SKIP, false)) { 617 skipButton.setVisibility(View.VISIBLE); 618 } 619 } 620 } 621 622 /** 623 * Returns true if this activity is currently showing the header list. 624 */ 625 public boolean hasHeaders() { 626 return getListView().getVisibility() == View.VISIBLE 627 && mPreferenceManager == null; 628 } 629 630 /** 631 * Returns true if this activity is showing multiple panes -- the headers 632 * and a preference fragment. 633 */ 634 public boolean isMultiPane() { 635 return hasHeaders() && mPrefsContainer.getVisibility() == View.VISIBLE; 636 } 637 638 /** 639 * Called to determine if the activity should run in multi-pane mode. 640 * The default implementation returns true if the screen is large 641 * enough. 642 */ 643 public boolean onIsMultiPane() { 644 Configuration config = getResources().getConfiguration(); 645 if ((config.screenLayout&Configuration.SCREENLAYOUT_SIZE_MASK) 646 == Configuration.SCREENLAYOUT_SIZE_XLARGE) { 647 return true; 648 } 649 if ((config.screenLayout&Configuration.SCREENLAYOUT_SIZE_MASK) 650 == Configuration.SCREENLAYOUT_SIZE_LARGE 651 && config.orientation == Configuration.ORIENTATION_LANDSCAPE) { 652 return true; 653 } 654 return false; 655 } 656 657 /** 658 * Called to determine whether the header list should be hidden. 659 * The default implementation returns the 660 * value given in {@link #EXTRA_NO_HEADERS} or false if it is not supplied. 661 * This is set to false, for example, when the activity is being re-launched 662 * to show a particular preference activity. 663 */ 664 public boolean onIsHidingHeaders() { 665 return getIntent().getBooleanExtra(EXTRA_NO_HEADERS, false); 666 } 667 668 /** 669 * Called to determine the initial header to be shown. The default 670 * implementation simply returns the fragment of the first header. Note 671 * that the returned Header object does not actually need to exist in 672 * your header list -- whatever its fragment is will simply be used to 673 * show for the initial UI. 674 */ 675 public Header onGetInitialHeader() { 676 return mHeaders.get(0); 677 } 678 679 /** 680 * Called after the header list has been updated ({@link #onBuildHeaders} 681 * has been called and returned due to {@link #invalidateHeaders()}) to 682 * specify the header that should now be selected. The default implementation 683 * returns null to keep whatever header is currently selected. 684 */ 685 public Header onGetNewHeader() { 686 return null; 687 } 688 689 /** 690 * Called when the activity needs its list of headers build. By 691 * implementing this and adding at least one item to the list, you 692 * will cause the activity to run in its modern fragment mode. Note 693 * that this function may not always be called; for example, if the 694 * activity has been asked to display a particular fragment without 695 * the header list, there is no need to build the headers. 696 * 697 * <p>Typical implementations will use {@link #loadHeadersFromResource} 698 * to fill in the list from a resource. 699 * 700 * @param target The list in which to place the headers. 701 */ 702 public void onBuildHeaders(List<Header> target) { 703 } 704 705 /** 706 * Call when you need to change the headers being displayed. Will result 707 * in onBuildHeaders() later being called to retrieve the new list. 708 */ 709 public void invalidateHeaders() { 710 if (!mHandler.hasMessages(MSG_BUILD_HEADERS)) { 711 mHandler.sendEmptyMessage(MSG_BUILD_HEADERS); 712 } 713 } 714 715 /** 716 * Parse the given XML file as a header description, adding each 717 * parsed Header into the target list. 718 * 719 * @param resid The XML resource to load and parse. 720 * @param target The list in which the parsed headers should be placed. 721 */ 722 public void loadHeadersFromResource(int resid, List<Header> target) { 723 XmlResourceParser parser = null; 724 try { 725 parser = getResources().getXml(resid); 726 AttributeSet attrs = Xml.asAttributeSet(parser); 727 728 int type; 729 while ((type=parser.next()) != XmlPullParser.END_DOCUMENT 730 && type != XmlPullParser.START_TAG) { 731 } 732 733 String nodeName = parser.getName(); 734 if (!"preference-headers".equals(nodeName)) { 735 throw new RuntimeException( 736 "XML document must start with <preference-headers> tag; found" 737 + nodeName + " at " + parser.getPositionDescription()); 738 } 739 740 Bundle curBundle = null; 741 742 final int outerDepth = parser.getDepth(); 743 while ((type=parser.next()) != XmlPullParser.END_DOCUMENT 744 && (type != XmlPullParser.END_TAG || parser.getDepth() > outerDepth)) { 745 if (type == XmlPullParser.END_TAG || type == XmlPullParser.TEXT) { 746 continue; 747 } 748 749 nodeName = parser.getName(); 750 if ("header".equals(nodeName)) { 751 Header header = new Header(); 752 753 TypedArray sa = getResources().obtainAttributes(attrs, 754 com.android.internal.R.styleable.PreferenceHeader); 755 header.id = sa.getResourceId( 756 com.android.internal.R.styleable.PreferenceHeader_id, 757 (int)HEADER_ID_UNDEFINED); 758 TypedValue tv = sa.peekValue( 759 com.android.internal.R.styleable.PreferenceHeader_title); 760 if (tv != null && tv.type == TypedValue.TYPE_STRING) { 761 if (tv.resourceId != 0) { 762 header.titleRes = tv.resourceId; 763 } else { 764 header.title = tv.string; 765 } 766 } 767 tv = sa.peekValue( 768 com.android.internal.R.styleable.PreferenceHeader_summary); 769 if (tv != null && tv.type == TypedValue.TYPE_STRING) { 770 if (tv.resourceId != 0) { 771 header.summaryRes = tv.resourceId; 772 } else { 773 header.summary = tv.string; 774 } 775 } 776 tv = sa.peekValue( 777 com.android.internal.R.styleable.PreferenceHeader_breadCrumbTitle); 778 if (tv != null && tv.type == TypedValue.TYPE_STRING) { 779 if (tv.resourceId != 0) { 780 header.breadCrumbTitleRes = tv.resourceId; 781 } else { 782 header.breadCrumbTitle = tv.string; 783 } 784 } 785 tv = sa.peekValue( 786 com.android.internal.R.styleable.PreferenceHeader_breadCrumbShortTitle); 787 if (tv != null && tv.type == TypedValue.TYPE_STRING) { 788 if (tv.resourceId != 0) { 789 header.breadCrumbShortTitleRes = tv.resourceId; 790 } else { 791 header.breadCrumbShortTitle = tv.string; 792 } 793 } 794 header.iconRes = sa.getResourceId( 795 com.android.internal.R.styleable.PreferenceHeader_icon, 0); 796 header.fragment = sa.getString( 797 com.android.internal.R.styleable.PreferenceHeader_fragment); 798 sa.recycle(); 799 800 if (curBundle == null) { 801 curBundle = new Bundle(); 802 } 803 804 final int innerDepth = parser.getDepth(); 805 while ((type=parser.next()) != XmlPullParser.END_DOCUMENT 806 && (type != XmlPullParser.END_TAG || parser.getDepth() > innerDepth)) { 807 if (type == XmlPullParser.END_TAG || type == XmlPullParser.TEXT) { 808 continue; 809 } 810 811 String innerNodeName = parser.getName(); 812 if (innerNodeName.equals("extra")) { 813 getResources().parseBundleExtra("extra", attrs, curBundle); 814 XmlUtils.skipCurrentTag(parser); 815 816 } else if (innerNodeName.equals("intent")) { 817 header.intent = Intent.parseIntent(getResources(), parser, attrs); 818 819 } else { 820 XmlUtils.skipCurrentTag(parser); 821 } 822 } 823 824 if (curBundle.size() > 0) { 825 header.fragmentArguments = curBundle; 826 curBundle = null; 827 } 828 829 target.add(header); 830 } else { 831 XmlUtils.skipCurrentTag(parser); 832 } 833 } 834 835 } catch (XmlPullParserException e) { 836 throw new RuntimeException("Error parsing headers", e); 837 } catch (IOException e) { 838 throw new RuntimeException("Error parsing headers", e); 839 } finally { 840 if (parser != null) parser.close(); 841 } 842 843 } 844 845 /** 846 * Set a footer that should be shown at the bottom of the header list. 847 */ 848 public void setListFooter(View view) { 849 mListFooter.removeAllViews(); 850 mListFooter.addView(view, new FrameLayout.LayoutParams( 851 FrameLayout.LayoutParams.MATCH_PARENT, 852 FrameLayout.LayoutParams.WRAP_CONTENT)); 853 } 854 855 @Override 856 protected void onStop() { 857 super.onStop(); 858 859 if (mPreferenceManager != null) { 860 mPreferenceManager.dispatchActivityStop(); 861 } 862 } 863 864 @Override 865 protected void onDestroy() { 866 super.onDestroy(); 867 868 if (mPreferenceManager != null) { 869 mPreferenceManager.dispatchActivityDestroy(); 870 } 871 } 872 873 @Override 874 protected void onSaveInstanceState(Bundle outState) { 875 super.onSaveInstanceState(outState); 876 877 if (mHeaders.size() > 0) { 878 outState.putParcelableArrayList(HEADERS_TAG, mHeaders); 879 if (mCurHeader != null) { 880 int index = mHeaders.indexOf(mCurHeader); 881 if (index >= 0) { 882 outState.putInt(CUR_HEADER_TAG, index); 883 } 884 } 885 } 886 887 if (mPreferenceManager != null) { 888 final PreferenceScreen preferenceScreen = getPreferenceScreen(); 889 if (preferenceScreen != null) { 890 Bundle container = new Bundle(); 891 preferenceScreen.saveHierarchyState(container); 892 outState.putBundle(PREFERENCES_TAG, container); 893 } 894 } 895 } 896 897 @Override 898 protected void onRestoreInstanceState(Bundle state) { 899 if (mPreferenceManager != null) { 900 Bundle container = state.getBundle(PREFERENCES_TAG); 901 if (container != null) { 902 final PreferenceScreen preferenceScreen = getPreferenceScreen(); 903 if (preferenceScreen != null) { 904 preferenceScreen.restoreHierarchyState(container); 905 mSavedInstanceState = state; 906 return; 907 } 908 } 909 } 910 911 // Only call this if we didn't save the instance state for later. 912 // If we did save it, it will be restored when we bind the adapter. 913 super.onRestoreInstanceState(state); 914 } 915 916 @Override 917 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 918 super.onActivityResult(requestCode, resultCode, data); 919 920 if (mPreferenceManager != null) { 921 mPreferenceManager.dispatchActivityResult(requestCode, resultCode, data); 922 } 923 } 924 925 @Override 926 public void onContentChanged() { 927 super.onContentChanged(); 928 929 if (mPreferenceManager != null) { 930 postBindPreferences(); 931 } 932 } 933 934 @Override 935 protected void onListItemClick(ListView l, View v, int position, long id) { 936 super.onListItemClick(l, v, position, id); 937 938 if (mAdapter != null) { 939 onHeaderClick(mHeaders.get(position), position); 940 } 941 } 942 943 /** 944 * Called when the user selects an item in the header list. The default 945 * implementation will call either {@link #startWithFragment(String, Bundle, Fragment, int)} 946 * or {@link #switchToHeader(Header)} as appropriate. 947 * 948 * @param header The header that was selected. 949 * @param position The header's position in the list. 950 */ 951 public void onHeaderClick(Header header, int position) { 952 if (header.fragment != null) { 953 if (mSinglePane) { 954 startWithFragment(header.fragment, header.fragmentArguments, null, 0); 955 } else { 956 switchToHeader(header); 957 } 958 } else if (header.intent != null) { 959 startActivity(header.intent); 960 } 961 } 962 963 /** 964 * Start a new instance of this activity, showing only the given 965 * preference fragment. When launched in this mode, the header list 966 * will be hidden and the given preference fragment will be instantiated 967 * and fill the entire activity. 968 * 969 * @param fragmentName The name of the fragment to display. 970 * @param args Optional arguments to supply to the fragment. 971 */ 972 public void startWithFragment(String fragmentName, Bundle args, 973 Fragment resultTo, int resultRequestCode) { 974 Intent intent = new Intent(Intent.ACTION_MAIN); 975 intent.setClass(this, getClass()); 976 intent.putExtra(EXTRA_SHOW_FRAGMENT, fragmentName); 977 intent.putExtra(EXTRA_SHOW_FRAGMENT_ARGUMENTS, args); 978 intent.putExtra(EXTRA_NO_HEADERS, true); 979 if (resultTo == null) { 980 startActivity(intent); 981 } else { 982 resultTo.startActivityForResult(intent, resultRequestCode); 983 } 984 } 985 986 /** 987 * Change the base title of the bread crumbs for the current preferences. 988 * This will normally be called for you. See 989 * {@link android.app.FragmentBreadCrumbs} for more information. 990 */ 991 public void showBreadCrumbs(CharSequence title, CharSequence shortTitle) { 992 if (mFragmentBreadCrumbs == null) { 993 View crumbs = findViewById(android.R.id.title); 994 // For screens with a different kind of title, don't create breadcrumbs. 995 if (!(crumbs instanceof FragmentBreadCrumbs)) return; 996 mFragmentBreadCrumbs = (FragmentBreadCrumbs) findViewById(android.R.id.title); 997 if (mFragmentBreadCrumbs == null) { 998 mFragmentBreadCrumbs = new FragmentBreadCrumbs(this); 999 ActionBar actionBar = getActionBar(); 1000 if (actionBar != null) { 1001 actionBar.setCustomNavigationMode(mFragmentBreadCrumbs); 1002 } 1003 } 1004 mFragmentBreadCrumbs.setMaxVisible(2); 1005 mFragmentBreadCrumbs.setActivity(this); 1006 } 1007 mFragmentBreadCrumbs.setTitle(title, shortTitle); 1008 mFragmentBreadCrumbs.setParentTitle(null, null, null); 1009 } 1010 1011 /** 1012 * Should be called after onCreate to ensure that the breadcrumbs, if any, were created. 1013 * This prepends a title to the fragment breadcrumbs and attaches a listener to any clicks 1014 * on the parent entry. 1015 * @param title the title for the breadcrumb 1016 * @param shortTitle the short title for the breadcrumb 1017 */ 1018 public void setParentTitle(CharSequence title, CharSequence shortTitle, 1019 OnClickListener listener) { 1020 if (mFragmentBreadCrumbs != null) { 1021 mFragmentBreadCrumbs.setParentTitle(title, shortTitle, listener); 1022 } 1023 } 1024 1025 void setSelectedHeader(Header header) { 1026 mCurHeader = header; 1027 int index = mHeaders.indexOf(header); 1028 if (index >= 0) { 1029 getListView().setItemChecked(index, true); 1030 } else { 1031 getListView().clearChoices(); 1032 } 1033 if (header != null) { 1034 CharSequence title = header.getBreadCrumbTitle(getResources()); 1035 if (title == null) title = header.getTitle(getResources()); 1036 if (title == null) title = getTitle(); 1037 showBreadCrumbs(title, header.getBreadCrumbShortTitle(getResources())); 1038 } else { 1039 showBreadCrumbs(getTitle(), null); 1040 } 1041 } 1042 1043 private void switchToHeaderInner(String fragmentName, Bundle args, int direction) { 1044 getFragmentManager().popBackStack(BACK_STACK_PREFS, 1045 FragmentManager.POP_BACK_STACK_INCLUSIVE); 1046 Fragment f = Fragment.instantiate(this, fragmentName, args); 1047 FragmentTransaction transaction = getFragmentManager().beginTransaction(); 1048 transaction.setTransition(direction == 0 ? FragmentTransaction.TRANSIT_NONE 1049 : direction > 0 ? FragmentTransaction.TRANSIT_FRAGMENT_NEXT 1050 : FragmentTransaction.TRANSIT_FRAGMENT_PREV); 1051 transaction.replace(com.android.internal.R.id.prefs, f); 1052 transaction.commit(); 1053 } 1054 1055 /** 1056 * When in two-pane mode, switch the fragment pane to show the given 1057 * preference fragment. 1058 * 1059 * @param fragmentName The name of the fragment to display. 1060 * @param args Optional arguments to supply to the fragment. 1061 */ 1062 public void switchToHeader(String fragmentName, Bundle args) { 1063 setSelectedHeader(null); 1064 switchToHeaderInner(fragmentName, args, 0); 1065 } 1066 1067 /** 1068 * When in two-pane mode, switch to the fragment pane to show the given 1069 * preference fragment. 1070 * 1071 * @param header The new header to display. 1072 */ 1073 public void switchToHeader(Header header) { 1074 if (mCurHeader == header) { 1075 // This is the header we are currently displaying. Just make sure 1076 // to pop the stack up to its root state. 1077 getFragmentManager().popBackStack(BACK_STACK_PREFS, 1078 FragmentManager.POP_BACK_STACK_INCLUSIVE); 1079 } else { 1080 int direction = mHeaders.indexOf(header) - mHeaders.indexOf(mCurHeader); 1081 switchToHeaderInner(header.fragment, header.fragmentArguments, direction); 1082 setSelectedHeader(header); 1083 } 1084 } 1085 1086 Header findBestMatchingHeader(Header cur, ArrayList<Header> from) { 1087 ArrayList<Header> matches = new ArrayList<Header>(); 1088 for (int j=0; j<from.size(); j++) { 1089 Header oh = from.get(j); 1090 if (cur == oh || (cur.id != HEADER_ID_UNDEFINED && cur.id == oh.id)) { 1091 // Must be this one. 1092 matches.clear(); 1093 matches.add(oh); 1094 break; 1095 } 1096 if (cur.fragment != null) { 1097 if (cur.fragment.equals(oh.fragment)) { 1098 matches.add(oh); 1099 } 1100 } else if (cur.intent != null) { 1101 if (cur.intent.equals(oh.intent)) { 1102 matches.add(oh); 1103 } 1104 } else if (cur.title != null) { 1105 if (cur.title.equals(oh.title)) { 1106 matches.add(oh); 1107 } 1108 } 1109 } 1110 final int NM = matches.size(); 1111 if (NM == 1) { 1112 return matches.get(0); 1113 } else if (NM > 1) { 1114 for (int j=0; j<NM; j++) { 1115 Header oh = matches.get(j); 1116 if (cur.fragmentArguments != null && 1117 cur.fragmentArguments.equals(oh.fragmentArguments)) { 1118 return oh; 1119 } 1120 if (cur.extras != null && cur.extras.equals(oh.extras)) { 1121 return oh; 1122 } 1123 if (cur.title != null && cur.title.equals(oh.title)) { 1124 return oh; 1125 } 1126 } 1127 } 1128 return null; 1129 } 1130 1131 /** 1132 * Start a new fragment. 1133 * 1134 * @param fragment The fragment to start 1135 * @param push If true, the current fragment will be pushed onto the back stack. If false, 1136 * the current fragment will be replaced. 1137 */ 1138 public void startPreferenceFragment(Fragment fragment, boolean push) { 1139 FragmentTransaction transaction = getFragmentManager().beginTransaction(); 1140 transaction.replace(com.android.internal.R.id.prefs, fragment); 1141 if (push) { 1142 transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN); 1143 transaction.addToBackStack(BACK_STACK_PREFS); 1144 } else { 1145 transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_NEXT); 1146 } 1147 transaction.commit(); 1148 } 1149 1150 /** 1151 * Start a new fragment containing a preference panel. If the prefences 1152 * are being displayed in multi-pane mode, the given fragment class will 1153 * be instantiated and placed in the appropriate pane. If running in 1154 * single-pane mode, a new activity will be launched in which to show the 1155 * fragment. 1156 * 1157 * @param fragmentClass Full name of the class implementing the fragment. 1158 * @param args Any desired arguments to supply to the fragment. 1159 * @param titleRes Optional resource identifier of the title of this 1160 * fragment. 1161 * @param titleText Optional text of the title of this fragment. 1162 * @param resultTo Optional fragment that result data should be sent to. 1163 * If non-null, resultTo.onActivityResult() will be called when this 1164 * preference panel is done. The launched panel must use 1165 * {@link #finishPreferencePanel(Fragment, int, Intent)} when done. 1166 * @param resultRequestCode If resultTo is non-null, this is the caller's 1167 * request code to be received with the resut. 1168 */ 1169 public void startPreferencePanel(String fragmentClass, Bundle args, int titleRes, 1170 CharSequence titleText, Fragment resultTo, int resultRequestCode) { 1171 if (mSinglePane) { 1172 startWithFragment(fragmentClass, args, resultTo, resultRequestCode); 1173 } else { 1174 Fragment f = Fragment.instantiate(this, fragmentClass, args); 1175 if (resultTo != null) { 1176 f.setTargetFragment(resultTo, resultRequestCode); 1177 } 1178 FragmentTransaction transaction = getFragmentManager().beginTransaction(); 1179 transaction.replace(com.android.internal.R.id.prefs, f); 1180 if (titleRes != 0) { 1181 transaction.setBreadCrumbTitle(titleRes); 1182 } else if (titleText != null) { 1183 transaction.setBreadCrumbTitle(titleText); 1184 } 1185 transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN); 1186 transaction.addToBackStack(BACK_STACK_PREFS); 1187 transaction.commit(); 1188 } 1189 } 1190 1191 /** 1192 * Called by a preference panel fragment to finish itself. 1193 * 1194 * @param caller The fragment that is asking to be finished. 1195 * @param resultCode Optional result code to send back to the original 1196 * launching fragment. 1197 * @param resultData Optional result data to send back to the original 1198 * launching fragment. 1199 */ 1200 public void finishPreferencePanel(Fragment caller, int resultCode, Intent resultData) { 1201 if (mSinglePane) { 1202 setResult(resultCode, resultData); 1203 finish(); 1204 } else { 1205 // XXX be smarter about popping the stack. 1206 onBackPressed(); 1207 if (caller != null) { 1208 if (caller.getTargetFragment() != null) { 1209 caller.getTargetFragment().onActivityResult(caller.getTargetRequestCode(), 1210 resultCode, resultData); 1211 } 1212 } 1213 } 1214 } 1215 1216 @Override 1217 public boolean onPreferenceStartFragment(PreferenceFragment caller, Preference pref) { 1218 startPreferencePanel(pref.getFragment(), pref.getExtras(), 0, pref.getTitle(), null, 0); 1219 return true; 1220 } 1221 1222 /** 1223 * Posts a message to bind the preferences to the list view. 1224 * <p> 1225 * Binding late is preferred as any custom preference types created in 1226 * {@link #onCreate(Bundle)} are able to have their views recycled. 1227 */ 1228 private void postBindPreferences() { 1229 if (mHandler.hasMessages(MSG_BIND_PREFERENCES)) return; 1230 mHandler.obtainMessage(MSG_BIND_PREFERENCES).sendToTarget(); 1231 } 1232 1233 private void bindPreferences() { 1234 final PreferenceScreen preferenceScreen = getPreferenceScreen(); 1235 if (preferenceScreen != null) { 1236 preferenceScreen.bind(getListView()); 1237 if (mSavedInstanceState != null) { 1238 super.onRestoreInstanceState(mSavedInstanceState); 1239 mSavedInstanceState = null; 1240 } 1241 } 1242 } 1243 1244 /** 1245 * Returns the {@link PreferenceManager} used by this activity. 1246 * @return The {@link PreferenceManager}. 1247 * 1248 * @deprecated This function is not relevant for a modern fragment-based 1249 * PreferenceActivity. 1250 */ 1251 @Deprecated 1252 public PreferenceManager getPreferenceManager() { 1253 return mPreferenceManager; 1254 } 1255 1256 private void requirePreferenceManager() { 1257 if (mPreferenceManager == null) { 1258 if (mAdapter == null) { 1259 throw new RuntimeException("This should be called after super.onCreate."); 1260 } 1261 throw new RuntimeException( 1262 "Modern two-pane PreferenceActivity requires use of a PreferenceFragment"); 1263 } 1264 } 1265 1266 /** 1267 * Sets the root of the preference hierarchy that this activity is showing. 1268 * 1269 * @param preferenceScreen The root {@link PreferenceScreen} of the preference hierarchy. 1270 * 1271 * @deprecated This function is not relevant for a modern fragment-based 1272 * PreferenceActivity. 1273 */ 1274 @Deprecated 1275 public void setPreferenceScreen(PreferenceScreen preferenceScreen) { 1276 requirePreferenceManager(); 1277 1278 if (mPreferenceManager.setPreferences(preferenceScreen) && preferenceScreen != null) { 1279 postBindPreferences(); 1280 CharSequence title = getPreferenceScreen().getTitle(); 1281 // Set the title of the activity 1282 if (title != null) { 1283 setTitle(title); 1284 } 1285 } 1286 } 1287 1288 /** 1289 * Gets the root of the preference hierarchy that this activity is showing. 1290 * 1291 * @return The {@link PreferenceScreen} that is the root of the preference 1292 * hierarchy. 1293 * 1294 * @deprecated This function is not relevant for a modern fragment-based 1295 * PreferenceActivity. 1296 */ 1297 @Deprecated 1298 public PreferenceScreen getPreferenceScreen() { 1299 if (mPreferenceManager != null) { 1300 return mPreferenceManager.getPreferenceScreen(); 1301 } 1302 return null; 1303 } 1304 1305 /** 1306 * Adds preferences from activities that match the given {@link Intent}. 1307 * 1308 * @param intent The {@link Intent} to query activities. 1309 * 1310 * @deprecated This function is not relevant for a modern fragment-based 1311 * PreferenceActivity. 1312 */ 1313 @Deprecated 1314 public void addPreferencesFromIntent(Intent intent) { 1315 requirePreferenceManager(); 1316 1317 setPreferenceScreen(mPreferenceManager.inflateFromIntent(intent, getPreferenceScreen())); 1318 } 1319 1320 /** 1321 * Inflates the given XML resource and adds the preference hierarchy to the current 1322 * preference hierarchy. 1323 * 1324 * @param preferencesResId The XML resource ID to inflate. 1325 * 1326 * @deprecated This function is not relevant for a modern fragment-based 1327 * PreferenceActivity. 1328 */ 1329 @Deprecated 1330 public void addPreferencesFromResource(int preferencesResId) { 1331 requirePreferenceManager(); 1332 1333 setPreferenceScreen(mPreferenceManager.inflateFromResource(this, preferencesResId, 1334 getPreferenceScreen())); 1335 } 1336 1337 /** 1338 * {@inheritDoc} 1339 * 1340 * @deprecated This function is not relevant for a modern fragment-based 1341 * PreferenceActivity. 1342 */ 1343 @Deprecated 1344 public boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference) { 1345 return false; 1346 } 1347 1348 /** 1349 * Finds a {@link Preference} based on its key. 1350 * 1351 * @param key The key of the preference to retrieve. 1352 * @return The {@link Preference} with the key, or null. 1353 * @see PreferenceGroup#findPreference(CharSequence) 1354 * 1355 * @deprecated This function is not relevant for a modern fragment-based 1356 * PreferenceActivity. 1357 */ 1358 @Deprecated 1359 public Preference findPreference(CharSequence key) { 1360 1361 if (mPreferenceManager == null) { 1362 return null; 1363 } 1364 1365 return mPreferenceManager.findPreference(key); 1366 } 1367 1368 @Override 1369 protected void onNewIntent(Intent intent) { 1370 if (mPreferenceManager != null) { 1371 mPreferenceManager.dispatchNewIntent(intent); 1372 } 1373 } 1374 1375 // give subclasses access to the Next button 1376 /** @hide */ 1377 protected boolean hasNextButton() { 1378 return mNextButton != null; 1379 } 1380 /** @hide */ 1381 protected Button getNextButton() { 1382 return mNextButton; 1383 } 1384} 1385