Note: This class is included in the support library for compatibility * with API level 7 and higher. If you're developing your app for API level 11 and higher * only, you should instead use the framework {@link android.app.ActionBar} class.
* *When using the support library, you can add the action bar to the top of your activity * window by extending the {@link ActionBarActivity} class and setting the activity theme to * {@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} or a similar theme. * *
By default, the action bar shows the application icon on * the left, followed by the activity title. If your activity has an options menu, you can make * select items accessible directly from the action bar as "action items". You can also * modify various characteristics of the action bar or remove it completely.
* *From your activity, you can retrieve an instance of {@link ActionBar} by calling {@link * android.support.v7.app.ActionBarActivity#getSupportActionBar}.
* *In some cases, the action bar may be overlayed by another bar that enables contextual actions, * using an {@link android.support.v7.view.ActionMode}. For example, when the user selects one or * more items in your activity, you can enable an action mode that offers actions specific to the * selected items, with a UI that temporarily replaces the action bar. Although the UI may occupy * the same space, the {@link android.support.v7.view.ActionMode} APIs are distinct and independent * from those for {@link ActionBar}. * *
For information about how to use the action bar, including how to add action items, navigation * modes and more, read the Action * Bar API guide.
*Setting this option will implicitly enable interaction with the home/up button. See {@link * #setHomeButtonEnabled(boolean)}. * * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public static final int DISPLAY_HOME_AS_UP = 0x4; /** * Show the activity title and subtitle, if present. * * @see #setTitle(CharSequence) * @see #setTitle(int) * @see #setSubtitle(CharSequence) * @see #setSubtitle(int) * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public static final int DISPLAY_SHOW_TITLE = 0x8; /** * Show the custom view if one has been set. * * @see #setCustomView(View) * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public static final int DISPLAY_SHOW_CUSTOM = 0x10; /** * Set the action bar into custom navigation mode, supplying a view for custom navigation. * * Custom navigation views appear between the application icon and any action buttons and may * use any space available there. Common use cases for custom navigation views might include an * auto-suggesting address bar for a browser or other navigation mechanisms that do not * translate well to provided navigation modes. * * @param view Custom navigation view to place in the ActionBar. */ public abstract void setCustomView(View view); /** * Set the action bar into custom navigation mode, supplying a view for custom navigation. * *
Custom navigation views appear between the application icon and any action buttons and may * use any space available there. Common use cases for custom navigation views might include an * auto-suggesting address bar for a browser or other navigation mechanisms that do not * translate well to provided navigation modes.
* *The display option {@link #DISPLAY_SHOW_CUSTOM} must be set for the custom view to be * displayed.
* * @param view Custom navigation view to place in the ActionBar. * @param layoutParams How this custom view should layout in the bar. * @see #setDisplayOptions(int, int) */ public abstract void setCustomView(View view, LayoutParams layoutParams); /** * Set the action bar into custom navigation mode, supplying a view for custom navigation. * *Custom navigation views appear between the application icon and any action buttons and may * use any space available there. Common use cases for custom navigation views might include an * auto-suggesting address bar for a browser or other navigation mechanisms that do not * translate well to provided navigation modes.
* *The display option {@link #DISPLAY_SHOW_CUSTOM} must be set for the custom view to be * displayed.
* * @param resId Resource ID of a layout to inflate into the ActionBar. * @see #setDisplayOptions(int, int) */ public abstract void setCustomView(@LayoutRes int resId); /** * Set the icon to display in the 'home' section of the action bar. The action bar will use an * icon specified by its style or the activity icon by default. * * Whether the home section shows an icon or logo is controlled by the display option {@link * #DISPLAY_USE_LOGO}. * * @param resId Resource ID of a drawable to show as an icon. * @see #setDisplayUseLogoEnabled(boolean) * @see #setDisplayShowHomeEnabled(boolean) */ public abstract void setIcon(@DrawableRes int resId); /** * Set the icon to display in the 'home' section of the action bar. The action bar will use an * icon specified by its style or the activity icon by default. * * Whether the home section shows an icon or logo is controlled by the display option {@link * #DISPLAY_USE_LOGO}. * * @param icon Drawable to show as an icon. * @see #setDisplayUseLogoEnabled(boolean) * @see #setDisplayShowHomeEnabled(boolean) */ public abstract void setIcon(Drawable icon); /** * Set the logo to display in the 'home' section of the action bar. The action bar will use a * logo specified by its style or the activity logo by default. * * Whether the home section shows an icon or logo is controlled by the display option {@link * #DISPLAY_USE_LOGO}. * * @param resId Resource ID of a drawable to show as a logo. * @see #setDisplayUseLogoEnabled(boolean) * @see #setDisplayShowHomeEnabled(boolean) */ public abstract void setLogo(@DrawableRes int resId); /** * Set the logo to display in the 'home' section of the action bar. The action bar will use a * logo specified by its style or the activity logo by default. * * Whether the home section shows an icon or logo is controlled by the display option {@link * #DISPLAY_USE_LOGO}. * * @param logo Drawable to show as a logo. * @see #setDisplayUseLogoEnabled(boolean) * @see #setDisplayShowHomeEnabled(boolean) */ public abstract void setLogo(Drawable logo); /** * Set the adapter and navigation callback for list navigation mode. * * The supplied adapter will provide views for the expanded list as well as the currently * selected item. (These may be displayed differently.) * * The supplied OnNavigationListener will alert the application when the user changes the * current list selection. * * @param adapter An adapter that will provide views both to display the current navigation * selection and populate views within the dropdown navigation menu. * @param callback An OnNavigationListener that will receive events when the user selects a * navigation item. */ public abstract void setListNavigationCallbacks(SpinnerAdapter adapter, OnNavigationListener callback); /** * Set the selected navigation item in list or tabbed navigation modes. * * @param position Position of the item to select. */ public abstract void setSelectedNavigationItem(int position); /** * Get the position of the selected navigation item in list or tabbed navigation modes. * * @return Position of the selected item. */ public abstract int getSelectedNavigationIndex(); /** * Get the number of navigation items present in the current navigation mode. * * @return Number of navigation items. */ public abstract int getNavigationItemCount(); /** * Set the action bar's title. This will only be displayed if {@link #DISPLAY_SHOW_TITLE} is * set. * * @param title Title to set * @see #setTitle(int) * @see #setDisplayOptions(int, int) */ public abstract void setTitle(CharSequence title); /** * Set the action bar's title. This will only be displayed if {@link #DISPLAY_SHOW_TITLE} is * set. * * @param resId Resource ID of title string to set * @see #setTitle(CharSequence) * @see #setDisplayOptions(int, int) */ public abstract void setTitle(@StringRes int resId); /** * Set the action bar's subtitle. This will only be displayed if {@link #DISPLAY_SHOW_TITLE} is * set. Set to null to disable the subtitle entirely. * * @param subtitle Subtitle to set * @see #setSubtitle(int) * @see #setDisplayOptions(int, int) */ public abstract void setSubtitle(@Nullable CharSequence subtitle); /** * Set the action bar's subtitle. This will only be displayed if {@link #DISPLAY_SHOW_TITLE} is * set. * * @param resId Resource ID of subtitle string to set * @see #setSubtitle(CharSequence) * @see #setDisplayOptions(int, int) */ public abstract void setSubtitle(@StringRes int resId); /** * Set display options. This changes all display option bits at once. To change a limited subset * of display options, see {@link #setDisplayOptions(int, int)}. * * @param options A combination of the bits defined by the DISPLAY_ constants defined in * ActionBar. */ public abstract void setDisplayOptions(@DisplayOptions int options); /** * Set selected display options. Only the options specified by mask will be changed. To change * all display option bits at once, see {@link #setDisplayOptions(int)}. * *Example: setDisplayOptions(0, DISPLAY_SHOW_HOME) will disable the {@link * #DISPLAY_SHOW_HOME} option. setDisplayOptions(DISPLAY_SHOW_HOME, DISPLAY_SHOW_HOME | * DISPLAY_USE_LOGO) will enable {@link #DISPLAY_SHOW_HOME} and disable {@link * #DISPLAY_USE_LOGO}. * * @param options A combination of the bits defined by the DISPLAY_ constants defined in * ActionBar. * @param mask A bit mask declaring which display options should be changed. */ public abstract void setDisplayOptions(@DisplayOptions int options, int mask); /** * Set whether to display the activity logo rather than the activity icon. A logo is often a * wider, more detailed image. * *
To set several display options at once, see the setDisplayOptions methods. * * @param useLogo true to use the activity logo, false to use the activity icon. * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public abstract void setDisplayUseLogoEnabled(boolean useLogo); /** * Set whether to include the application home affordance in the action bar. Home is presented * as either an activity icon or logo. * *
To set several display options at once, see the setDisplayOptions methods. * * @param showHome true to show home, false otherwise. * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public abstract void setDisplayShowHomeEnabled(boolean showHome); /** * Set whether home should be displayed as an "up" affordance. Set this to true if selecting * "home" returns up by a single level in your UI rather than back to the top level or front * page. * *
To set several display options at once, see the setDisplayOptions methods. * * @param showHomeAsUp true to show the user that selecting home will return one level up rather * than to the top level of the app. * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public abstract void setDisplayHomeAsUpEnabled(boolean showHomeAsUp); /** * Set whether an activity title/subtitle should be displayed. * *
To set several display options at once, see the setDisplayOptions methods. * * @param showTitle true to display a title/subtitle if present. * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public abstract void setDisplayShowTitleEnabled(boolean showTitle); /** * Set whether a custom view should be displayed, if set. * *
To set several display options at once, see the setDisplayOptions methods. * * @param showCustom true if the currently set custom view should be displayed, false * otherwise. * @see #setDisplayOptions(int) * @see #setDisplayOptions(int, int) */ public abstract void setDisplayShowCustomEnabled(boolean showCustom); /** * Set the ActionBar's background. This will be used for the primary action bar. * * @param d Background drawable * @see #setStackedBackgroundDrawable(Drawable) * @see #setSplitBackgroundDrawable(Drawable) */ public abstract void setBackgroundDrawable(Drawable d); /** * Set the ActionBar's stacked background. This will appear in the second row/stacked bar on * some devices and configurations. * * @param d Background drawable for the stacked row */ public void setStackedBackgroundDrawable(Drawable d) { } /** * Set the ActionBar's split background. This will appear in the split action bar containing * menu-provided action buttons on some devices and configurations * *
You can enable split action bar with {@link android.R.attr#uiOptions} * * @param d Background drawable for the split bar */ public void setSplitBackgroundDrawable(Drawable d) { } /** * @return The current custom view. */ public abstract View getCustomView(); /** * Returns the current ActionBar title in standard mode. Returns null if {@link * #getNavigationMode()} would not return {@link #NAVIGATION_MODE_STANDARD}. * * @return The current ActionBar title or null. */ @Nullable public abstract CharSequence getTitle(); /** * Returns the current ActionBar subtitle in standard mode. Returns null if {@link * #getNavigationMode()} would not return {@link #NAVIGATION_MODE_STANDARD}. * * @return The current ActionBar subtitle or null. */ @Nullable public abstract CharSequence getSubtitle(); /** * Returns the current navigation mode. The result will be one of: * *
Very often tabs will be used to switch between {@link Fragment} objects. Here is a * typical implementation of such tabs:
* * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentTabs.java * complete} * * @return A new Tab * @see #addTab(Tab) */ public abstract Tab newTab(); /** * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list. If * this is the first tab to be added it will become the selected tab. * * @param tab Tab to add */ public abstract void addTab(Tab tab); /** * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list. * * @param tab Tab to add * @param setSelected True if the added tab should become the selected tab. */ public abstract void addTab(Tab tab, boolean setSelected); /** * Add a tab for use in tabbed navigation mode. The tab will be inserted at *position. If this is the first tab to be added it will become the selected tab.
*
* @param tab The tab to add
* @param position The new position of the tab
*/
public abstract void addTab(Tab tab, int position);
/**
* Add a tab for use in tabbed navigation mode. The tab will be insterted at
* position.
*
* @param tab The tab to add
* @param position The new position of the tab
* @param setSelected True if the added tab should become the selected tab.
*/
public abstract void addTab(Tab tab, int position, boolean setSelected);
/**
* Remove a tab from the action bar. If the removed tab was selected it will be deselected and
* another tab will be selected if present.
*
* @param tab The tab to remove
*/
public abstract void removeTab(Tab tab);
/**
* Remove a tab from the action bar. If the removed tab was selected it will be deselected and
* another tab will be selected if present.
*
* @param position Position of the tab to remove
*/
public abstract void removeTabAt(int position);
/**
* Remove all tabs from the action bar and deselect the current tab.
*/
public abstract void removeAllTabs();
/**
* Select the specified tab. If it is not a child of this action bar it will be added.
*
* Note: If you want to select by index, use {@link #setSelectedNavigationItem(int)}.
* * @param tab Tab to select */ public abstract void selectTab(Tab tab); /** * Returns the currently selected tab if in tabbed navigation mode and there is at least one tab * present. * * @return The currently selected tab or null */ @Nullable public abstract Tab getSelectedTab(); /** * Returns the tab at the specified index. * * @param index Index value in the range 0-get */ public abstract Tab getTabAt(int index); /** * Returns the number of tabs currently registered with the action bar. * * @return Tab count */ public abstract int getTabCount(); /** * Retrieve the current height of the ActionBar. * * @return The ActionBar's height */ public abstract int getHeight(); /** * Show the ActionBar if it is not currently showing. If the window hosting the ActionBar does * not have the feature {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application * content to fit the new space available. * *If you are hiding the ActionBar through {@link View#SYSTEM_UI_FLAG_FULLSCREEN * View.SYSTEM_UI_FLAG_FULLSCREEN}, you should not call this function directly. */ public abstract void show(); /** * Hide the ActionBar if it is currently showing. If the window hosting the ActionBar does not * have the feature {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application content * to fit the new space available. * *
Instead of calling this function directly, you can also cause an ActionBar using the
* overlay feature to hide through {@link View#SYSTEM_UI_FLAG_FULLSCREEN
* View.SYSTEM_UI_FLAG_FULLSCREEN}. Hiding the ActionBar through this system UI flag allows you
* to more seamlessly hide it in conjunction with other screen decorations.
*/
public abstract void hide();
/**
* @return true if the ActionBar is showing, false otherwise.
*/
public abstract boolean isShowing();
/**
* Add a listener that will respond to menu visibility change events.
*
* @param listener The new listener to add
*/
public abstract void addOnMenuVisibilityListener(OnMenuVisibilityListener listener);
/**
* Remove a menu visibility listener. This listener will no longer receive menu visibility
* change events.
*
* @param listener A listener to remove that was previously added
*/
public abstract void removeOnMenuVisibilityListener(OnMenuVisibilityListener listener);
/**
* Enable or disable the "home" button in the corner of the action bar. (Note that this is the
* application home/up affordance on the action bar, not the systemwide home button.)
*
*
This defaults to true for packages targeting < API 14. For packages targeting API 14 or * greater, the application should call this method to enable interaction with the home/up * affordance. * *
Setting the {@link #DISPLAY_HOME_AS_UP} display option will automatically enable the home * button. * * @param enabled true to enable the home button, false to disable the home button. */ public void setHomeButtonEnabled(boolean enabled) { } /** * Returns a {@link Context} with an appropriate theme for creating views that will appear in * the action bar. If you are inflating or instantiating custom views that will appear in an * action bar, you should use the Context returned by this method. (This includes adapters used * for list navigation mode.) This will ensure that views contrast properly against the action * bar. * * @return A themed Context for creating views */ public Context getThemedContext() { return null; } /** * Set an alternate drawable to display next to the icon/logo/title * when {@link #DISPLAY_HOME_AS_UP} is enabled. This can be useful if you are using * this mode to display an alternate selection for up navigation, such as a sliding drawer. * *
If you pass null to this method, the default drawable from the theme
* will be used.
If you implement alternate or intermediate behavior around Up, you should also * call {@link #setHomeActionContentDescription(int) setHomeActionContentDescription()} * to provide a correct description of the action for accessibility support.
* * @param indicator A drawable to use for the up indicator, or null to use the theme's default * * @see #setDisplayOptions(int, int) * @see #setDisplayHomeAsUpEnabled(boolean) * @see #setHomeActionContentDescription(int) */ public void setHomeAsUpIndicator(@Nullable Drawable indicator) {} /** * Set an alternate drawable to display next to the icon/logo/title * when {@link #DISPLAY_HOME_AS_UP} is enabled. This can be useful if you are using * this mode to display an alternate selection for up navigation, such as a sliding drawer. * *If you pass 0 to this method, the default drawable from the theme
* will be used.
If you implement alternate or intermediate behavior around Up, you should also * call {@link #setHomeActionContentDescription(int) setHomeActionContentDescription()} * to provide a correct description of the action for accessibility support.
* * @param resId Resource ID of a drawable to use for the up indicator, or 0 * to use the theme's default * * @see #setDisplayOptions(int, int) * @see #setDisplayHomeAsUpEnabled(boolean) * @see #setHomeActionContentDescription(int) */ public void setHomeAsUpIndicator(@DrawableRes int resId) {} /** * Set an alternate description for the Home/Up action, when enabled. * *This description is commonly used for accessibility/screen readers when * the Home action is enabled. (See {@link #setDisplayHomeAsUpEnabled(boolean)}.) * Examples of this are, "Navigate Home" or "Navigate Up" depending on the * {@link #DISPLAY_HOME_AS_UP} display option. If you have changed the home-as-up * indicator using {@link #setHomeAsUpIndicator(int)} to indicate more specific * functionality such as a sliding drawer, you should also set this to accurately * describe the action.
* *Setting this to null will use the system default description.
This description is commonly used for accessibility/screen readers when * the Home action is enabled. (See {@link #setDisplayHomeAsUpEnabled(boolean)}.) * Examples of this are, "Navigate Home" or "Navigate Up" depending on the * {@link #DISPLAY_HOME_AS_UP} display option. If you have changed the home-as-up * indicator using {@link #setHomeAsUpIndicator(int)} to indicate more specific * functionality such as a sliding drawer, you should also set this to accurately * describe the action.
* *Setting this to 0 will use the system default description.
Note: This interface is included in the support library for compatibility * with API level 7 and higher. If you're developing your app for API level 11 and higher * only, you should instead use the framework {@link * android.app.ActionBar.OnNavigationListener} interface.
*/ public interface OnNavigationListener { /** * This method is called whenever a navigation item in your action bar is selected. * * @param itemPosition Position of the item clicked. * @param itemId ID of the item clicked. * @return True if the event was handled, false otherwise. */ public boolean onNavigationItemSelected(int itemPosition, long itemId); } /** * Listener for receiving events when {@link ActionBar} items are shown or hidden. * *Note: This interface is included in the support library for compatibility * with API level 7 and higher. If you're developing your app for API level 11 and higher * only, you should instead use the framework {@link * android.app.ActionBar.OnMenuVisibilityListener} interface.
*/ public interface OnMenuVisibilityListener { /** * Called when an action bar menu is shown or hidden. Applications may want to use this to * tune auto-hiding behavior for the action bar or pause/resume video playback, gameplay, or * other activity within the main content area. * * @param isVisible True if an action bar menu is now visible, false if no action bar menus * are visible. */ public void onMenuVisibilityChanged(boolean isVisible); } /** * A tab in the action bar that manages the hiding and showing of {@link Fragment}s. * *Note: This class is included in the support library for compatibility * with API level 7 and higher. If you're developing your app for API level 11 and higher * only, you should instead use the framework {@link android.app.ActionBar.Tab} * class.
* *For information about how to use action bar tabs, * read the Action * Bar API guide.
*Note: This interface is included in the support library for compatibility * with API level 7 and higher. If you're developing your app for API level 11 and higher * only, you should instead use the framework {@link android.app.ActionBar.TabListener} * interface.
* *For information about how to use action bar tabs, * read the Action * Bar API guide.
*