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