com.actionbarsherlock.app

Class ActionBar

java.lang.Object

com.actionbarsherlock.app.ActionBar

Direct Known Subclasses:

ActionBarImpl, ActionBarWrapper

public abstract class ActionBar
extends Object

A window feature at the top of the activity that may display the activity title, navigation modes, and other interactive items.

Beginning with Android 3.0 (API level 11), the action bar appears at the top of an activity's window when the activity uses the system's Holo theme (or one of its descendant themes), which is the default. You may otherwise add the action bar by calling requestFeature(FEATURE_ACTION_BAR) or by declaring it in a custom theme with the windowActionBar property.

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 ActionBar by calling getActionBar().

In some cases, the action bar may be overlayed by another bar that enables contextual actions, using an 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 ActionMode APIs are distinct and independent from those for ActionBar.

Developer Guides

For information about how to use the action bar, including how to add action items, navigation modes and more, read the Action Bar developer guide.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ActionBar.LayoutParams Per-child layout information associated with action bar custom views.
static interface	ActionBar.OnMenuVisibilityListener Listener for receiving events when action bar menus are shown or hidden.
static interface	ActionBar.OnNavigationListener Listener interface for ActionBar navigation events.
static class	ActionBar.Tab A tab in the action bar.
static interface	ActionBar.TabListener Callback interface invoked when a tab is focused, unfocused, added, or removed.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DISPLAY_HOME_AS_UP Display the 'home' element such that it appears as an 'up' affordance.
static int	DISPLAY_SHOW_CUSTOM Show the custom view if one has been set.
static int	DISPLAY_SHOW_HOME Show 'home' elements in this action bar, leaving more space for other navigation elements.
static int	DISPLAY_SHOW_TITLE Show the activity title and subtitle, if present.
static int	DISPLAY_USE_LOGO Use logo instead of icon if available.
static int	NAVIGATION_MODE_LIST List navigation mode.
static int	NAVIGATION_MODE_STANDARD Standard navigation mode.
static int	NAVIGATION_MODE_TABS Tab navigation mode.

Constructor Summary

Constructors

Constructor and Description
ActionBar()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	addOnMenuVisibilityListener(ActionBar.OnMenuVisibilityListener listener) Add a listener that will respond to menu visibility change events.
abstract void	addTab(ActionBar.Tab tab) Add a tab for use in tabbed navigation mode.
abstract void	addTab(ActionBar.Tab tab, boolean setSelected) Add a tab for use in tabbed navigation mode.
abstract void	addTab(ActionBar.Tab tab, int position) Add a tab for use in tabbed navigation mode.
abstract void	addTab(ActionBar.Tab tab, int position, boolean setSelected) Add a tab for use in tabbed navigation mode.
abstract android.view.View	getCustomView()
abstract int	getDisplayOptions()
abstract int	getHeight() Retrieve the current height of the ActionBar.
abstract int	getNavigationItemCount() Get the number of navigation items present in the current navigation mode.
abstract int	getNavigationMode() Returns the current navigation mode.
abstract int	getSelectedNavigationIndex() Get the position of the selected navigation item in list or tabbed navigation modes.
abstract ActionBar.Tab	getSelectedTab() Returns the currently selected tab if in tabbed navigation mode and there is at least one tab present.
abstract CharSequence	getSubtitle() Returns the current ActionBar subtitle in standard mode.
abstract ActionBar.Tab	getTabAt(int index) Returns the tab at the specified index.
abstract int	getTabCount() Returns the number of tabs currently registered with the action bar.
android.content.Context	getThemedContext() Returns a Context with an appropriate theme for creating views that will appear in the action bar.
abstract CharSequence	getTitle() Returns the current ActionBar title in standard mode.
abstract void	hide() Hide the ActionBar if it is currently showing.
abstract boolean	isShowing()
abstract ActionBar.Tab	newTab() Create and return a new ActionBar.Tab.
abstract void	removeAllTabs() Remove all tabs from the action bar and deselect the current tab.
abstract void	removeOnMenuVisibilityListener(ActionBar.OnMenuVisibilityListener listener) Remove a menu visibility listener.
abstract void	removeTab(ActionBar.Tab tab) Remove a tab from the action bar.
abstract void	removeTabAt(int position) Remove a tab from the action bar.
abstract void	selectTab(ActionBar.Tab tab) Select the specified tab.
abstract void	setBackgroundDrawable(android.graphics.drawable.Drawable d) Set the ActionBar's background.
abstract void	setCustomView(int resId) Set the action bar into custom navigation mode, supplying a view for custom navigation.
abstract void	setCustomView(android.view.View view) Set the action bar into custom navigation mode, supplying a view for custom navigation.
abstract void	setCustomView(android.view.View view, ActionBar.LayoutParams layoutParams) Set the action bar into custom navigation mode, supplying a view for custom navigation.
abstract void	setDisplayHomeAsUpEnabled(boolean showHomeAsUp) Set whether home should be displayed as an "up" affordance.
abstract void	setDisplayOptions(int options) Set display options.
abstract void	setDisplayOptions(int options, int mask) Set selected display options.
abstract void	setDisplayShowCustomEnabled(boolean showCustom) Set whether a custom view should be displayed, if set.
abstract void	setDisplayShowHomeEnabled(boolean showHome) Set whether to include the application home affordance in the action bar.
abstract void	setDisplayShowTitleEnabled(boolean showTitle) Set whether an activity title/subtitle should be displayed.
abstract void	setDisplayUseLogoEnabled(boolean useLogo) Set whether to display the activity logo rather than the activity icon.
void	setHomeButtonEnabled(boolean enabled) Enable or disable the "home" button in the corner of the action bar.
abstract void	setIcon(android.graphics.drawable.Drawable icon) Set the icon to display in the 'home' section of the action bar.
abstract void	setIcon(int resId) Set the icon to display in the 'home' section of the action bar.
abstract void	setListNavigationCallbacks(android.widget.SpinnerAdapter adapter, ActionBar.OnNavigationListener callback) Set the adapter and navigation callback for list navigation mode.
abstract void	setLogo(android.graphics.drawable.Drawable logo) Set the logo to display in the 'home' section of the action bar.
abstract void	setLogo(int resId) Set the logo to display in the 'home' section of the action bar.
abstract void	setNavigationMode(int mode) Set the current navigation mode.
abstract void	setSelectedNavigationItem(int position) Set the selected navigation item in list or tabbed navigation modes.
void	setSplitBackgroundDrawable(android.graphics.drawable.Drawable d) Set the ActionBar's split background.
void	setStackedBackgroundDrawable(android.graphics.drawable.Drawable d) Set the ActionBar's stacked background.
abstract void	setSubtitle(CharSequence subtitle) Set the action bar's subtitle.
abstract void	setSubtitle(int resId) Set the action bar's subtitle.
abstract void	setTitle(CharSequence title) Set the action bar's title.
abstract void	setTitle(int resId) Set the action bar's title.
abstract void	show() Show the ActionBar if it is not currently showing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAVIGATION_MODE_STANDARD

public static final int NAVIGATION_MODE_STANDARD

Standard navigation mode. Consists of either a logo or icon and title text with an optional subtitle. Clicking any of these elements will dispatch onOptionsItemSelected to the host Activity with a MenuItem with item ID android.R.id.home.

See Also:

Constant Field Values

NAVIGATION_MODE_LIST

public static final int NAVIGATION_MODE_LIST

List navigation mode. Instead of static title text this mode presents a list menu for navigation within the activity. e.g. this might be presented to the user as a dropdown list.

See Also:

Constant Field Values

NAVIGATION_MODE_TABS

public static final int NAVIGATION_MODE_TABS

Tab navigation mode. Instead of static title text this mode presents a series of tabs for navigation within the activity.

See Also:

Constant Field Values

DISPLAY_USE_LOGO

public static final int DISPLAY_USE_LOGO

Use logo instead of icon if available. This flag will cause appropriate navigation modes to use a wider logo in place of the standard icon.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int), Constant Field Values

DISPLAY_SHOW_HOME

public static final int DISPLAY_SHOW_HOME

Show 'home' elements in this action bar, leaving more space for other navigation elements. This includes logo and icon.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int), Constant Field Values

DISPLAY_HOME_AS_UP

public static final int DISPLAY_HOME_AS_UP

Display the 'home' element such that it appears as an 'up' affordance. e.g. show an arrow to the left indicating the action that will be taken. Set this flag if selecting the 'home' button in the action bar to return up by a single level in your UI rather than back to the top level or front page.

Setting this option will implicitly enable interaction with the home/up button. See setHomeButtonEnabled(boolean).

See Also:

setDisplayOptions(int), setDisplayOptions(int, int), Constant Field Values

DISPLAY_SHOW_TITLE

public static final int DISPLAY_SHOW_TITLE

Show the activity title and subtitle, if present.

See Also:

setTitle(CharSequence), setTitle(int), setSubtitle(CharSequence), setSubtitle(int), setDisplayOptions(int), setDisplayOptions(int, int), Constant Field Values

DISPLAY_SHOW_CUSTOM

public static final int DISPLAY_SHOW_CUSTOM

Show the custom view if one has been set.

See Also:

setCustomView(View), setDisplayOptions(int), setDisplayOptions(int, int), Constant Field Values

Constructor Detail

ActionBar

public ActionBar()

Method Detail

setCustomView

public abstract void setCustomView(android.view.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.

Parameters:

view - Custom navigation view to place in the ActionBar.

setCustomView

public abstract void setCustomView(android.view.View view,
                 ActionBar.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 DISPLAY_SHOW_CUSTOM must be set for the custom view to be displayed.

Parameters:

view - Custom navigation view to place in the ActionBar.

layoutParams - How this custom view should layout in the bar.

See Also:

setDisplayOptions(int, int)

setCustomView

public abstract void setCustomView(int resId)

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 DISPLAY_SHOW_CUSTOM must be set for the custom view to be displayed.

Parameters:

resId - Resource ID of a layout to inflate into the ActionBar.

See Also:

setDisplayOptions(int, int)

setIcon

public abstract void setIcon(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 DISPLAY_USE_LOGO.

Parameters:

resId - Resource ID of a drawable to show as an icon.

See Also:

setDisplayUseLogoEnabled(boolean), setDisplayShowHomeEnabled(boolean)

setIcon

public abstract void setIcon(android.graphics.drawable.Drawable icon)

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 DISPLAY_USE_LOGO.

Parameters:

icon - Drawable to show as an icon.

See Also:

setDisplayUseLogoEnabled(boolean), setDisplayShowHomeEnabled(boolean)

setLogo

public abstract void setLogo(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 DISPLAY_USE_LOGO.

Parameters:

resId - Resource ID of a drawable to show as a logo.

See Also:

setDisplayUseLogoEnabled(boolean), setDisplayShowHomeEnabled(boolean)

setLogo

public abstract void setLogo(android.graphics.drawable.Drawable logo)

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 DISPLAY_USE_LOGO.

Parameters:

logo - Drawable to show as a logo.

See Also:

setDisplayUseLogoEnabled(boolean), setDisplayShowHomeEnabled(boolean)

setListNavigationCallbacks

public abstract void setListNavigationCallbacks(android.widget.SpinnerAdapter adapter,
                              ActionBar.OnNavigationListener callback)

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.

Parameters:

adapter - An adapter that will provide views both to display the current navigation selection and populate views within the dropdown navigation menu.

callback - An OnNavigationListener that will receive events when the user selects a navigation item.

setSelectedNavigationItem

public abstract void setSelectedNavigationItem(int position)

Set the selected navigation item in list or tabbed navigation modes.

Parameters:

position - Position of the item to select.

getSelectedNavigationIndex

public abstract int getSelectedNavigationIndex()

Get the position of the selected navigation item in list or tabbed navigation modes.

Returns:

Position of the selected item.

getNavigationItemCount

public abstract int getNavigationItemCount()

Get the number of navigation items present in the current navigation mode.

Returns:

Number of navigation items.

setTitle

public abstract void setTitle(CharSequence title)

Set the action bar's title. This will only be displayed if DISPLAY_SHOW_TITLE is set.

Parameters:

title - Title to set

See Also:

setTitle(int), setDisplayOptions(int, int)

setTitle

public abstract void setTitle(int resId)

Set the action bar's title. This will only be displayed if DISPLAY_SHOW_TITLE is set.

Parameters:

resId - Resource ID of title string to set

See Also:

setTitle(CharSequence), setDisplayOptions(int, int)

setSubtitle

public abstract void setSubtitle(CharSequence subtitle)

Set the action bar's subtitle. This will only be displayed if DISPLAY_SHOW_TITLE is set. Set to null to disable the subtitle entirely.

Parameters:

subtitle - Subtitle to set

See Also:

setSubtitle(int), setDisplayOptions(int, int)

setSubtitle

public abstract void setSubtitle(int resId)

Set the action bar's subtitle. This will only be displayed if DISPLAY_SHOW_TITLE is set.

Parameters:

resId - Resource ID of subtitle string to set

See Also:

setSubtitle(CharSequence), setDisplayOptions(int, int)

setDisplayOptions

public abstract void setDisplayOptions(int options)

Set display options. This changes all display option bits at once. To change a limited subset of display options, see setDisplayOptions(int, int).

Parameters:

options - A combination of the bits defined by the DISPLAY_ constants defined in ActionBar.

setDisplayOptions

public abstract void setDisplayOptions(int options,
                     int mask)

Set selected display options. Only the options specified by mask will be changed. To change all display option bits at once, see setDisplayOptions(int).

Example: setDisplayOptions(0, DISPLAY_SHOW_HOME) will disable the DISPLAY_SHOW_HOME option. setDisplayOptions(DISPLAY_SHOW_HOME, DISPLAY_SHOW_HOME | DISPLAY_USE_LOGO) will enable DISPLAY_SHOW_HOME and disable DISPLAY_USE_LOGO.

Parameters:

options - A combination of the bits defined by the DISPLAY_ constants defined in ActionBar.

mask - A bit mask declaring which display options should be changed.

setDisplayUseLogoEnabled

public abstract void setDisplayUseLogoEnabled(boolean useLogo)

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.

Parameters:

useLogo - true to use the activity logo, false to use the activity icon.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int)

setDisplayShowHomeEnabled

public abstract void setDisplayShowHomeEnabled(boolean showHome)

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.

Parameters:

showHome - true to show home, false otherwise.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int)

setDisplayHomeAsUpEnabled

public abstract void setDisplayHomeAsUpEnabled(boolean showHomeAsUp)

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.

Parameters:

showHomeAsUp - true to show the user that selecting home will return one level up rather than to the top level of the app.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int)

setDisplayShowTitleEnabled

public abstract void setDisplayShowTitleEnabled(boolean showTitle)

Set whether an activity title/subtitle should be displayed.

To set several display options at once, see the setDisplayOptions methods.

Parameters:

showTitle - true to display a title/subtitle if present.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int)

setDisplayShowCustomEnabled

public abstract void setDisplayShowCustomEnabled(boolean showCustom)

Set whether a custom view should be displayed, if set.

To set several display options at once, see the setDisplayOptions methods.

Parameters:

showCustom - true if the currently set custom view should be displayed, false otherwise.

See Also:

setDisplayOptions(int), setDisplayOptions(int, int)

setBackgroundDrawable

public abstract void setBackgroundDrawable(android.graphics.drawable.Drawable d)

Set the ActionBar's background. This will be used for the primary action bar.

Parameters:

d - Background drawable

See Also:

setStackedBackgroundDrawable(Drawable), setSplitBackgroundDrawable(Drawable)

setStackedBackgroundDrawable

public void setStackedBackgroundDrawable(android.graphics.drawable.Drawable d)

Set the ActionBar's stacked background. This will appear in the second row/stacked bar on some devices and configurations.

Parameters:

d - Background drawable for the stacked row

setSplitBackgroundDrawable

public void setSplitBackgroundDrawable(android.graphics.drawable.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 R.attr.uiOptions

Parameters:

d - Background drawable for the split bar

getCustomView

public abstract android.view.View getCustomView()

Returns:

The current custom view.

getTitle

public abstract CharSequence getTitle()

Returns the current ActionBar title in standard mode. Returns null if getNavigationMode() would not return NAVIGATION_MODE_STANDARD.

Returns:

The current ActionBar title or null.

getSubtitle

public abstract CharSequence getSubtitle()

Returns the current ActionBar subtitle in standard mode. Returns null if getNavigationMode() would not return NAVIGATION_MODE_STANDARD.

Returns:

The current ActionBar subtitle or null.

getNavigationMode

public abstract int getNavigationMode()

Returns the current navigation mode. The result will be one of:

• NAVIGATION_MODE_STANDARD
• NAVIGATION_MODE_LIST
• NAVIGATION_MODE_TABS

Returns:

The current navigation mode.

setNavigationMode

public abstract void setNavigationMode(int mode)

Set the current navigation mode.

Parameters:

mode - The new mode to set.

See Also:

NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS

getDisplayOptions

public abstract int getDisplayOptions()

Returns:

The current set of display options.

newTab

public abstract ActionBar.Tab newTab()

Create and return a new ActionBar.Tab. This tab will not be included in the action bar until it is added.

Very often tabs will be used to switch between Fragment objects. Here is a typical implementation of such tabs:

Returns:

A new Tab

See Also:

addTab(Tab)

addTab

public abstract void addTab(ActionBar.Tab tab)

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.

Parameters:

tab - Tab to add

addTab

public abstract void addTab(ActionBar.Tab tab,
          boolean setSelected)

Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list.

Parameters:

tab - Tab to add

setSelected - True if the added tab should become the selected tab.

addTab

public abstract void addTab(ActionBar.Tab tab,
          int position)

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.

Parameters:

tab - The tab to add

position - The new position of the tab

addTab

public abstract void addTab(ActionBar.Tab tab,
          int position,
          boolean setSelected)

Add a tab for use in tabbed navigation mode. The tab will be insterted at position.

Parameters:

tab - The tab to add

position - The new position of the tab

setSelected - True if the added tab should become the selected tab.

removeTab

public abstract void removeTab(ActionBar.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.

Parameters:

tab - The tab to remove

removeTabAt

public abstract void removeTabAt(int position)

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.

Parameters:

position - Position of the tab to remove

removeAllTabs

public abstract void removeAllTabs()

Remove all tabs from the action bar and deselect the current tab.

selectTab

public abstract void selectTab(ActionBar.Tab tab)

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 setSelectedNavigationItem(int).

Parameters:

tab - Tab to select

getSelectedTab

public abstract ActionBar.Tab getSelectedTab()

Returns the currently selected tab if in tabbed navigation mode and there is at least one tab present.

Returns:

The currently selected tab or null

getTabAt

public abstract ActionBar.Tab getTabAt(int index)

Returns the tab at the specified index.

Parameters:

index - Index value in the range 0-get

Returns:

getTabCount

public abstract int getTabCount()

Returns the number of tabs currently registered with the action bar.

Returns:

Tab count

getHeight

public abstract int getHeight()

Retrieve the current height of the ActionBar.

Returns:

The ActionBar's height

show

public abstract void show()

Show the ActionBar if it is not currently showing. If the window hosting the ActionBar does not have the feature Window#FEATURE_ACTION_BAR_OVERLAY it will resize application content to fit the new space available.

hide

public abstract void hide()

Hide the ActionBar if it is currently showing. If the window hosting the ActionBar does not have the feature Window#FEATURE_ACTION_BAR_OVERLAY it will resize application content to fit the new space available.

isShowing

public abstract boolean isShowing()

Returns:

true if the ActionBar is showing, false otherwise.

addOnMenuVisibilityListener

public abstract void addOnMenuVisibilityListener(ActionBar.OnMenuVisibilityListener listener)

Add a listener that will respond to menu visibility change events.

Parameters:

listener - The new listener to add

removeOnMenuVisibilityListener

public abstract void removeOnMenuVisibilityListener(ActionBar.OnMenuVisibilityListener listener)

Remove a menu visibility listener. This listener will no longer receive menu visibility change events.

Parameters:

listener - A listener to remove that was previously added

setHomeButtonEnabled

public void setHomeButtonEnabled(boolean enabled)

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 DISPLAY_HOME_AS_UP display option will automatically enable the home button.

Parameters:

enabled - true to enable the home button, false to disable the home button.

getThemedContext

public android.content.Context getThemedContext()

Returns a 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.

Returns:

A themed Context for creating views