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