com.actionbarsherlock.internal.view.menu

Class MenuBuilder

java.lang.Object

com.actionbarsherlock.internal.view.menu.MenuBuilder

All Implemented Interfaces:

Menu

Direct Known Subclasses:

SubMenuBuilder

public class MenuBuilder
extends Object
implements Menu

Implementation of the Menu interface for creating a standard menu UI.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MenuBuilder.Callback Called by menu to notify of close and selection changes.
static interface	MenuBuilder.ItemInvoker Called by menu items to execute their associated action

Field Summary

Fields inherited from interface com.actionbarsherlock.view.Menu

CATEGORY_ALTERNATIVE, CATEGORY_CONTAINER, CATEGORY_MASK, CATEGORY_SECONDARY, CATEGORY_SHIFT, CATEGORY_SYSTEM, FIRST, FLAG_ALWAYS_PERFORM_CLOSE, FLAG_APPEND_TO_GROUP, FLAG_PERFORM_NO_CLOSE, NONE, USER_MASK, USER_SHIFT

Constructor Summary

Constructors

Constructor and Description
MenuBuilder(android.content.Context context)

Method Summary

Methods

Modifier and Type	Method and Description
MenuItem	add(CharSequence title) Add a new item to the menu.
MenuItem	add(int titleRes) Add a new item to the menu.
MenuItem	add(int group, int id, int categoryOrder, CharSequence title) Add a new item to the menu.
MenuItem	add(int group, int id, int categoryOrder, int title) Variation on Menu.add(int, int, int, CharSequence) that takes a string resource identifier instead of the string itself.
int	addIntentOptions(int group, int id, int categoryOrder, android.content.ComponentName caller, android.content.Intent[] specifics, android.content.Intent intent, int flags, MenuItem[] outSpecificItems) Add a group of menu items corresponding to actions that can be performed for a particular Intent.
void	addMenuPresenter(MenuPresenter presenter) Add a presenter to this menu.
SubMenu	addSubMenu(CharSequence title) Add a new sub-menu to the menu.
SubMenu	addSubMenu(int titleRes) Add a new sub-menu to the menu.
SubMenu	addSubMenu(int group, int id, int categoryOrder, CharSequence title) Add a new sub-menu to the menu.
SubMenu	addSubMenu(int group, int id, int categoryOrder, int title) Variation on Menu.addSubMenu(int, int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself.
boolean	bindNativeOverflow(android.view.Menu menu, android.view.MenuItem.OnMenuItemClickListener listener, HashMap<android.view.MenuItem,MenuItemImpl> map)
void	changeMenuMode() Dispatch a mode change event to this menu's callback.
void	clear() Remove all existing items from the menu, leaving it empty as if it had just been created.
void	clearAll()
void	clearHeader()
void	close() Closes the menu, if open.
boolean	collapseItemActionView(MenuItemImpl item)
boolean	expandItemActionView(MenuItemImpl item)
int	findGroupIndex(int group)
int	findGroupIndex(int group, int start)
MenuItem	findItem(int id) Return the menu item with a particular identifier.
int	findItemIndex(int id)
void	flagActionItems() This method determines which menu items get to be 'action items' that will appear in an action bar and which items should be 'overflow items' in a secondary menu.
protected String	getActionViewStatesKey()
android.content.Context	getContext()
MenuItemImpl	getExpandedItem()
android.graphics.drawable.Drawable	getHeaderIcon()
CharSequence	getHeaderTitle()
android.view.View	getHeaderView()
MenuItem	getItem(int index) Gets the menu item at the given index.
MenuBuilder	getRootMenu() Gets the root menu (if this is a submenu, find its root menu).
boolean	hasVisibleItems() Return whether the menu currently has item items that are visible.
boolean	isShortcutKey(int keyCode, android.view.KeyEvent event) Is a keypress one of the defined shortcut keys for this window.
boolean	isShortcutsVisible()
boolean	performIdentifierAction(int id, int flags) Execute the menu item action associated with the given menu identifier.
boolean	performItemAction(MenuItem item, int flags)
boolean	performShortcut(int keyCode, android.view.KeyEvent event, int flags) Execute the menu item action associated with the given shortcut character.
void	removeGroup(int group) Remove all items in the given group.
void	removeItem(int id) Remove the item with the given identifier.
void	removeItemAt(int index)
void	removeMenuPresenter(MenuPresenter presenter) Remove a presenter from this menu.
void	restoreActionViewStates(android.os.Bundle states)
void	restorePresenterStates(android.os.Bundle state)
void	saveActionViewStates(android.os.Bundle outStates)
void	savePresenterStates(android.os.Bundle outState)
void	setCallback(MenuBuilder.Callback cb)
void	setCurrentMenuInfo(android.view.ContextMenu.ContextMenuInfo menuInfo) Sets the current menu info that is set on all items added to this menu (until this is called again with different menu info, in which case that one will be added to all subsequent item additions).
MenuBuilder	setDefaultShowAsAction(int defaultShowAsAction)
void	setGroupCheckable(int group, boolean checkable, boolean exclusive) Control whether a particular group of items can show a check mark.
void	setGroupEnabled(int group, boolean enabled) Enable or disable all menu items that are in the given group.
void	setGroupVisible(int group, boolean visible) Show or hide all menu items that are in the given group.
protected MenuBuilder	setHeaderIconInt(android.graphics.drawable.Drawable icon) Sets the header's icon.
protected MenuBuilder	setHeaderIconInt(int iconRes) Sets the header's icon.
protected MenuBuilder	setHeaderTitleInt(CharSequence title) Sets the header's title.
protected MenuBuilder	setHeaderTitleInt(int titleRes) Sets the header's title.
protected MenuBuilder	setHeaderViewInt(android.view.View view) Sets the header's view.
void	setQwertyMode(boolean isQwerty) Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).
void	setShortcutsVisible(boolean shortcutsVisible) Sets whether the shortcuts should be visible on menus.
int	size() Get the number of items in the menu.
void	startDispatchingItemsChanged()
void	stopDispatchingItemsChanged() Stop dispatching item changed events to presenters until startDispatchingItemsChanged() is called.

Methods inherited from class java.lang.Object

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

Constructor Detail

MenuBuilder

public MenuBuilder(android.content.Context context)

Method Detail

setDefaultShowAsAction

public MenuBuilder setDefaultShowAsAction(int defaultShowAsAction)

addMenuPresenter

public void addMenuPresenter(MenuPresenter presenter)

Add a presenter to this menu. This will only hold a WeakReference; you do not need to explicitly remove a presenter, but you can using removeMenuPresenter(MenuPresenter).

Parameters:

presenter - The presenter to add

removeMenuPresenter

public void removeMenuPresenter(MenuPresenter presenter)

Remove a presenter from this menu. That presenter will no longer receive notifications of updates to this menu's data.

Parameters:

presenter - The presenter to remove

savePresenterStates

public void savePresenterStates(android.os.Bundle outState)

restorePresenterStates

public void restorePresenterStates(android.os.Bundle state)

saveActionViewStates

public void saveActionViewStates(android.os.Bundle outStates)

restoreActionViewStates

public void restoreActionViewStates(android.os.Bundle states)

getActionViewStatesKey

protected String getActionViewStatesKey()

setCallback

public void setCallback(MenuBuilder.Callback cb)

add

public MenuItem add(CharSequence title)

Description copied from interface: Menu

Add a new item to the menu. This item displays the given title for its label.

Specified by:

add in interface Menu

Parameters:

title - The text to display for the item.

Returns:

The newly added menu item.

add

public MenuItem add(int titleRes)

Description copied from interface: Menu

Add a new item to the menu. This item displays the given title for its label.

Specified by:

add in interface Menu

Parameters:

titleRes - Resource identifier of title string.

Returns:

The newly added menu item.

add

public MenuItem add(int group,
           int id,
           int categoryOrder,
           CharSequence title)

Description copied from interface: Menu

Add a new item to the menu. This item displays the given title for its label.

Specified by:

add in interface Menu

Parameters:

group - The group identifier that this item should be part of. This can be used to define groups of items for batch state changes. Normally use Menu.NONE if an item should not be in a group.

id - Unique item ID. Use Menu.NONE if you do not need a unique ID.

categoryOrder - The order for the item. Use Menu.NONE if you do not care about the order. See MenuItem.getOrder().

title - The text to display for the item.

Returns:

The newly added menu item.

add

public MenuItem add(int group,
           int id,
           int categoryOrder,
           int title)

Description copied from interface: Menu

Variation on Menu.add(int, int, int, CharSequence) that takes a string resource identifier instead of the string itself.

Specified by:

add in interface Menu

Parameters:

group - The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use Menu.NONE if an item should not be in a group.

id - Unique item ID. Use Menu.NONE if you do not need a unique ID.

categoryOrder - The order for the item. Use Menu.NONE if you do not care about the order. See MenuItem.getOrder().

title - Resource identifier of title string.

Returns:

The newly added menu item.

addSubMenu

public SubMenu addSubMenu(CharSequence title)

Description copied from interface: Menu

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use SubMenu.getItem().

Specified by:

addSubMenu in interface Menu

Parameters:

title - The text to display for the item.

Returns:

The newly added sub-menu

addSubMenu

public SubMenu addSubMenu(int titleRes)

Description copied from interface: Menu

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use SubMenu.getItem().

Specified by:

addSubMenu in interface Menu

Parameters:

titleRes - Resource identifier of title string.

Returns:

The newly added sub-menu

addSubMenu

public SubMenu addSubMenu(int group,
                 int id,
                 int categoryOrder,
                 CharSequence title)

Description copied from interface: Menu

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use SubMenu.getItem().

Note that you can only have one level of sub-menus, i.e. you cannnot add a subMenu to a subMenu: An UnsupportedOperationException will be thrown if you try.

Specified by:

addSubMenu in interface Menu

Parameters:

group - The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use Menu.NONE if an item should not be in a group.

id - Unique item ID. Use Menu.NONE if you do not need a unique ID.

categoryOrder - The order for the item. Use Menu.NONE if you do not care about the order. See MenuItem.getOrder().

title - The text to display for the item.

Returns:

The newly added sub-menu

addSubMenu

public SubMenu addSubMenu(int group,
                 int id,
                 int categoryOrder,
                 int title)

Description copied from interface: Menu

Variation on Menu.addSubMenu(int, int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself.

Specified by:

addSubMenu in interface Menu

Parameters:

group - The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use Menu.NONE if an item should not be in a group.

id - Unique item ID. Use Menu.NONE if you do not need a unique ID.

categoryOrder - The order for the item. Use Menu.NONE if you do not care about the order. See MenuItem.getOrder().

title - Resource identifier of title string.

Returns:

The newly added sub-menu

addIntentOptions

public int addIntentOptions(int group,
                   int id,
                   int categoryOrder,
                   android.content.ComponentName caller,
                   android.content.Intent[] specifics,
                   android.content.Intent intent,
                   int flags,
                   MenuItem[] outSpecificItems)

Description copied from interface: Menu

Add a group of menu items corresponding to actions that can be performed for a particular Intent. The Intent is most often configured with a null action, the data that the current activity is working with, and includes either the Intent.CATEGORY_ALTERNATIVE or Intent.CATEGORY_SELECTED_ALTERNATIVE to find activities that have said they would like to be included as optional action. You can, however, use any Intent you want.

See PackageManager.queryIntentActivityOptions(android.content.ComponentName, android.content.Intent[], android.content.Intent, int) for more * details on the caller, specifics, and intent arguments. The list returned by that function is used to populate the resulting menu items.

All of the menu items of possible options for the intent will be added with the given group and id. You can use the group to control ordering of the items in relation to other items in the menu. Normally this function will automatically remove any existing items in the menu in the same group and place a divider above and below the added items; this behavior can be modified with the flags parameter. For each of the generated items MenuItem.setIntent(android.content.Intent) is called to associate the appropriate Intent with the item; this means the activity will automatically be started for you without having to do anything else.

Specified by:

addIntentOptions in interface Menu

Parameters:

group - The group identifier that the items should be part of. This can also be used to define groups of items for batch state changes. Normally use Menu.NONE if the items should not be in a group.

id - Unique item ID. Use Menu.NONE if you do not need a unique ID.

categoryOrder - The order for the items. Use Menu.NONE if you do not care about the order. See MenuItem.getOrder().

caller - The current activity component name as defined by queryIntentActivityOptions().

specifics - Specific items to place first as defined by queryIntentActivityOptions().

intent - Intent describing the kinds of items to populate in the list as defined by queryIntentActivityOptions().

flags - Additional options controlling how the items are added.

outSpecificItems - Optional array in which to place the menu items that were generated for each of the specifics that were requested. Entries may be null if no activity was found for that specific action.

Returns:

The number of menu items that were added.

See Also:

Menu.FLAG_APPEND_TO_GROUP, MenuItem.setIntent(android.content.Intent), PackageManager.queryIntentActivityOptions(android.content.ComponentName, android.content.Intent[], android.content.Intent, int)

removeItem

public void removeItem(int id)

Description copied from interface: Menu

Remove the item with the given identifier.

Specified by:

removeItem in interface Menu

Parameters:

id - The item to be removed. If there is no item with this identifier, nothing happens.

removeGroup

public void removeGroup(int group)

Description copied from interface: Menu

Remove all items in the given group.

Specified by:

removeGroup in interface Menu

Parameters:

group - The group to be removed. If there are no items in this group, nothing happens.

removeItemAt

public void removeItemAt(int index)

clearAll

public void clearAll()

clear

public void clear()

Description copied from interface: Menu

Remove all existing items from the menu, leaving it empty as if it had just been created.

Specified by:

clear in interface Menu

setGroupCheckable

public void setGroupCheckable(int group,
                     boolean checkable,
                     boolean exclusive)

Description copied from interface: Menu

Control whether a particular group of items can show a check mark. This is similar to calling MenuItem.setCheckable(boolean) on all of the menu items with the given group identifier, but in addition you can control whether this group contains a mutually-exclusive set items. This should be called after the items of the group have been added to the menu.

Specified by:

setGroupCheckable in interface Menu

Parameters:

group - The group of items to operate on.

checkable - Set to true to allow a check mark, false to disallow. The default is false.

exclusive - If set to true, only one item in this group can be checked at a time; checking an item will automatically uncheck all others in the group. If set to false, each item can be checked independently of the others.

See Also:

MenuItem.setCheckable(boolean), MenuItem.setChecked(boolean)

setGroupVisible

public void setGroupVisible(int group,
                   boolean visible)

Description copied from interface: Menu

Show or hide all menu items that are in the given group.

Specified by:

setGroupVisible in interface Menu

Parameters:

group - The group of items to operate on.

visible - If true the items are visible, else they are hidden.

See Also:

MenuItem.setVisible(boolean)

setGroupEnabled

public void setGroupEnabled(int group,
                   boolean enabled)

Description copied from interface: Menu

Enable or disable all menu items that are in the given group.

Specified by:

setGroupEnabled in interface Menu

Parameters:

group - The group of items to operate on.

enabled - If true the items will be enabled, else they will be disabled.

See Also:

MenuItem.setEnabled(boolean)

hasVisibleItems

public boolean hasVisibleItems()

Description copied from interface: Menu

Return whether the menu currently has item items that are visible.

Specified by:

hasVisibleItems in interface Menu

Returns:

True if there is one or more item visible, else false.

findItem

public MenuItem findItem(int id)

Description copied from interface: Menu

Return the menu item with a particular identifier.

Specified by:

findItem in interface Menu

Parameters:

id - The identifier to find.

Returns:

The menu item object, or null if there is no item with this identifier.

findItemIndex

public int findItemIndex(int id)

findGroupIndex

public int findGroupIndex(int group)

findGroupIndex

public int findGroupIndex(int group,
                 int start)

size

public int size()

Description copied from interface: Menu

Get the number of items in the menu. Note that this will change any times items are added or removed from the menu.

Specified by:

size in interface Menu

Returns:

The item count.

getItem

public MenuItem getItem(int index)

Gets the menu item at the given index.

Specified by:

getItem in interface Menu

Parameters:

index - The index of the menu item to return.

Returns:

The menu item.

isShortcutKey

public boolean isShortcutKey(int keyCode,
                    android.view.KeyEvent event)

Description copied from interface: Menu

Is a keypress one of the defined shortcut keys for this window.

Specified by:

isShortcutKey in interface Menu

Parameters:

keyCode - the key code from KeyEvent to check.

event - the KeyEvent to use to help check.

setQwertyMode

public void setQwertyMode(boolean isQwerty)

Description copied from interface: Menu

Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).

Specified by:

setQwertyMode in interface Menu

Parameters:

isQwerty - If true the menu will use alphabetic shortcuts; else it will use numeric shortcuts.

setShortcutsVisible

public void setShortcutsVisible(boolean shortcutsVisible)

Sets whether the shortcuts should be visible on menus. Devices without hardware key input will never make shortcuts visible even if this method is passed 'true'.

Parameters:

shortcutsVisible - Whether shortcuts should be visible (if true and a menu item does not have a shortcut defined, that item will still NOT show a shortcut)

isShortcutsVisible

public boolean isShortcutsVisible()

Returns:

Whether shortcuts should be visible on menus.

getContext

public android.content.Context getContext()

changeMenuMode

public void changeMenuMode()

Dispatch a mode change event to this menu's callback.

performShortcut

public boolean performShortcut(int keyCode,
                      android.view.KeyEvent event,
                      int flags)

Description copied from interface: Menu

Execute the menu item action associated with the given shortcut character.

Specified by:

performShortcut in interface Menu

Parameters:

keyCode - The keycode of the shortcut key.

event - Key event message.

flags - Additional option flags or 0.

Returns:

If the given shortcut exists and is shown, returns true; else returns false.

See Also:

Menu.FLAG_PERFORM_NO_CLOSE

performIdentifierAction

public boolean performIdentifierAction(int id,
                              int flags)

Description copied from interface: Menu

Execute the menu item action associated with the given menu identifier.

Specified by:

performIdentifierAction in interface Menu

Parameters:

id - Identifier associated with the menu item.

flags - Additional option flags or 0.

Returns:

If the given identifier exists and is shown, returns true; else returns false.

See Also:

Menu.FLAG_PERFORM_NO_CLOSE

performItemAction

public boolean performItemAction(MenuItem item,
                        int flags)

close

public void close()

Closes the menu, if open.

Specified by:

close in interface Menu

stopDispatchingItemsChanged

public void stopDispatchingItemsChanged()

Stop dispatching item changed events to presenters until startDispatchingItemsChanged() is called. Useful when many menu operations are going to be performed as a batch.

startDispatchingItemsChanged

public void startDispatchingItemsChanged()

flagActionItems

public void flagActionItems()

This method determines which menu items get to be 'action items' that will appear in an action bar and which items should be 'overflow items' in a secondary menu. The rules are as follows:

Items are considered for inclusion in the order specified within the menu. There is a limit of mMaxActionItems as a total count, optionally including the overflow menu button itself. This is a soft limit; if an item shares a group ID with an item previously included as an action item, the new item will stay with its group and become an action item itself even if it breaks the max item count limit. This is done to limit the conceptual complexity of the items presented within an action bar. Only a few unrelated concepts should be presented to the user in this space, and groups are treated as a single concept.

There is also a hard limit of consumed measurable space: mActionWidthLimit. This limit may be broken by a single item that exceeds the remaining space, but no further items may be added. If an item that is part of a group cannot fit within the remaining measured width, the entire group will be demoted to overflow. This is done to ensure room for navigation and other affordances in the action bar as well as reduce general UI clutter.

The space freed by demoting a full group cannot be consumed by future menu items. Once items begin to overflow, all future items become overflow items as well. This is to avoid inadvertent reordering that may break the app's intended design.

clearHeader

public void clearHeader()

setHeaderTitleInt

protected MenuBuilder setHeaderTitleInt(CharSequence title)

Sets the header's title. This replaces the header view. Called by the builder-style methods of subclasses.

Parameters:

title - The new title.

Returns:

This MenuBuilder so additional setters can be called.

setHeaderTitleInt

protected MenuBuilder setHeaderTitleInt(int titleRes)

Sets the header's title. This replaces the header view. Called by the builder-style methods of subclasses.

Parameters:

titleRes - The new title (as a resource ID).

Returns:

This MenuBuilder so additional setters can be called.

setHeaderIconInt

protected MenuBuilder setHeaderIconInt(android.graphics.drawable.Drawable icon)

Sets the header's icon. This replaces the header view. Called by the builder-style methods of subclasses.

Parameters:

icon - The new icon.

Returns:

This MenuBuilder so additional setters can be called.

setHeaderIconInt

protected MenuBuilder setHeaderIconInt(int iconRes)

Sets the header's icon. This replaces the header view. Called by the builder-style methods of subclasses.

Parameters:

iconRes - The new icon (as a resource ID).

Returns:

This MenuBuilder so additional setters can be called.

setHeaderViewInt

protected MenuBuilder setHeaderViewInt(android.view.View view)

Sets the header's view. This replaces the title and icon. Called by the builder-style methods of subclasses.

Parameters:

view - The new view.

Returns:

This MenuBuilder so additional setters can be called.

getHeaderTitle

public CharSequence getHeaderTitle()

getHeaderIcon

public android.graphics.drawable.Drawable getHeaderIcon()

getHeaderView

public android.view.View getHeaderView()

getRootMenu

public MenuBuilder getRootMenu()

Gets the root menu (if this is a submenu, find its root menu).

Returns:

The root menu.

setCurrentMenuInfo

public void setCurrentMenuInfo(android.view.ContextMenu.ContextMenuInfo menuInfo)

Sets the current menu info that is set on all items added to this menu (until this is called again with different menu info, in which case that one will be added to all subsequent item additions).

Parameters:

menuInfo - The extra menu information to add.

expandItemActionView

public boolean expandItemActionView(MenuItemImpl item)

collapseItemActionView

public boolean collapseItemActionView(MenuItemImpl item)

getExpandedItem

public MenuItemImpl getExpandedItem()

bindNativeOverflow

public boolean bindNativeOverflow(android.view.Menu menu,
                         android.view.MenuItem.OnMenuItemClickListener listener,
                         HashMap<android.view.MenuItem,MenuItemImpl> map)