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