ActionBar.java revision fc35dfd513677ca01e8d4950ff9faa4ed19e65fe
1/* 2 * Copyright (C) 2010 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.app; 18 19import android.annotation.IntDef; 20import android.annotation.NonNull; 21import android.annotation.Nullable; 22import android.content.Context; 23import android.content.res.TypedArray; 24import android.graphics.drawable.Drawable; 25import android.util.AttributeSet; 26import android.view.Gravity; 27import android.view.View; 28import android.view.ViewDebug; 29import android.view.ViewGroup; 30import android.view.ViewGroup.MarginLayoutParams; 31import android.view.Window; 32import android.widget.SpinnerAdapter; 33 34import java.lang.annotation.Retention; 35import java.lang.annotation.RetentionPolicy; 36 37/** 38 * A window feature at the top of the activity that may display the activity title, navigation 39 * modes, and other interactive items. 40 * <p>Beginning with Android 3.0 (API level 11), the action bar appears at the top of an 41 * activity's window when the activity uses the system's {@link 42 * android.R.style#Theme_Holo Holo} theme (or one of its descendant themes), which is the default. 43 * You may otherwise add the action bar by calling {@link 44 * android.view.Window#requestFeature requestFeature(FEATURE_ACTION_BAR)} or by declaring it in a 45 * custom theme with the {@link android.R.styleable#Theme_windowActionBar windowActionBar} property. 46 * <p>By default, the action bar shows the application icon on 47 * the left, followed by the activity title. If your activity has an options menu, you can make 48 * select items accessible directly from the action bar as "action items". You can also 49 * modify various characteristics of the action bar or remove it completely.</p> 50 * <p>From your activity, you can retrieve an instance of {@link ActionBar} by calling {@link 51 * android.app.Activity#getActionBar getActionBar()}.</p> 52 * <p>In some cases, the action bar may be overlayed by another bar that enables contextual actions, 53 * using an {@link android.view.ActionMode}. For example, when the user selects one or more items in 54 * your activity, you can enable an action mode that offers actions specific to the selected 55 * items, with a UI that temporarily replaces the action bar. Although the UI may occupy the 56 * same space, the {@link android.view.ActionMode} APIs are distinct and independent from those for 57 * {@link ActionBar}. 58 * <div class="special reference"> 59 * <h3>Developer Guides</h3> 60 * <p>For information about how to use the action bar, including how to add action items, navigation 61 * modes and more, read the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action 62 * Bar</a> developer guide.</p> 63 * </div> 64 */ 65public abstract class ActionBar { 66 /** @hide */ 67 @Retention(RetentionPolicy.SOURCE) 68 @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS}) 69 public @interface NavigationMode {} 70 71 /** 72 * Standard navigation mode. Consists of either a logo or icon 73 * and title text with an optional subtitle. Clicking any of these elements 74 * will dispatch onOptionsItemSelected to the host Activity with 75 * a MenuItem with item ID android.R.id.home. 76 * 77 * @deprecated Action bar navigation modes are deprecated and not supported by inline 78 * toolbar action bars. Consider using other 79 * <a href="http://developer.android.com/design/patterns/navigation.html">common 80 * navigation patterns</a> instead. 81 */ 82 public static final int NAVIGATION_MODE_STANDARD = 0; 83 84 /** 85 * List navigation mode. Instead of static title text this mode 86 * presents a list menu for navigation within the activity. 87 * e.g. this might be presented to the user as a dropdown list. 88 * 89 * @deprecated Action bar navigation modes are deprecated and not supported by inline 90 * toolbar action bars. Consider using other 91 * <a href="http://developer.android.com/design/patterns/navigation.html">common 92 * navigation patterns</a> instead. 93 */ 94 public static final int NAVIGATION_MODE_LIST = 1; 95 96 /** 97 * Tab navigation mode. Instead of static title text this mode 98 * presents a series of tabs for navigation within the activity. 99 * 100 * @deprecated Action bar navigation modes are deprecated and not supported by inline 101 * toolbar action bars. Consider using other 102 * <a href="http://developer.android.com/design/patterns/navigation.html">common 103 * navigation patterns</a> instead. 104 */ 105 public static final int NAVIGATION_MODE_TABS = 2; 106 107 /** @hide */ 108 @Retention(RetentionPolicy.SOURCE) 109 @IntDef(flag = true, 110 value = { 111 DISPLAY_USE_LOGO, 112 DISPLAY_SHOW_HOME, 113 DISPLAY_HOME_AS_UP, 114 DISPLAY_SHOW_TITLE, 115 DISPLAY_SHOW_CUSTOM, 116 DISPLAY_TITLE_MULTIPLE_LINES 117 }) 118 public @interface DisplayOptions {} 119 120 /** 121 * Use logo instead of icon if available. This flag will cause appropriate 122 * navigation modes to use a wider logo in place of the standard icon. 123 * 124 * @see #setDisplayOptions(int) 125 * @see #setDisplayOptions(int, int) 126 */ 127 public static final int DISPLAY_USE_LOGO = 0x1; 128 129 /** 130 * Show 'home' elements in this action bar, leaving more space for other 131 * navigation elements. This includes logo and icon. 132 * 133 * @see #setDisplayOptions(int) 134 * @see #setDisplayOptions(int, int) 135 */ 136 public static final int DISPLAY_SHOW_HOME = 0x2; 137 138 /** 139 * Display the 'home' element such that it appears as an 'up' affordance. 140 * e.g. show an arrow to the left indicating the action that will be taken. 141 * 142 * Set this flag if selecting the 'home' button in the action bar to return 143 * up by a single level in your UI rather than back to the top level or front page. 144 * 145 * <p>Setting this option will implicitly enable interaction with the home/up 146 * button. See {@link #setHomeButtonEnabled(boolean)}. 147 * 148 * @see #setDisplayOptions(int) 149 * @see #setDisplayOptions(int, int) 150 */ 151 public static final int DISPLAY_HOME_AS_UP = 0x4; 152 153 /** 154 * Show the activity title and subtitle, if present. 155 * 156 * @see #setTitle(CharSequence) 157 * @see #setTitle(int) 158 * @see #setSubtitle(CharSequence) 159 * @see #setSubtitle(int) 160 * @see #setDisplayOptions(int) 161 * @see #setDisplayOptions(int, int) 162 */ 163 public static final int DISPLAY_SHOW_TITLE = 0x8; 164 165 /** 166 * Show the custom view if one has been set. 167 * @see #setCustomView(View) 168 * @see #setDisplayOptions(int) 169 * @see #setDisplayOptions(int, int) 170 */ 171 public static final int DISPLAY_SHOW_CUSTOM = 0x10; 172 173 /** 174 * Allow the title to wrap onto multiple lines if space is available 175 * @hide pending API approval 176 */ 177 public static final int DISPLAY_TITLE_MULTIPLE_LINES = 0x20; 178 179 /** 180 * Set the action bar into custom navigation mode, supplying a view 181 * for custom navigation. 182 * 183 * Custom navigation views appear between the application icon and 184 * any action buttons and may use any space available there. Common 185 * use cases for custom navigation views might include an auto-suggesting 186 * address bar for a browser or other navigation mechanisms that do not 187 * translate well to provided navigation modes. 188 * 189 * @param view Custom navigation view to place in the ActionBar. 190 */ 191 public abstract void setCustomView(View view); 192 193 /** 194 * Set the action bar into custom navigation mode, supplying a view 195 * for custom navigation. 196 * 197 * <p>Custom navigation views appear between the application icon and 198 * any action buttons and may use any space available there. Common 199 * use cases for custom navigation views might include an auto-suggesting 200 * address bar for a browser or other navigation mechanisms that do not 201 * translate well to provided navigation modes.</p> 202 * 203 * <p>The display option {@link #DISPLAY_SHOW_CUSTOM} must be set for 204 * the custom view to be displayed.</p> 205 * 206 * @param view Custom navigation view to place in the ActionBar. 207 * @param layoutParams How this custom view should layout in the bar. 208 * 209 * @see #setDisplayOptions(int, int) 210 */ 211 public abstract void setCustomView(View view, LayoutParams layoutParams); 212 213 /** 214 * Set the action bar into custom navigation mode, supplying a view 215 * for custom navigation. 216 * 217 * <p>Custom navigation views appear between the application icon and 218 * any action buttons and may use any space available there. Common 219 * use cases for custom navigation views might include an auto-suggesting 220 * address bar for a browser or other navigation mechanisms that do not 221 * translate well to provided navigation modes.</p> 222 * 223 * <p>The display option {@link #DISPLAY_SHOW_CUSTOM} must be set for 224 * the custom view to be displayed.</p> 225 * 226 * @param resId Resource ID of a layout to inflate into the ActionBar. 227 * 228 * @see #setDisplayOptions(int, int) 229 */ 230 public abstract void setCustomView(int resId); 231 232 /** 233 * Set the icon to display in the 'home' section of the action bar. 234 * The action bar will use an icon specified by its style or the 235 * activity icon by default. 236 * 237 * Whether the home section shows an icon or logo is controlled 238 * by the display option {@link #DISPLAY_USE_LOGO}. 239 * 240 * @param resId Resource ID of a drawable to show as an icon. 241 * 242 * @see #setDisplayUseLogoEnabled(boolean) 243 * @see #setDisplayShowHomeEnabled(boolean) 244 */ 245 public abstract void setIcon(int resId); 246 247 /** 248 * Set the icon to display in the 'home' section of the action bar. 249 * The action bar will use an icon specified by its style or the 250 * activity icon by default. 251 * 252 * Whether the home section shows an icon or logo is controlled 253 * by the display option {@link #DISPLAY_USE_LOGO}. 254 * 255 * @param icon Drawable to show as an icon. 256 * 257 * @see #setDisplayUseLogoEnabled(boolean) 258 * @see #setDisplayShowHomeEnabled(boolean) 259 */ 260 public abstract void setIcon(Drawable icon); 261 262 /** 263 * Set the logo to display in the 'home' section of the action bar. 264 * The action bar will use a logo specified by its style or the 265 * activity logo by default. 266 * 267 * Whether the home section shows an icon or logo is controlled 268 * by the display option {@link #DISPLAY_USE_LOGO}. 269 * 270 * @param resId Resource ID of a drawable to show as a logo. 271 * 272 * @see #setDisplayUseLogoEnabled(boolean) 273 * @see #setDisplayShowHomeEnabled(boolean) 274 */ 275 public abstract void setLogo(int resId); 276 277 /** 278 * Set the logo to display in the 'home' section of the action bar. 279 * The action bar will use a logo specified by its style or the 280 * activity logo by default. 281 * 282 * Whether the home section shows an icon or logo is controlled 283 * by the display option {@link #DISPLAY_USE_LOGO}. 284 * 285 * @param logo Drawable to show as a logo. 286 * 287 * @see #setDisplayUseLogoEnabled(boolean) 288 * @see #setDisplayShowHomeEnabled(boolean) 289 */ 290 public abstract void setLogo(Drawable logo); 291 292 /** 293 * Set the adapter and navigation callback for list navigation mode. 294 * 295 * The supplied adapter will provide views for the expanded list as well as 296 * the currently selected item. (These may be displayed differently.) 297 * 298 * The supplied OnNavigationListener will alert the application when the user 299 * changes the current list selection. 300 * 301 * @param adapter An adapter that will provide views both to display 302 * the current navigation selection and populate views 303 * within the dropdown navigation menu. 304 * @param callback An OnNavigationListener that will receive events when the user 305 * selects a navigation item. 306 * 307 * @deprecated Action bar navigation modes are deprecated and not supported by inline 308 * toolbar action bars. Consider using other 309 * <a href="http://developer.android.com/design/patterns/navigation.html">common 310 * navigation patterns</a> instead. 311 */ 312 public abstract void setListNavigationCallbacks(SpinnerAdapter adapter, 313 OnNavigationListener callback); 314 315 /** 316 * Set the selected navigation item in list or tabbed navigation modes. 317 * 318 * @param position Position of the item to select. 319 * 320 * @deprecated Action bar navigation modes are deprecated and not supported by inline 321 * toolbar action bars. Consider using other 322 * <a href="http://developer.android.com/design/patterns/navigation.html">common 323 * navigation patterns</a> instead. 324 */ 325 public abstract void setSelectedNavigationItem(int position); 326 327 /** 328 * Get the position of the selected navigation item in list or tabbed navigation modes. 329 * 330 * @return Position of the selected item. 331 * 332 * @deprecated Action bar navigation modes are deprecated and not supported by inline 333 * toolbar action bars. Consider using other 334 * <a href="http://developer.android.com/design/patterns/navigation.html">common 335 * navigation patterns</a> instead. 336 */ 337 public abstract int getSelectedNavigationIndex(); 338 339 /** 340 * Get the number of navigation items present in the current navigation mode. 341 * 342 * @return Number of navigation items. 343 * 344 * @deprecated Action bar navigation modes are deprecated and not supported by inline 345 * toolbar action bars. Consider using other 346 * <a href="http://developer.android.com/design/patterns/navigation.html">common 347 * navigation patterns</a> instead. 348 */ 349 public abstract int getNavigationItemCount(); 350 351 /** 352 * Set the action bar's title. This will only be displayed if 353 * {@link #DISPLAY_SHOW_TITLE} is set. 354 * 355 * @param title Title to set 356 * 357 * @see #setTitle(int) 358 * @see #setDisplayOptions(int, int) 359 */ 360 public abstract void setTitle(CharSequence title); 361 362 /** 363 * Set the action bar's title. This will only be displayed if 364 * {@link #DISPLAY_SHOW_TITLE} is set. 365 * 366 * @param resId Resource ID of title string to set 367 * 368 * @see #setTitle(CharSequence) 369 * @see #setDisplayOptions(int, int) 370 */ 371 public abstract void setTitle(int resId); 372 373 /** 374 * Set the action bar's subtitle. This will only be displayed if 375 * {@link #DISPLAY_SHOW_TITLE} is set. Set to null to disable the 376 * subtitle entirely. 377 * 378 * @param subtitle Subtitle to set 379 * 380 * @see #setSubtitle(int) 381 * @see #setDisplayOptions(int, int) 382 */ 383 public abstract void setSubtitle(CharSequence subtitle); 384 385 /** 386 * Set the action bar's subtitle. This will only be displayed if 387 * {@link #DISPLAY_SHOW_TITLE} is set. 388 * 389 * @param resId Resource ID of subtitle string to set 390 * 391 * @see #setSubtitle(CharSequence) 392 * @see #setDisplayOptions(int, int) 393 */ 394 public abstract void setSubtitle(int resId); 395 396 /** 397 * Set display options. This changes all display option bits at once. To change 398 * a limited subset of display options, see {@link #setDisplayOptions(int, int)}. 399 * 400 * @param options A combination of the bits defined by the DISPLAY_ constants 401 * defined in ActionBar. 402 */ 403 public abstract void setDisplayOptions(@DisplayOptions int options); 404 405 /** 406 * Set selected display options. Only the options specified by mask will be changed. 407 * To change all display option bits at once, see {@link #setDisplayOptions(int)}. 408 * 409 * <p>Example: setDisplayOptions(0, DISPLAY_SHOW_HOME) will disable the 410 * {@link #DISPLAY_SHOW_HOME} option. 411 * setDisplayOptions(DISPLAY_SHOW_HOME, DISPLAY_SHOW_HOME | DISPLAY_USE_LOGO) 412 * will enable {@link #DISPLAY_SHOW_HOME} and disable {@link #DISPLAY_USE_LOGO}. 413 * 414 * @param options A combination of the bits defined by the DISPLAY_ constants 415 * defined in ActionBar. 416 * @param mask A bit mask declaring which display options should be changed. 417 */ 418 public abstract void setDisplayOptions(@DisplayOptions int options, @DisplayOptions int mask); 419 420 /** 421 * Set whether to display the activity logo rather than the activity icon. 422 * A logo is often a wider, more detailed image. 423 * 424 * <p>To set several display options at once, see the setDisplayOptions methods. 425 * 426 * @param useLogo true to use the activity logo, false to use the activity icon. 427 * 428 * @see #setDisplayOptions(int) 429 * @see #setDisplayOptions(int, int) 430 */ 431 public abstract void setDisplayUseLogoEnabled(boolean useLogo); 432 433 /** 434 * Set whether to include the application home affordance in the action bar. 435 * Home is presented as either an activity icon or logo. 436 * 437 * <p>To set several display options at once, see the setDisplayOptions methods. 438 * 439 * @param showHome true to show home, false otherwise. 440 * 441 * @see #setDisplayOptions(int) 442 * @see #setDisplayOptions(int, int) 443 */ 444 public abstract void setDisplayShowHomeEnabled(boolean showHome); 445 446 /** 447 * Set whether home should be displayed as an "up" affordance. 448 * Set this to true if selecting "home" returns up by a single level in your UI 449 * rather than back to the top level or front page. 450 * 451 * <p>To set several display options at once, see the setDisplayOptions methods. 452 * 453 * @param showHomeAsUp true to show the user that selecting home will return one 454 * level up rather than to the top level of the app. 455 * 456 * @see #setDisplayOptions(int) 457 * @see #setDisplayOptions(int, int) 458 */ 459 public abstract void setDisplayHomeAsUpEnabled(boolean showHomeAsUp); 460 461 /** 462 * Set whether an activity title/subtitle should be displayed. 463 * 464 * <p>To set several display options at once, see the setDisplayOptions methods. 465 * 466 * @param showTitle true to display a title/subtitle if present. 467 * 468 * @see #setDisplayOptions(int) 469 * @see #setDisplayOptions(int, int) 470 */ 471 public abstract void setDisplayShowTitleEnabled(boolean showTitle); 472 473 /** 474 * Set whether a custom view should be displayed, if set. 475 * 476 * <p>To set several display options at once, see the setDisplayOptions methods. 477 * 478 * @param showCustom true if the currently set custom view should be displayed, false otherwise. 479 * 480 * @see #setDisplayOptions(int) 481 * @see #setDisplayOptions(int, int) 482 */ 483 public abstract void setDisplayShowCustomEnabled(boolean showCustom); 484 485 /** 486 * Set the ActionBar's background. This will be used for the primary 487 * action bar. 488 * 489 * @param d Background drawable 490 * @see #setStackedBackgroundDrawable(Drawable) 491 * @see #setSplitBackgroundDrawable(Drawable) 492 */ 493 public abstract void setBackgroundDrawable(@Nullable Drawable d); 494 495 /** 496 * Set the ActionBar's stacked background. This will appear 497 * in the second row/stacked bar on some devices and configurations. 498 * 499 * @param d Background drawable for the stacked row 500 */ 501 public void setStackedBackgroundDrawable(Drawable d) { } 502 503 /** 504 * Set the ActionBar's split background. This will appear in 505 * the split action bar containing menu-provided action buttons 506 * on some devices and configurations. 507 * <p>You can enable split action bar with {@link android.R.attr#uiOptions} 508 * 509 * @param d Background drawable for the split bar 510 */ 511 public void setSplitBackgroundDrawable(Drawable d) { } 512 513 /** 514 * @return The current custom view. 515 */ 516 public abstract View getCustomView(); 517 518 /** 519 * Returns the current ActionBar title in standard mode. 520 * Returns null if {@link #getNavigationMode()} would not return 521 * {@link #NAVIGATION_MODE_STANDARD}. 522 * 523 * @return The current ActionBar title or null. 524 */ 525 public abstract CharSequence getTitle(); 526 527 /** 528 * Returns the current ActionBar subtitle in standard mode. 529 * Returns null if {@link #getNavigationMode()} would not return 530 * {@link #NAVIGATION_MODE_STANDARD}. 531 * 532 * @return The current ActionBar subtitle or null. 533 */ 534 public abstract CharSequence getSubtitle(); 535 536 /** 537 * Returns the current navigation mode. The result will be one of: 538 * <ul> 539 * <li>{@link #NAVIGATION_MODE_STANDARD}</li> 540 * <li>{@link #NAVIGATION_MODE_LIST}</li> 541 * <li>{@link #NAVIGATION_MODE_TABS}</li> 542 * </ul> 543 * 544 * @return The current navigation mode. 545 * 546 * @deprecated Action bar navigation modes are deprecated and not supported by inline 547 * toolbar action bars. Consider using other 548 * <a href="http://developer.android.com/design/patterns/navigation.html">common 549 * navigation patterns</a> instead. 550 */ 551 @NavigationMode 552 public abstract int getNavigationMode(); 553 554 /** 555 * Set the current navigation mode. 556 * 557 * @param mode The new mode to set. 558 * @see #NAVIGATION_MODE_STANDARD 559 * @see #NAVIGATION_MODE_LIST 560 * @see #NAVIGATION_MODE_TABS 561 * 562 * @deprecated Action bar navigation modes are deprecated and not supported by inline 563 * toolbar action bars. Consider using other 564 * <a href="http://developer.android.com/design/patterns/navigation.html">common 565 * navigation patterns</a> instead. 566 */ 567 public abstract void setNavigationMode(@NavigationMode int mode); 568 569 /** 570 * @return The current set of display options. 571 */ 572 public abstract int getDisplayOptions(); 573 574 /** 575 * Create and return a new {@link Tab}. 576 * This tab will not be included in the action bar until it is added. 577 * 578 * <p>Very often tabs will be used to switch between {@link Fragment} 579 * objects. Here is a typical implementation of such tabs:</p> 580 * 581 * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentTabs.java 582 * complete} 583 * 584 * @return A new Tab 585 * 586 * @see #addTab(Tab) 587 * 588 * @deprecated Action bar navigation modes are deprecated and not supported by inline 589 * toolbar action bars. Consider using other 590 * <a href="http://developer.android.com/design/patterns/navigation.html">common 591 * navigation patterns</a> instead. 592 */ 593 public abstract Tab newTab(); 594 595 /** 596 * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list. 597 * If this is the first tab to be added it will become the selected tab. 598 * 599 * @param tab Tab to add 600 * 601 * @deprecated Action bar navigation modes are deprecated and not supported by inline 602 * toolbar action bars. Consider using other 603 * <a href="http://developer.android.com/design/patterns/navigation.html">common 604 * navigation patterns</a> instead. 605 */ 606 public abstract void addTab(Tab tab); 607 608 /** 609 * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list. 610 * 611 * @param tab Tab to add 612 * @param setSelected True if the added tab should become the selected tab. 613 * 614 * @deprecated Action bar navigation modes are deprecated and not supported by inline 615 * toolbar action bars. Consider using other 616 * <a href="http://developer.android.com/design/patterns/navigation.html">common 617 * navigation patterns</a> instead. 618 */ 619 public abstract void addTab(Tab tab, boolean setSelected); 620 621 /** 622 * Add a tab for use in tabbed navigation mode. The tab will be inserted at 623 * <code>position</code>. If this is the first tab to be added it will become 624 * the selected tab. 625 * 626 * @param tab The tab to add 627 * @param position The new position of the tab 628 * 629 * @deprecated Action bar navigation modes are deprecated and not supported by inline 630 * toolbar action bars. Consider using other 631 * <a href="http://developer.android.com/design/patterns/navigation.html">common 632 * navigation patterns</a> instead. 633 */ 634 public abstract void addTab(Tab tab, int position); 635 636 /** 637 * Add a tab for use in tabbed navigation mode. The tab will be insterted at 638 * <code>position</code>. 639 * 640 * @param tab The tab to add 641 * @param position The new position of the tab 642 * @param setSelected True if the added tab should become the selected tab. 643 * 644 * @deprecated Action bar navigation modes are deprecated and not supported by inline 645 * toolbar action bars. Consider using other 646 * <a href="http://developer.android.com/design/patterns/navigation.html">common 647 * navigation patterns</a> instead. 648 */ 649 public abstract void addTab(Tab tab, int position, boolean setSelected); 650 651 /** 652 * Remove a tab from the action bar. If the removed tab was selected it will be deselected 653 * and another tab will be selected if present. 654 * 655 * @param tab The tab to remove 656 * 657 * @deprecated Action bar navigation modes are deprecated and not supported by inline 658 * toolbar action bars. Consider using other 659 * <a href="http://developer.android.com/design/patterns/navigation.html">common 660 * navigation patterns</a> instead. 661 */ 662 public abstract void removeTab(Tab tab); 663 664 /** 665 * Remove a tab from the action bar. If the removed tab was selected it will be deselected 666 * and another tab will be selected if present. 667 * 668 * @param position Position of the tab to remove 669 * 670 * @deprecated Action bar navigation modes are deprecated and not supported by inline 671 * toolbar action bars. Consider using other 672 * <a href="http://developer.android.com/design/patterns/navigation.html">common 673 * navigation patterns</a> instead. 674 */ 675 public abstract void removeTabAt(int position); 676 677 /** 678 * Remove all tabs from the action bar and deselect the current tab. 679 * 680 * @deprecated Action bar navigation modes are deprecated and not supported by inline 681 * toolbar action bars. Consider using other 682 * <a href="http://developer.android.com/design/patterns/navigation.html">common 683 * navigation patterns</a> instead. 684 */ 685 public abstract void removeAllTabs(); 686 687 /** 688 * Select the specified tab. If it is not a child of this action bar it will be added. 689 * 690 * <p>Note: If you want to select by index, use {@link #setSelectedNavigationItem(int)}.</p> 691 * 692 * @param tab Tab to select 693 * 694 * @deprecated Action bar navigation modes are deprecated and not supported by inline 695 * toolbar action bars. Consider using other 696 * <a href="http://developer.android.com/design/patterns/navigation.html">common 697 * navigation patterns</a> instead. 698 */ 699 public abstract void selectTab(Tab tab); 700 701 /** 702 * Returns the currently selected tab if in tabbed navigation mode and there is at least 703 * one tab present. 704 * 705 * @return The currently selected tab or null 706 * 707 * @deprecated Action bar navigation modes are deprecated and not supported by inline 708 * toolbar action bars. Consider using other 709 * <a href="http://developer.android.com/design/patterns/navigation.html">common 710 * navigation patterns</a> instead. 711 */ 712 public abstract Tab getSelectedTab(); 713 714 /** 715 * Returns the tab at the specified index. 716 * 717 * @param index Index value in the range 0-get 718 * @return 719 * 720 * @deprecated Action bar navigation modes are deprecated and not supported by inline 721 * toolbar action bars. Consider using other 722 * <a href="http://developer.android.com/design/patterns/navigation.html">common 723 * navigation patterns</a> instead. 724 */ 725 public abstract Tab getTabAt(int index); 726 727 /** 728 * Returns the number of tabs currently registered with the action bar. 729 * @return Tab count 730 * 731 * @deprecated Action bar navigation modes are deprecated and not supported by inline 732 * toolbar action bars. Consider using other 733 * <a href="http://developer.android.com/design/patterns/navigation.html">common 734 * navigation patterns</a> instead. 735 */ 736 public abstract int getTabCount(); 737 738 /** 739 * Retrieve the current height of the ActionBar. 740 * 741 * @return The ActionBar's height 742 */ 743 public abstract int getHeight(); 744 745 /** 746 * Show the ActionBar if it is not currently showing. 747 * If the window hosting the ActionBar does not have the feature 748 * {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application 749 * content to fit the new space available. 750 * 751 * <p>If you are hiding the ActionBar through 752 * {@link View#SYSTEM_UI_FLAG_FULLSCREEN View.SYSTEM_UI_FLAG_FULLSCREEN}, 753 * you should not call this function directly. 754 */ 755 public abstract void show(); 756 757 /** 758 * Hide the ActionBar if it is currently showing. 759 * If the window hosting the ActionBar does not have the feature 760 * {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application 761 * content to fit the new space available. 762 * 763 * <p>Instead of calling this function directly, you can also cause an 764 * ActionBar using the overlay feature to hide through 765 * {@link View#SYSTEM_UI_FLAG_FULLSCREEN View.SYSTEM_UI_FLAG_FULLSCREEN}. 766 * Hiding the ActionBar through this system UI flag allows you to more 767 * seamlessly hide it in conjunction with other screen decorations. 768 */ 769 public abstract void hide(); 770 771 /** 772 * @return <code>true</code> if the ActionBar is showing, <code>false</code> otherwise. 773 */ 774 public abstract boolean isShowing(); 775 776 /** 777 * Add a listener that will respond to menu visibility change events. 778 * 779 * @param listener The new listener to add 780 */ 781 public abstract void addOnMenuVisibilityListener(OnMenuVisibilityListener listener); 782 783 /** 784 * Remove a menu visibility listener. This listener will no longer receive menu 785 * visibility change events. 786 * 787 * @param listener A listener to remove that was previously added 788 */ 789 public abstract void removeOnMenuVisibilityListener(OnMenuVisibilityListener listener); 790 791 /** 792 * Enable or disable the "home" button in the corner of the action bar. (Note that this 793 * is the application home/up affordance on the action bar, not the systemwide home 794 * button.) 795 * 796 * <p>This defaults to true for packages targeting < API 14. For packages targeting 797 * API 14 or greater, the application should call this method to enable interaction 798 * with the home/up affordance. 799 * 800 * <p>Setting the {@link #DISPLAY_HOME_AS_UP} display option will automatically enable 801 * the home button. 802 * 803 * @param enabled true to enable the home button, false to disable the home button. 804 */ 805 public void setHomeButtonEnabled(boolean enabled) { } 806 807 /** 808 * Returns a {@link Context} with an appropriate theme for creating views that 809 * will appear in the action bar. If you are inflating or instantiating custom views 810 * that will appear in an action bar, you should use the Context returned by this method. 811 * (This includes adapters used for list navigation mode.) 812 * This will ensure that views contrast properly against the action bar. 813 * 814 * @return A themed Context for creating views 815 */ 816 public Context getThemedContext() { return null; } 817 818 /** 819 * Returns true if the Title field has been truncated during layout for lack 820 * of available space. 821 * 822 * @return true if the Title field has been truncated 823 * @hide pending API approval 824 */ 825 public boolean isTitleTruncated() { return false; } 826 827 /** 828 * Set an alternate drawable to display next to the icon/logo/title 829 * when {@link #DISPLAY_HOME_AS_UP} is enabled. This can be useful if you are using 830 * this mode to display an alternate selection for up navigation, such as a sliding drawer. 831 * 832 * <p>If you pass <code>null</code> to this method, the default drawable from the theme 833 * will be used.</p> 834 * 835 * <p>If you implement alternate or intermediate behavior around Up, you should also 836 * call {@link #setHomeActionContentDescription(int) setHomeActionContentDescription()} 837 * to provide a correct description of the action for accessibility support.</p> 838 * 839 * @param indicator A drawable to use for the up indicator, or null to use the theme's default 840 * 841 * @see #setDisplayOptions(int, int) 842 * @see #setDisplayHomeAsUpEnabled(boolean) 843 * @see #setHomeActionContentDescription(int) 844 */ 845 public void setHomeAsUpIndicator(Drawable indicator) { } 846 847 /** 848 * Set an alternate drawable to display next to the icon/logo/title 849 * when {@link #DISPLAY_HOME_AS_UP} is enabled. This can be useful if you are using 850 * this mode to display an alternate selection for up navigation, such as a sliding drawer. 851 * 852 * <p>If you pass <code>0</code> to this method, the default drawable from the theme 853 * will be used.</p> 854 * 855 * <p>If you implement alternate or intermediate behavior around Up, you should also 856 * call {@link #setHomeActionContentDescription(int) setHomeActionContentDescription()} 857 * to provide a correct description of the action for accessibility support.</p> 858 * 859 * @param resId Resource ID of a drawable to use for the up indicator, or null 860 * to use the theme's default 861 * 862 * @see #setDisplayOptions(int, int) 863 * @see #setDisplayHomeAsUpEnabled(boolean) 864 * @see #setHomeActionContentDescription(int) 865 */ 866 public void setHomeAsUpIndicator(int resId) { } 867 868 /** 869 * Set an alternate description for the Home/Up action, when enabled. 870 * 871 * <p>This description is commonly used for accessibility/screen readers when 872 * the Home action is enabled. (See {@link #setDisplayHomeAsUpEnabled(boolean)}.) 873 * Examples of this are, "Navigate Home" or "Navigate Up" depending on the 874 * {@link #DISPLAY_HOME_AS_UP} display option. If you have changed the home-as-up 875 * indicator using {@link #setHomeAsUpIndicator(int)} to indicate more specific 876 * functionality such as a sliding drawer, you should also set this to accurately 877 * describe the action.</p> 878 * 879 * <p>Setting this to <code>null</code> will use the system default description.</p> 880 * 881 * @param description New description for the Home action when enabled 882 * @see #setHomeAsUpIndicator(int) 883 * @see #setHomeAsUpIndicator(android.graphics.drawable.Drawable) 884 */ 885 public void setHomeActionContentDescription(CharSequence description) { } 886 887 /** 888 * Set an alternate description for the Home/Up action, when enabled. 889 * 890 * <p>This description is commonly used for accessibility/screen readers when 891 * the Home action is enabled. (See {@link #setDisplayHomeAsUpEnabled(boolean)}.) 892 * Examples of this are, "Navigate Home" or "Navigate Up" depending on the 893 * {@link #DISPLAY_HOME_AS_UP} display option. If you have changed the home-as-up 894 * indicator using {@link #setHomeAsUpIndicator(int)} to indicate more specific 895 * functionality such as a sliding drawer, you should also set this to accurately 896 * describe the action.</p> 897 * 898 * <p>Setting this to <code>0</code> will use the system default description.</p> 899 * 900 * @param resId Resource ID of a string to use as the new description 901 * for the Home action when enabled 902 * @see #setHomeAsUpIndicator(int) 903 * @see #setHomeAsUpIndicator(android.graphics.drawable.Drawable) 904 */ 905 public void setHomeActionContentDescription(int resId) { } 906 907 /** 908 * Listener interface for ActionBar navigation events. 909 * 910 * @deprecated Action bar navigation modes are deprecated and not supported by inline 911 * toolbar action bars. Consider using other 912 * <a href="http://developer.android.com/design/patterns/navigation.html">common 913 * navigation patterns</a> instead. 914 */ 915 public interface OnNavigationListener { 916 /** 917 * This method is called whenever a navigation item in your action bar 918 * is selected. 919 * 920 * @param itemPosition Position of the item clicked. 921 * @param itemId ID of the item clicked. 922 * @return True if the event was handled, false otherwise. 923 */ 924 public boolean onNavigationItemSelected(int itemPosition, long itemId); 925 } 926 927 /** 928 * Listener for receiving events when action bar menus are shown or hidden. 929 */ 930 public interface OnMenuVisibilityListener { 931 /** 932 * Called when an action bar menu is shown or hidden. Applications may want to use 933 * this to tune auto-hiding behavior for the action bar or pause/resume video playback, 934 * gameplay, or other activity within the main content area. 935 * 936 * @param isVisible True if an action bar menu is now visible, false if no action bar 937 * menus are visible. 938 */ 939 public void onMenuVisibilityChanged(boolean isVisible); 940 } 941 942 /** 943 * A tab in the action bar. 944 * 945 * <p>Tabs manage the hiding and showing of {@link Fragment}s. 946 * 947 * @deprecated Action bar navigation modes are deprecated and not supported by inline 948 * toolbar action bars. Consider using other 949 * <a href="http://developer.android.com/design/patterns/navigation.html">common 950 * navigation patterns</a> instead. 951 */ 952 public static abstract class Tab { 953 /** 954 * An invalid position for a tab. 955 * 956 * @see #getPosition() 957 */ 958 public static final int INVALID_POSITION = -1; 959 960 /** 961 * Return the current position of this tab in the action bar. 962 * 963 * @return Current position, or {@link #INVALID_POSITION} if this tab is not currently in 964 * the action bar. 965 */ 966 public abstract int getPosition(); 967 968 /** 969 * Return the icon associated with this tab. 970 * 971 * @return The tab's icon 972 */ 973 public abstract Drawable getIcon(); 974 975 /** 976 * Return the text of this tab. 977 * 978 * @return The tab's text 979 */ 980 public abstract CharSequence getText(); 981 982 /** 983 * Set the icon displayed on this tab. 984 * 985 * @param icon The drawable to use as an icon 986 * @return The current instance for call chaining 987 */ 988 public abstract Tab setIcon(Drawable icon); 989 990 /** 991 * Set the icon displayed on this tab. 992 * 993 * @param resId Resource ID referring to the drawable to use as an icon 994 * @return The current instance for call chaining 995 */ 996 public abstract Tab setIcon(int resId); 997 998 /** 999 * Set the text displayed on this tab. Text may be truncated if there is not 1000 * room to display the entire string. 1001 * 1002 * @param text The text to display 1003 * @return The current instance for call chaining 1004 */ 1005 public abstract Tab setText(CharSequence text); 1006 1007 /** 1008 * Set the text displayed on this tab. Text may be truncated if there is not 1009 * room to display the entire string. 1010 * 1011 * @param resId A resource ID referring to the text that should be displayed 1012 * @return The current instance for call chaining 1013 */ 1014 public abstract Tab setText(int resId); 1015 1016 /** 1017 * Set a custom view to be used for this tab. This overrides values set by 1018 * {@link #setText(CharSequence)} and {@link #setIcon(Drawable)}. 1019 * 1020 * @param view Custom view to be used as a tab. 1021 * @return The current instance for call chaining 1022 */ 1023 public abstract Tab setCustomView(View view); 1024 1025 /** 1026 * Set a custom view to be used for this tab. This overrides values set by 1027 * {@link #setText(CharSequence)} and {@link #setIcon(Drawable)}. 1028 * 1029 * @param layoutResId A layout resource to inflate and use as a custom tab view 1030 * @return The current instance for call chaining 1031 */ 1032 public abstract Tab setCustomView(int layoutResId); 1033 1034 /** 1035 * Retrieve a previously set custom view for this tab. 1036 * 1037 * @return The custom view set by {@link #setCustomView(View)}. 1038 */ 1039 public abstract View getCustomView(); 1040 1041 /** 1042 * Give this Tab an arbitrary object to hold for later use. 1043 * 1044 * @param obj Object to store 1045 * @return The current instance for call chaining 1046 */ 1047 public abstract Tab setTag(Object obj); 1048 1049 /** 1050 * @return This Tab's tag object. 1051 */ 1052 public abstract Object getTag(); 1053 1054 /** 1055 * Set the {@link TabListener} that will handle switching to and from this tab. 1056 * All tabs must have a TabListener set before being added to the ActionBar. 1057 * 1058 * @param listener Listener to handle tab selection events 1059 * @return The current instance for call chaining 1060 */ 1061 public abstract Tab setTabListener(TabListener listener); 1062 1063 /** 1064 * Select this tab. Only valid if the tab has been added to the action bar. 1065 */ 1066 public abstract void select(); 1067 1068 /** 1069 * Set a description of this tab's content for use in accessibility support. 1070 * If no content description is provided the title will be used. 1071 * 1072 * @param resId A resource ID referring to the description text 1073 * @return The current instance for call chaining 1074 * @see #setContentDescription(CharSequence) 1075 * @see #getContentDescription() 1076 */ 1077 public abstract Tab setContentDescription(int resId); 1078 1079 /** 1080 * Set a description of this tab's content for use in accessibility support. 1081 * If no content description is provided the title will be used. 1082 * 1083 * @param contentDesc Description of this tab's content 1084 * @return The current instance for call chaining 1085 * @see #setContentDescription(int) 1086 * @see #getContentDescription() 1087 */ 1088 public abstract Tab setContentDescription(CharSequence contentDesc); 1089 1090 /** 1091 * Gets a brief description of this tab's content for use in accessibility support. 1092 * 1093 * @return Description of this tab's content 1094 * @see #setContentDescription(CharSequence) 1095 * @see #setContentDescription(int) 1096 */ 1097 public abstract CharSequence getContentDescription(); 1098 } 1099 1100 /** 1101 * Callback interface invoked when a tab is focused, unfocused, added, or removed. 1102 * 1103 * @deprecated Action bar navigation modes are deprecated and not supported by inline 1104 * toolbar action bars. Consider using other 1105 * <a href="http://developer.android.com/design/patterns/navigation.html">common 1106 * navigation patterns</a> instead. 1107 */ 1108 public interface TabListener { 1109 /** 1110 * Called when a tab enters the selected state. 1111 * 1112 * @param tab The tab that was selected 1113 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 1114 * during a tab switch. The previous tab's unselect and this tab's select will be 1115 * executed in a single transaction. This FragmentTransaction does not support 1116 * being added to the back stack. 1117 */ 1118 public void onTabSelected(Tab tab, FragmentTransaction ft); 1119 1120 /** 1121 * Called when a tab exits the selected state. 1122 * 1123 * @param tab The tab that was unselected 1124 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 1125 * during a tab switch. This tab's unselect and the newly selected tab's select 1126 * will be executed in a single transaction. This FragmentTransaction does not 1127 * support being added to the back stack. 1128 */ 1129 public void onTabUnselected(Tab tab, FragmentTransaction ft); 1130 1131 /** 1132 * Called when a tab that is already selected is chosen again by the user. 1133 * Some applications may use this action to return to the top level of a category. 1134 * 1135 * @param tab The tab that was reselected. 1136 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 1137 * once this method returns. This FragmentTransaction does not support 1138 * being added to the back stack. 1139 */ 1140 public void onTabReselected(Tab tab, FragmentTransaction ft); 1141 } 1142 1143 /** 1144 * Per-child layout information associated with action bar custom views. 1145 * 1146 * @attr ref android.R.styleable#ActionBar_LayoutParams_layout_gravity 1147 */ 1148 public static class LayoutParams extends MarginLayoutParams { 1149 /** 1150 * Gravity for the view associated with these LayoutParams. 1151 * 1152 * @see android.view.Gravity 1153 */ 1154 @ViewDebug.ExportedProperty(category = "layout", mapping = { 1155 @ViewDebug.IntToString(from = -1, to = "NONE"), 1156 @ViewDebug.IntToString(from = Gravity.NO_GRAVITY, to = "NONE"), 1157 @ViewDebug.IntToString(from = Gravity.TOP, to = "TOP"), 1158 @ViewDebug.IntToString(from = Gravity.BOTTOM, to = "BOTTOM"), 1159 @ViewDebug.IntToString(from = Gravity.LEFT, to = "LEFT"), 1160 @ViewDebug.IntToString(from = Gravity.RIGHT, to = "RIGHT"), 1161 @ViewDebug.IntToString(from = Gravity.START, to = "START"), 1162 @ViewDebug.IntToString(from = Gravity.END, to = "END"), 1163 @ViewDebug.IntToString(from = Gravity.CENTER_VERTICAL, to = "CENTER_VERTICAL"), 1164 @ViewDebug.IntToString(from = Gravity.FILL_VERTICAL, to = "FILL_VERTICAL"), 1165 @ViewDebug.IntToString(from = Gravity.CENTER_HORIZONTAL, to = "CENTER_HORIZONTAL"), 1166 @ViewDebug.IntToString(from = Gravity.FILL_HORIZONTAL, to = "FILL_HORIZONTAL"), 1167 @ViewDebug.IntToString(from = Gravity.CENTER, to = "CENTER"), 1168 @ViewDebug.IntToString(from = Gravity.FILL, to = "FILL") 1169 }) 1170 public int gravity = Gravity.NO_GRAVITY; 1171 1172 public LayoutParams(@NonNull Context c, AttributeSet attrs) { 1173 super(c, attrs); 1174 1175 TypedArray a = c.obtainStyledAttributes(attrs, 1176 com.android.internal.R.styleable.ActionBar_LayoutParams); 1177 gravity = a.getInt( 1178 com.android.internal.R.styleable.ActionBar_LayoutParams_layout_gravity, 1179 Gravity.NO_GRAVITY); 1180 a.recycle(); 1181 } 1182 1183 public LayoutParams(int width, int height) { 1184 super(width, height); 1185 this.gravity = Gravity.CENTER_VERTICAL | Gravity.START; 1186 } 1187 1188 public LayoutParams(int width, int height, int gravity) { 1189 super(width, height); 1190 this.gravity = gravity; 1191 } 1192 1193 public LayoutParams(int gravity) { 1194 this(WRAP_CONTENT, MATCH_PARENT, gravity); 1195 } 1196 1197 public LayoutParams(LayoutParams source) { 1198 super(source); 1199 1200 this.gravity = source.gravity; 1201 } 1202 1203 public LayoutParams(ViewGroup.LayoutParams source) { 1204 super(source); 1205 } 1206 } 1207} 1208