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