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