danger.ui
Class BaseMenu

java.lang.Object
  danger.app.Listener
      danger.ui.View
          danger.ui.Container
              danger.ui.Control
                  danger.ui.BaseMenu

All Implemented Interfaces:

ToolTipOwner

Direct Known Subclasses:

ListSelectMenu, Menu

public abstract class BaseMenu
extends Control

Base functionality for menu controls.

NOTE: This class is not safe to use from more than one thread simultaneously. Use explicit synchronization for multi-threaded access.

Field Summary

static int	WITH_KEY_HELD Flag that can be passed to enterMenu(boolean).
static int	WITH_WIDGET_HELD Flag that can be passed to enterMenu(boolean).

Fields inherited from class danger.ui.Control

mValue

Fields inherited from class danger.ui.View

DEFAULT_SCROLL_FOCUS_MARGIN, FOCUS_DEFAULT, FOCUS_DOWNWARD, FOCUS_LEFTWARD, FOCUS_NONE, FOCUS_RIGHTWARD, FOCUS_UPWARD, mOriginX, mOriginY, mStyle, POSITION_ABOVE, POSITION_ALIGN_BASELINE, POSITION_ALIGN_BOTTOM, POSITION_ALIGN_HORIZONTALLY, POSITION_ALIGN_LEFT, POSITION_ALIGN_PARENT_BOTTOM, POSITION_ALIGN_PARENT_RIGHT, POSITION_ALIGN_RIGHT, POSITION_ALIGN_TOP, POSITION_ALIGN_VERTICALLY, POSITION_BELOW, POSITION_CENTER_HORIZONTALLY, POSITION_CENTER_VERTICALLY, POSITION_TO_LEFT, POSITION_TO_RIGHT, PREFER_DIRECTION_NONE, PREFER_HORIZONTAL_DIRECTION, PREFER_VERTICAL_DIRECTION, STATE_AT_AND_SPACE_PAGE, STATE_CAN_FOCUS, STATE_DEBUG_BOUNDS, STATE_ENABLED, STATE_FOCUSED, STATE_MAKE_DING, STATE_PARTIAL_FOCUS_OK, STATE_TRANSPARENT, STATE_VISIBLE, WIDTH_FILL_TO_RIGHT

Constructor Summary

BaseMenu()
Construct an instance with "" (the empty string) for the title and set not to show the title.

BaseMenu(String title)
Construct an instance with the given title but set not to show the title.

BaseMenu(String title, boolean showTitle)
Construct an instance with the given title and given setting for whether or not the title should be displayed.

Method Summary

void	addDivider() Add a divider to this menu.
void	addDivider(int id) Add a divider with the given ID to this menu.
void	addDividerAtPosition(int position) Insert a divider into this menu at the given position.
void	addFromResource(ResourceDatabase database, int id) Set up this menu based on the resource with the given ID from the given resource database.
void	addFromResource(ResourceDatabase database, int id, Listener listener) Set up this menu based on the resource with the given ID from the given resource database, and set all menu items to use the given listener.
void	addFromResource(ResourceDatabase database, int id, Listener listener, Window textEditBaseWindow) Set up this menu based on the resource with the given ID from the given resource database.
MenuItem	addItem(CharSequence inTitle) Add a menu item to this menu.
MenuItem	addItem(CharSequence title, int eventType) Add a menu item to this menu.
MenuItem	addItem(CharSequence title, int eventType, int eventWhat, int eventData, Object eventArg, Listener listener, int itemID) Add a menu item to this menu.
MenuItem	addItem(CharSequence title, int eventType, int eventData, Object eventArg, Listener listener) Add a menu item to this menu.
MenuItem	addItem(CharSequence title, int eventType, int eventData, Object eventArg, Listener listener, int itemID)
MenuItem	addItem(MenuItem m) Add the given menu item to this menu.
MenuItem	addItem(MenuItem m, int id) Add the given menu item to this menu with the given ID.
MenuItem	addItem(String inTitle) Add a menu item to this menu.
MenuItem	addItem(String title, int eventType) Add a menu item to this menu.
MenuItem	addItem(String title, int eventType, int eventWhat, int eventData, Object eventArg, Listener listener, int itemID) Add a menu item to this menu.
MenuItem	addItem(String title, int eventType, int eventData, Object eventArg, Listener listener) Add a menu item to this menu.
MenuItem	addItem(String title, int eventType, int eventData, Object eventArg, Listener listener, int itemID)
MenuItem	addItemAtPosition(MenuItem m, int position) Insert the given menu item into this menu at the given position.
void	addItemFromResource(ResourceDatabase database, int id, int menuItemID, int eventData, Object eventArg, Listener listener) Add an item to this menu based on the resource with the given ID from the given resource database.
void	addItemFromResource(ResourceDatabase database, int id, int menuItemID, Listener listener) Add an item to this menu based on the resource with the given ID from the given resource database.
void	addItems(MenuItem[] items) Add the elements of the given array of menu items to this menu, in order.
MenuItem	addLinkOptionItems(Window inBaseWindow) Add the menu items needed to support link option functionality.
MenuItem	addLinkOptionItems(Window inBaseWindow, int id) Add the menu items needed to support link option functionality.
MenuItem	addTextEditItems(Window inBaseWindow) Add the menu items needed to support text edit functionality.
MenuItem	addTextEditItems(Window inBaseWindow, int id) Add the menu items needed to support text edit functionality.
void	collateMenuItems() Sort the menu items in this menu by title according to locale rules.
void	enableItemWithID(int id, boolean inEnable) Enables or disables the menu item with the given ID, if such a menu item is in fact in the menu.
void	enterMenu() Indicate the the menu has been entered.
void	enterMenu(boolean springLoaded) Indicate that the menu has been entered, also indicating whether or not it is spring-loaded.
void	enterMenu(int flags) Indicate that the menu has been entered, and specify whether a widget and/or key is held down at this moment.
void	enterSubmenuForShortcut(char shortcut) Indicate the the submenu for the given shortcut has been entered.
void	exitMenu(boolean inKeepSelection) Indicate the the menu has been exited.
boolean	getAutoHideIfIdle() Get the flag indicating whether the menu should auto-hide after a period of inactivity.
Bitmap	getCheckedIcon() Get the icon to be used as a checkmark next to items.
boolean	getEllipsizeTruncatedMenuText() Get the flag indicating whether an ellipsis should be used when truncation of menu item text is required.
int	getIDOfItem(MenuItem item) Get the ID of the given item in this menu.
MenuItem	getItem(int n) Get the nth menu item in the menu.
MenuItem	getItemFromShortcut(char shortcut) Find and return a menu item that has the given shortcut character.
MenuItem	getItemWithID(int id) Get the menu item with the given ID.
MenuItem	getItemWithIDOrNull(int id) Get the menu item with the given ID or return null if there is no item with the given ID in the menu.
Bitmap	getMarkedIcon() Get the icon to be used as a generic mark next to items.
Window	getOwnerWindow() Get the Window that "owns" this instance, that is, the Window underneath that caused this menu to appear.
MenuItem	getSelectedItem() Get the currently selected item in this menu.
int	getSelectedItemID() Get the ID of the currently selected item in this menu.
boolean	getShowTitle() Get the flag indicating whether this menu's title should appear.
boolean	hasVisibleSubmenu() Return whether or not this menu has a currently-visible submenu.
void	hideItemWithID(int id) Hides the menu item with the given ID, if such a menu item is in fact in the menu.
int	indexOfItem(MenuItem item) Get the index of the given menu item in this menu, compared with ==.
int	indexOfItem(String title) Get the index of a menu item with the given title, compared with String.equals(java.lang.Object).
boolean	isDefaultSelectionFirstMenuItem() Get the flag indicating whether the menu selection should default to the first item in the menu.
boolean	isShortcutForSubmenu(char shortcut) Determine whether the given shortcut is for a submenu.
boolean	isSubmenu() Get the flag indicating whether this menu is in fact a submenu in a hierarchy.
int	itemCount() Return the number of items in this menu.
boolean	matchAndDispatchNonMenuShortcut(char shortcut, Event event)
boolean	matchAndDispatchShortcut(char shortcut, Event event) Match the given character as a menu shortcut.
protected void	onStyleChanged(int attribute) This method is called when the specified attribute of this view's style has been modified.
boolean	ownerWindowIsActive() Return whether or not the owner window of this menu is currently active.
void	removeAllItems() Remove all items from the menu.
void	removeItem(int index) Remove the nth item from the menu.
void	removeItemWithID(int id) Remove the menu item with the given ID, if such a menu item is in fact in the menu.
void	sendSelectionChangedEvent() Send an event indicating that the selection of this instance has changed.
void	setAutoHideIfIdle(boolean flag) Set or clear the flag indicating whether this menu should auto-hide after a period of inactivity.
void	setCheckedIcon(Bitmap inIcon) Set the icon to be used as a checkmark next to items.
void	setCheckedIcon(Bitmap inIcon, boolean invert) Set the icon to be used as a checkmark next to items.
void	setDefaultSelectionToFirstMenuItem(boolean flag) Set or clear the flag indicating whether the menu selection should default to the first item in the menu.
void	setEllipsizeTruncatedMenuText(boolean flag) Set or clear the flag indicating whether an ellipsis should be used when truncation of menu item text is required.
void	setListenerForAllItems(Listener listener) Set the listener for all menu items to the one given.
void	setMarkedIcon(Bitmap inIcon) Set the icon to be used as a generic mark next to items.
void	setMarkedIcon(Bitmap inIcon, boolean invert) Set the icon to be used as a generic mark next to items.
void	setMaxItemID(int id) Set the maximum ID that items with IDs that are added to this menu may have.
void	setMaxToolTipLines(int maxLines) Set the maximum number of lines to show in a tool tip.
void	setSelectionChangedListener(Listener listener, int event) Set the listener for selection-changed events, as well as the event type to use for such events.
void	setShowTitle(boolean flag) Set or clear the flag indicating whether this menu's title should appear.
void	setSubmenu(boolean flag) Set or clear the flag indicating whether this menu is in fact a submenu in a hierarchy.
void	showItemWithID(int id) Shows the menu item with the given ID, if such a menu item is in fact in the menu.
void	showItemWithID(int id, boolean inShow) Shows or hides the menu item with the given ID, if such a menu item is in fact in the menu.
void	sortMenuItems() Sort the menu items in this menu by title, case-sensitively.
void	uncheckAll() Uncheck all the items in the menu.
void	unmarkAll() Unmark all the items in the menu.
MenuItem	updateLinkOptionItems(Window inBaseWindow) Update the link option items in this menu, according to the state of the given target window.
MenuItem	updateTextEditItems(Window inBaseWindow) Update the text edit items in this menu, according to the state of the given target window.

Methods inherited from class danger.ui.Control

drawFocusBox, drawIdleBox, drawIdleBox, getBaseline, getEvent, getEventListener, getEventType, getHasBorder, getMaxToolTipLines, getTitle, getTitleSequence, getToolTip, getValue, hasToolTip, loseFocus, onSetHasBorder, onSetTitle, sendEvent, setEvent, setEvent, setEvent, setEvent, setEvent, setEventArg, setEventListener, setHasBorder, setTitle, setTitle, setToolTip, setValue, showToolTip, takeFocus

Methods inherited from class danger.ui.Container

addChild, addChild, addChildAt, addChildAt, addFromContainerResource, addFromContainerResource, addFromContainerResource, addFromDialogResource, addFromDialogResource, advanceFocus, advanceFocusInWindow, childCount, childIsOnScreen, disable, enable, eventKeyDown, eventKeyHeld, eventKeyRepeat, eventKeyUp, eventPeriodicPulse, eventRawKeyDown, eventRawKeyHeld, eventRawKeyRepeat, eventRawKeyUp, eventShortcut, eventWidgetDown, eventWidgetHeld, eventWidgetUp, focusedDescendantIsValid, getBottomChild, getBottomChild, getChildAt, getChildIndex, getChildWithID, getControlWithID, getDescendantWithID, getFirstChild, getFirstFocusableChild, getFocusableChildInWindow, getFocusedChild, getFocusedLeaf, getInterestingRect, getLastChild, getLastFocusableChild, getLeftMostChild, getNextFocusableChild, getNextFocusableChild, getPageHeight, getPrevFocusableChild, getPrevFocusableChild, getRightMostChild, getRightMostChild, handleButtonShortcut, hideAllChildren, isDescendant, keepRectInView, moveChildToIndex, onChildPositionChanged, onChildSizeChanged, onChildVisibilityChanged, pageToEnd, pageToHome, paint, paintChildren, receiveEvent, reflowChildren, removeAllChildren, removeChild, reverseFocus, setFocusedChild, setFocusedChild, setFocusedChild, setFocusedDescendant, setFocusedDescendant, setFocusedDescendant, setFocusToFirstDescendant, setFormatDateForControlWithID, setFormatDateForTextControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setListenerForAllControls, setReflowAdjustHeight, setWindow, showAllChildren, snapHeightToChildren, snapHeightToChildren, snapToChildren, snapWidthToChildren, snapWidthToChildren, willFocusWithin, willFocusWithin

Methods inherited from class danger.ui.View

boundsIntersect, boundsIntersect, canLoseFocus, clear, clear, copyStyle, getAcceptFocus, getBackgroundColor, getBottom, getBounds, getBounds, getFocusTraversalDirection, getFocusTraversalFrom, getFocusTraversalPolicy, getFrame, getFrame, getGlobalBottom, getGlobalLeft, getGlobalRight, getGlobalTop, getHeight, getID, getInterestingRect, getLabelFont, getLabelFont, getLeft, getOrigin, getOrigin, getOriginX, getOriginY, getParent, getParentContainer, getPartialFocusOK, getRight, getScrollFocusMargin, getSibling, getState, getStyle, getStyleColor, getStyleFont, getTop, getWidth, getWindow, globalToLocal, globalToLocalH, globalToLocalV, hide, invalidate, invalidate, invalidate, invalidateIndependentOfOrigin, invalidateIndependentOfOrigin, isEnabled, isFocusable, isFocused, isOnScreen, isTransparent, isVisible, isVisibleInHierarchy, isVisibleOnScreen, justSetVisible, localToGlobal, localToGlobal, localToGlobalH, localToGlobalV, localToWindow, moveBy, notifyWhenParentSizeChanges, notifyWhenPositionChanges, notifyWhenSizeChanges, offsetOrigin, offsetOrigin, onAddedToParent, onDecoded, onEnabledStateChanged, onHide, onPeriodicPulse, onPositionChanged, onRemovedFromParent, onShortcut, onShortcut, onShortcutConsumed, onShow, onSizeChanged, onViewPositionChanged, onViewSizeChanged, onWindowPaint, playLimitSound, receiveEventInternal, resetOrigin, sendEventToWindow, setAcceptFocus, setAtAndSpacePage, setBackground, setBackgroundColor, setBottom, setDebugBounds, setDynamicPosition, setDynamicWidth, setEnabled, setFocusTraversalDirection, setFocusTraversalFrom, setFocusTraversalPolicy, setFrame, setHeight, setKeyedValue, setLabelFont, setLeft, setMakeLimitNoise, setOrigin, setOrigin, setPartialFocusOK, setPosition, setPreferredDirection, setRight, setScrollFocusMargin, setSize, setStyle, setStyleColor, setStyleFont, setStyleFrameColor, setTop, setTransparent, setVisible, setWidth, shouldDropEvent, show, showContextMenu, styleIsDefault, swapStyleColors, windowToLocal

Methods inherited from class danger.app.Listener

cancelEvents, childEventPump, childEventPumpDone, eventProblem, isDispatchingThread, sendEvent, sendEvent, sendEvent, sendEvent, sendEvent, sendLowPriorityEvent

Methods inherited from class java.lang.Object

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

Field Detail

WITH_WIDGET_HELD

public static final int WITH_WIDGET_HELD

Flag that can be passed to enterMenu(boolean). Specifies that the menu was entered while a widget was being held down.

See Also:

Constant Field Values

WITH_KEY_HELD

public static final int WITH_KEY_HELD

Flag that can be passed to enterMenu(boolean). Specifies that the menu was entered while a key was being held down.

See Also:

Constant Field Values

Constructor Detail

BaseMenu

public BaseMenu()

Construct an instance with "" (the empty string) for the title and set not to show the title.

BaseMenu

public BaseMenu(String title)

Construct an instance with the given title but set not to show the title.

Parameters:

title - null-ok; the title; if passed as null, it is interpreted as "" (that is, the empty string)

BaseMenu

public BaseMenu(String title,
                boolean showTitle)

Construct an instance with the given title and given setting for whether or not the title should be displayed.

Parameters:

title - null-ok; the title; if passed as null, it is interpreted as "" (that is, the empty string)

showTitle - whether or not to show the title

Method Detail

onStyleChanged

protected void onStyleChanged(int attribute)

Description copied from class: View

This method is called when the specified attribute of this view's style has been modified. Base implementation does nothing.

Overrides:

onStyleChanged in class View

setMaxItemID

public final void setMaxItemID(int id)

Set the maximum ID that items with IDs that are added to this menu may have. IDs may range from 1 through the given value. This method will also clear the ID map, so it is not appropriate to call it once items with IDs have been added. (XXX: This description was written to describe existing behavior, but sounds sorta suspect.)

Parameters:

id - > 0; the maximum id

itemCount

public final int itemCount()

Return the number of items in this menu.

Returns:

>= 0; the number of items.

addFromResource

public final void addFromResource(ResourceDatabase database,
                                  int id)

Set up this menu based on the resource with the given ID from the given resource database.

Parameters:

database - non-null; the resource database to use

id - the ID of the menu

addFromResource

public final void addFromResource(ResourceDatabase database,
                                  int id,
                                  Listener listener)

Set up this menu based on the resource with the given ID from the given resource database, and set all menu items to use the given listener.

Parameters:

database - non-null; the resource database to use

id - the ID of the menu

listener - null-ok; the listener that the menu items should have

addFromResource

public final void addFromResource(ResourceDatabase database,
                                  int id,
                                  Listener listener,
                                  Window textEditBaseWindow)

Set up this menu based on the resource with the given ID from the given resource database. Set all menu items to use the given listener, and use the given window as the target for text edit menu items.

Parameters:

database - non-null; the resource database to use

id - the ID of the menu

listener - null-ok; the listener that the menu items should have, or null if they should initially have no listener

textEditBaseWindow - null-ok; the window that text edit items should target or null if they should initially have no target

addItemFromResource

public final void addItemFromResource(ResourceDatabase database,
                                      int id,
                                      int menuItemID,
                                      Listener listener)

Add an item to this menu based on the resource with the given ID from the given resource database. The item should have the given menu item ID and listener.

Parameters:

database - non-null; the resource database to use

id - the ID of the menu item in the resource database

menuItemID - the ID of the menu item in the menu

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

addItemFromResource

public final void addItemFromResource(ResourceDatabase database,
                                      int id,
                                      int menuItemID,
                                      int eventData,
                                      Object eventArg,
                                      Listener listener)

Add an item to this menu based on the resource with the given ID from the given resource database. The item should have the given menu item ID, event data, event argument, and listener.

Parameters:

database - non-null; the resource database to use

id - the ID of the menu item in the resource database

menuItemID - the ID of the menu item in the menu

eventData - the event data for the event triggered by the item

eventArg - null-ok; the event argument for the event triggered by the item

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

addDivider

public final void addDivider(int id)

Add a divider with the given ID to this menu.

Parameters:

id - >= 0; the ID, or 0 to indicate that the divider should have no ID

addDivider

public final void addDivider()

Add a divider to this menu. The divider will have no ID.

addDividerAtPosition

public final void addDividerAtPosition(int position)

Insert a divider into this menu at the given position.

Parameters:

position - >= 0 && <= itemCount(); the position to insert at

Throws:

IndexOutOfBoundsException - thrown if position is invalid

addItem

public final MenuItem addItem(String title,
                              int eventType,
                              int eventData,
                              Object eventArg,
                              Listener listener,
                              int itemID)

See Also:

"below"

addItem

public final MenuItem addItem(CharSequence title,
                              int eventType,
                              int eventData,
                              Object eventArg,
                              Listener listener,
                              int itemID)

See Also:

"below"

addItem

public final MenuItem addItem(String title,
                              int eventType,
                              int eventWhat,
                              int eventData,
                              Object eventArg,
                              Listener listener,
                              int itemID)

Add a menu item to this menu.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

eventWhat - the Event.what parameter for the event triggered by the item

eventData - the event data for the event triggered by the item

eventArg - null-ok; the event argument for the event triggered by the item

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

itemID - >= 0; the ID for the item or 0 to indicate that it should have no ID

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(CharSequence title,
                              int eventType,
                              int eventWhat,
                              int eventData,
                              Object eventArg,
                              Listener listener,
                              int itemID)

Add a menu item to this menu.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

eventWhat - the Event.what parameter for the event triggered by the item

eventData - the event data for the event triggered by the item

eventArg - null-ok; the event argument for the event triggered by the item

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

itemID - >= 0; the ID for the item or 0 to indicate that it should have no ID

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(String title,
                              int eventType,
                              int eventData,
                              Object eventArg,
                              Listener listener)

Add a menu item to this menu. The item will have no ID.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

eventData - the event data for the event triggered by the item

eventArg - null-ok; the event argument for the event triggered by the item

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(CharSequence title,
                              int eventType,
                              int eventData,
                              Object eventArg,
                              Listener listener)

Add a menu item to this menu. The item will have no ID.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

eventData - the event data for the event triggered by the item

eventArg - null-ok; the event argument for the event triggered by the item

listener - null-ok; the listener that the menu item should have, or null if it should initially have no listener

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(String title,
                              int eventType)

Add a menu item to this menu. The item will have 0 event data, null event argument, no (null) listener, and no ID.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(CharSequence title,
                              int eventType)

Add a menu item to this menu. The item will have 0 event data, null event argument, no (null) listener, and no ID.

Parameters:

title - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

eventType - the event type for the event triggered by the item

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(String inTitle)

Add a menu item to this menu. The item will have 0 event type and data, null event argument, no (null) listener, and no ID.

Parameters:

inTitle - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(CharSequence inTitle)

Add a menu item to this menu. The item will have 0 event type and data, null event argument, no (null) listener, and no ID.

Parameters:

inTitle - null-ok; the title for the item; if passed as null, interpreted to mean "" (that is, the empty string)

Returns:

non-null; the MenuItem that was added

addItem

public final MenuItem addItem(MenuItem m)

Add the given menu item to this menu.

Parameters:

m - non-null; the item to add

addItem

public final MenuItem addItem(MenuItem m,
                              int id)

Add the given menu item to this menu with the given ID.

Parameters:

m - non-null; the item to add

id - >= 0; the ID, or 0 to indicate that the divider should have no ID

addItemAtPosition

public final MenuItem addItemAtPosition(MenuItem m,
                                        int position)

Insert the given menu item into this menu at the given position.

Parameters:

m - non-null; the item to insert

position - >= 0 && <= itemCount(); the position to insert at

Throws:

IndexOutOfBoundsException - thrown if position is invalid

addItems

public final void addItems(MenuItem[] items)

Add the elements of the given array of menu items to this menu, in order.

Parameters:

items - non-null and with all non-null elements; array of items to add

Throws:

NullPointerException - thrown if items or any element of items is null; in the latter case, the menu items up to the offending null will have been added

hideItemWithID

public final void hideItemWithID(int id)

Hides the menu item with the given ID, if such a menu item is in fact in the menu. If not, this does nothing.

Parameters:

id - the ID of the menu item to hide

showItemWithID

public final void showItemWithID(int id)

Shows the menu item with the given ID, if such a menu item is in fact in the menu. If not, this does nothing.

Parameters:

id - the ID of the menu item to hide

showItemWithID

public final void showItemWithID(int id,
                                 boolean inShow)

Shows or hides the menu item with the given ID, if such a menu item is in fact in the menu. If not, this does nothing.

Parameters:

id - the ID of the menu item

inShow - whether to show or hide the item

enableItemWithID

public final void enableItemWithID(int id,
                                   boolean inEnable)

Enables or disables the menu item with the given ID, if such a menu item is in fact in the menu. If not, this does nothing.

Parameters:

id - the ID of the menu item

inEnable - whether to enable or disable the item

removeItem

public final void removeItem(int index)

Remove the nth item from the menu. It is an error to attempt to remove an item that doesn't exist.

Parameters:

index - >= 0 && < itemCount(); which item to remove

Throws:

IndexOutOfBoundsException - thrown if n is out of range

removeItemWithID

public final void removeItemWithID(int id)

Remove the menu item with the given ID, if such a menu item is in fact in the menu. If not, this does nothing.

Parameters:

id - the ID of the menu item to remove

removeAllItems

public final void removeAllItems()

Remove all items from the menu.

enterMenu

public final void enterMenu(boolean springLoaded)

Indicate that the menu has been entered, also indicating whether or not it is spring-loaded. This method simply sets the flag to indicate the spring-loaded status and then calls through to the no-args variant of enterMenu().

Spring-loaded menus are entered as a result of a "click and hold" gestures. Because the menu springs to life once the control is no longer held, we need to know not to dispatch MenuItem events on the WidgetUp event immediately following the WidgetHeld event.

Parameters:

springLoaded - whether or not the menu was entered in a spring-loaded fashion

enterMenu

public final void enterMenu(int flags)

Indicate that the menu has been entered, and specify whether a widget and/or key is held down at this moment. This method simply sets the flags to ignore the first widget up or key up event and then calls through to the no-args variant of enterMenu().

Parameters:

flags - zero or more of WITH_WIDGET_HELD and WITH_KEY_HELD.

enterMenu

public void enterMenu()

Indicate the the menu has been entered. This implementation is a no-op; it is up to subclasses to override it to do something useful.

enterSubmenuForShortcut

public void enterSubmenuForShortcut(char shortcut)

Indicate the the submenu for the given shortcut has been entered. This implementation is a no-op; it is up to subclasses to override it to do something useful.

exitMenu

public void exitMenu(boolean inKeepSelection)

Indicate the the menu has been exited. This implementation is a no-op; it is up to subclasses to override it to do something useful.

getItemWithID

public final MenuItem getItemWithID(int id)

Get the menu item with the given ID.

Parameters:

id - the ID of the item in question

Returns:

non-null; the menu item with the given ID

Throws:

IllegalArgumentException - thrown if there is no menu item with the given ID

getItemWithIDOrNull

public final MenuItem getItemWithIDOrNull(int id)

Get the menu item with the given ID or return null if there is no item with the given ID in the menu.

Parameters:

id - the ID of the item in question

Returns:

null-ok; the menu item with the given ID or null if there is no menu item with the given ID

getItem

public final MenuItem getItem(int n)

Get the nth menu item in the menu.

Parameters:

n - >= 0 && < itemCount(); which item to get

Returns:

non-null; the nth menu item

Throws:

IndexOutOfBoundsException - thrown if n is out of range

uncheckAll

public final void uncheckAll()

Uncheck all the items in the menu. That is, iterate over them calling MenuItem.uncheck() on each.

setCheckedIcon

public final void setCheckedIcon(Bitmap inIcon)

Set the icon to be used as a checkmark next to items.

Parameters:

inIcon - the icon to use

setCheckedIcon

public final void setCheckedIcon(Bitmap inIcon,
                                 boolean invert)

Set the icon to be used as a checkmark next to items.

Parameters:

inIcon - the icon to use

invert - if true, the icon is inverted when displayed in a selected menu item; if false, the icon is only inverted if inIcon is grayscale.

getCheckedIcon

public final Bitmap getCheckedIcon()

Get the icon to be used as a checkmark next to items.

Returns:

the icon to use

unmarkAll

public final void unmarkAll()

Unmark all the items in the menu. That is, iterate over them calling MenuItem.unmark() on each.

setMarkedIcon

public final void setMarkedIcon(Bitmap inIcon)

Set the icon to be used as a generic mark next to items.

Parameters:

inIcon - the icon to use

setMarkedIcon

public final void setMarkedIcon(Bitmap inIcon,
                                boolean invert)

Set the icon to be used as a generic mark next to items.

Parameters:

inIcon - the icon to use

invert - if true, the icon is inverted when displayed in a selected menu item; if false, the icon is only inverted if inIcon is grayscale.

getMarkedIcon

public final Bitmap getMarkedIcon()

Get the icon to be used as a generic mark next to items.

Returns:

the icon to use

setShowTitle

public final void setShowTitle(boolean flag)

Set or clear the flag indicating whether this menu's title should appear.

Parameters:

flag - whether (true) or not (false) the title should appear

getShowTitle

public final boolean getShowTitle()

Get the flag indicating whether this menu's title should appear.

Returns:

whether (true) or not (false) the title should appear

setDefaultSelectionToFirstMenuItem

public final void setDefaultSelectionToFirstMenuItem(boolean flag)

Set or clear the flag indicating whether the menu selection should default to the first item in the menu. (XXX--can someone explain this better, please?)

Parameters:

flag - whether (true) or not (false) the default should be the first menu item

isDefaultSelectionFirstMenuItem

public final boolean isDefaultSelectionFirstMenuItem()

Get the flag indicating whether the menu selection should default to the first item in the menu.

Returns:

whether (true) or not (false) the default should be the first menu item

setAutoHideIfIdle

public final void setAutoHideIfIdle(boolean flag)

Set or clear the flag indicating whether this menu should auto-hide after a period of inactivity.

Parameters:

flag - whether (true) or not (false) the menu should auto-hide

getAutoHideIfIdle

public final boolean getAutoHideIfIdle()

Get the flag indicating whether the menu should auto-hide after a period of inactivity.

Returns:

whether (true) or not (false) the menu should auto-hide

setSubmenu

public final void setSubmenu(boolean flag)

Set or clear the flag indicating whether this menu is in fact a submenu in a hierarchy.

Parameters:

flag - whether (true) or not (false) this instance is a submenu

isSubmenu

public final boolean isSubmenu()

Get the flag indicating whether this menu is in fact a submenu in a hierarchy.

Returns:

whether (true) or not (false) this instance is a submenu

setEllipsizeTruncatedMenuText

public final void setEllipsizeTruncatedMenuText(boolean flag)

Set or clear the flag indicating whether an ellipsis should be used when truncation of menu item text is required.

Parameters:

flag - whether (true) or not (false) to ellipsize truncated menu text

getEllipsizeTruncatedMenuText

public final boolean getEllipsizeTruncatedMenuText()

Get the flag indicating whether an ellipsis should be used when truncation of menu item text is required.

Returns:

whether (true) or not (false) to ellipsize truncated menu text

matchAndDispatchShortcut

public boolean matchAndDispatchShortcut(char shortcut,
                                        Event event)

Match the given character as a menu shortcut. If a match is found, perform the appropriate action and return true. Otherwise, do nothing and return false. The default implementation does nothing but return false. Subclasses should override it as appropriate.

Parameters:

shortcut - the shortcut character

event - the event associated with the key press

Returns:

whether (true) or not (false) the shortcut was matched and handled

matchAndDispatchNonMenuShortcut

public boolean matchAndDispatchNonMenuShortcut(char shortcut,
                                               Event event)

isShortcutForSubmenu

public boolean isShortcutForSubmenu(char shortcut)

Determine whether the given shortcut is for a submenu.

Parameters:

shortcut - the shortcut character

Returns:

whether (true) or not (false) the shortcut is for a submenu.

setListenerForAllItems

public final void setListenerForAllItems(Listener listener)

Set the listener for all menu items to the one given. This simply iterates over the items calling MenuItem.setListener(danger.app.Listener) on each.

Parameters:

listener - null-ok; the listener to set

setSelectionChangedListener

public final void setSelectionChangedListener(Listener listener,
                                              int event)

Set the listener for selection-changed events, as well as the event type to use for such events. These values are only ever used by sendSelectionChangedEvent().

Parameters:

listener - null-ok; the listener; if null, then calls to sendSelectionChangedEvent() become a no-op

event - the event type for selection-changed events

sendSelectionChangedEvent

public final void sendSelectionChangedEvent()

Send an event indicating that the selection of this instance has changed. The event gets sent to the listener specified by a previous call to setSelectionChangedListener(danger.app.Listener, int), and has the type also specified in that call. The event subtype is the current value (that is, what would be returned by Control.getValue()), the event data is 0, and the event argument is the currently selected menu item (that is, what would be returned by getSelectedItem().

This call does nothing if there is no selection-changed listener (because setSelectionChangedListener(danger.app.Listener, int) was never called or because it was called and passed null for the listener argument).

getOwnerWindow

public Window getOwnerWindow()

Get the Window that "owns" this instance, that is, the Window underneath that caused this menu to appear. By default this returns the same thing as View.getWindow(), but subclasses may override this to do something more appropriate.

Returns:

null-ok; the owner window or null if this instance does not seem to have an owner

ownerWindowIsActive

public final boolean ownerWindowIsActive()

Return whether or not the owner window of this menu is currently active. This will return true if one of the following conditions holds: (a) the owner window is null; (b) the owner window is an instance of DialogWindow; or (c) the owner window is the frontmost application window on the device.

Returns:

whether or not the owner window is active

sortMenuItems

public final void sortMenuItems()

Sort the menu items in this menu by title, case-sensitively.

collateMenuItems

public final void collateMenuItems()

Sort the menu items in this menu by title according to locale rules.

hasVisibleSubmenu

public final boolean hasVisibleSubmenu()

Return whether or not this menu has a currently-visible submenu. This simply iterates over all the menu items, calling MenuItem.submenuIsVisible() on each, returning true as soon as that call returns true. If that never happens, it returns false.

Returns:

whether or not this instance has a currently-visible submenu

getSelectedItem

public final MenuItem getSelectedItem()

Get the currently selected item in this menu.

Returns:

null-ok; the currently selected item or null if there is no selection

getSelectedItemID

public final int getSelectedItemID()

Get the ID of the currently selected item in this menu. This is the same as calling getIDOfItem(getSelectedItem()).

Returns:

>= 0; the ID of the currently selected item

addLinkOptionItems

public final MenuItem addLinkOptionItems(Window inBaseWindow)

Add the menu items needed to support link option functionality.

Parameters:

inBaseWindow - non-null; the target window

Returns:

non-null; the main text edit item (submenu containing the various link option items)

addLinkOptionItems

public final MenuItem addLinkOptionItems(Window inBaseWindow,
                                         int id)

Add the menu items needed to support link option functionality.

Parameters:

inBaseWindow - non-null; the target window

id - the id to assign to the menu item containing the submenu

Returns:

non-null; the main text edit item (submenu containing the various link option items)

updateLinkOptionItems

public final MenuItem updateLinkOptionItems(Window inBaseWindow)

Update the link option items in this menu, according to the state of the given target window. This method is called automatically by ScreenWindow.adjustActionMenuState().

Parameters:

inBaseWindow - non-null; the target window

Returns:

null-ok; the main text edit item (submenu containing the various text edit items) or null if this menu doesn't actually have any text edit items in it

addTextEditItems