com.livescribe.ext.ui
Class Menu

java.lang.Object
  com.livescribe.ext.ui.Menu

Direct Known Subclasses:

RadioMenu

public class Menu
extends Object

A class to make it easier to build browse list-based menus. This represents a list of items, some of which may be selectable submenus.

Internally, this maps browse list items to sub-menus.

Since:

2.3

Note:

This class is not thread safe.

Nested Class Summary

static interface	Menu.MenuAction This interface provides a way for menu selection to trigger an action.
protected class	Menu.MenuBrowseList A special BrowseList implementation that allows the menu to access some protected methods and override others.
protected static class	Menu.MenuItem An implementation of a browse list item.
static interface	Menu.MenuListener This interface listens to menu changes or events.

Constructor Summary

Menu()
Creates a new menu with no title.

Menu(Object title)
Creates a new menu having the specified title.

Method Summary

void	add(Object text) Adds a non-selectable item to the menu.
void	add(Object text, Image icon, String audio, Menu.MenuAction action, Menu submenu) Adds a new item to the menu.
void	add(Object text, Menu.MenuAction action) Adds a non-selectable item to the menu.
void	add(Object text, Menu submenu) Adds a selectable item to the menu.
void	addAction(int index, Menu.MenuAction action) Adds an action for the item at the specified index.
void	addMenuListener(Menu.MenuListener listener) Adds a menu listener to this menu.
protected Menu.MenuBrowseList	createBrowseList(Vector items, BrowseList.Title title) This gives subclasses the opportunity to use their own Menu.MenuBrowseList implementation, for example to paint icons differently.
Menu	doSelect(int index, Display display, MediaPlayer player) Selects an item as if it was chosen with a tap on the NavPlus right arrow.
protected void	fireItemChanged(int oldIndex, int newIndex, boolean activated) Notifies the listener that an item was changed.
protected void	fireItemSelected(int index) Notifies the listener that an item was selected.
protected void	fireMenuShown() Notifies the listener that the menu was shown on the display.
protected BrowseList	getBrowseList() Gets the browse list display object.
int	getFocusIndex() Gets the index of the item that currently has the focus.
int	getItemCount() Gets the item count.
Object	getMetadata() Returns the metadata associated with this menu.
Object	getMetadata(int index) Gets the metadata associated with the specified menu item.
Menu	getParent() Returns the parent menu, or null if this menu has no parent.
Menu	getSubmenu(int index) Gets the submenu for the item at the specified index.
Menu	handleMenuEvent(MenuEvent event, Display display, MediaPlayer player) Handles a menu event by properly displaying the information.
boolean	isSelectable(int index) Returns whether the item at the specified index is selectable.
void	remove(int index) Removes the menu item at the specified index.
void	removeMenuListener(Menu.MenuListener listener) Removes a menu listener.
void	setAudio(int index, String audio) Sets the audio to be played when the specified menu item has the focus.
void	setBackAPM(String clip) Sets the sound to play when the user navigates to a parent menu.
void	setBookmarkable(int index, Bookmarkable b) Sets the specified menu as bookmarkable.
static void	setDefaultBackAPM(String clip) Sets the default sound to play when the user navigates to a parent menu.
static void	setDefaultForwardAPM(String clip) Sets the default sound to play when the user navigates to a submenu.
static void	setDefaultSelectAPM(String clip) Sets the default sound to play when the user selects a menu item having no submenu.
void	setFocusIndex(int index) Sets the item index that should have the focus.
void	setForwardAPM(String clip) Sets the sound to play when the user navigates to a submenu.
void	setIcon(int index, Image icon) Sets the icon for the item at the specified index.
void	setLastItemBookmarkable(Bookmarkable b) A convenience method that sets the last menu item's bookmark info.
void	setMetadata(int index, Object data) Attaches some arbitrary metadata to a specific menu item.
void	setMetadata(Object data) Attaches some arbitrary metadata to this menu.
void	setOneWayParent(Menu parent) Sets the parent for this menu to be the specified menu but does not add this menu to the parent.
void	setPlayBackAPM(boolean flag) Sets whether to play the back sound.
void	setPlayForwardAPM(boolean flag) Sets whether to play the back sound.
void	setPlaySelectAPM(boolean flag) Sets whether to play the back sound.
void	setSelectable(int index, boolean flag) Sets the item at the specified index as selectable or not selectable, depending on the flag.
void	setSelectAPM(String clip) Sets the sound to play when the user selects a menu item having no submenu.
void	setSubmenu(int index, Menu submenu) Sets the submenu at the specified index.
void	setText(int index, Object text) Sets the text for the specified menu item.
void	show(Display display, Transition t) Shows the menu on the specified display using the specified transition.
String	toString() Returns a string representation of this menu.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Menu

public Menu()

Creates a new menu with no title.

Menu

public Menu(Object title)

Creates a new menu having the specified title. The title text may be an AttributedText object or a plain string; it may also be null.

Parameters:

title - the menu title, may be null

Throws:

IllegalArgumentException - if the title is not valid text.

Method Detail

addMenuListener

public void addMenuListener(Menu.MenuListener listener)

Adds a menu listener to this menu. This does nothing if the listener is null.

Parameters:

listener - the new menu listener

removeMenuListener

public void removeMenuListener(Menu.MenuListener listener)

Removes a menu listener. This does nothing if the listener is null or if it has not already been added.

Parameters:

listener - the listener to remove

Since:

2.5

add

public void add(Object text)

Adds a non-selectable item to the menu. The text may be an AttributedText object or a plain string.

Parameters:

text - the menu text

Throws:

IllegalArgumentException - if the text is not a valid type.

See Also:

add(Object, Image, String, MenuAction, Menu)

add

public void add(Object text,
                Menu submenu)

Adds a selectable item to the menu. The text may be an AttributedText object or a plain string.

Parameters:

text - the menu text

submenu - the submenu

Throws:

IllegalArgumentException - if the text is not a valid type.

See Also:

add(Object, Image, String, MenuAction, Menu)

add

public void add(Object text,
                Menu.MenuAction action)

Adds a non-selectable item to the menu.

Parameters:

text - the menu text

action - this is executed when the specified menu is selected

Throws:

IllegalArgumentException - if the text is not a valid type.

See Also:

add(Object, Image, String, MenuAction, Menu)

add

public void add(Object text,
                Image icon,
                String audio,
                Menu.MenuAction action,
                Menu submenu)

Adds a new item to the menu. If the submenu is not null then the item will be selectable. The text may be an AttributedText object or a plain string.

If the submenu already has a parent, then it will be replaced with this menu.

When the menu is selected via forward, the specified action is executed. It may be null if no action is to be executed.

Parameters:

text - the menu text

icon - the menu icon, may be null

audio - the item's audio

action - this is executed when the specified menu is selected, may be null

submenu - the submenu, may be null

Throws:

NullPointerException - if the text is null.

IllegalArgumentException - if the text is not a valid type.

See Also:

getParent()

remove

public void remove(int index)

Removes the menu item at the specified index.

Parameters:

index - index at which to remove the item

Throws:

IndexOutOfBoundsException - if the index is out of range.

Since:

2.5

See Also:

getItemCount()

getItemCount

public int getItemCount()

Gets the item count.

Returns:

the item count.

setBookmarkable

public void setBookmarkable(int index,
                            Bookmarkable b)

Sets the specified menu as bookmarkable. If b is null then the item will no longer be bookmarkable. If the item is already bookmarkable then the information will be replaced by the given Bookmarkable parameter.

Parameters:

index - the item index

b - the bookmarking information, null to unset

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

Bookmarkable, BookmarkInfo, getItemCount()

setLastItemBookmarkable

public void setLastItemBookmarkable(Bookmarkable b)

A convenience method that sets the last menu item's bookmark info. This does nothing if the menu is empty.

Parameters:

b - the new bookmark information

See Also:

setBookmarkable(int, Bookmarkable), getItemCount()

setAudio

public void setAudio(int index,
                     String audio)

Sets the audio to be played when the specified menu item has the focus.

Parameters:

index - set the audio for the item at this index

audio - the new audio, may be null

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setText

public void setText(int index,
                    Object text)

Sets the text for the specified menu item. The text may be an AttributedText object or a plain string.

Parameters:

index - set the text of the item at this index

text - the new menu text

Throws:

IllegalArgumentException - if the text is not a valid type.

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setSelectable

public void setSelectable(int index,
                          boolean flag)

Sets the item at the specified index as selectable or not selectable, depending on the flag. If the flag is true the item will be set as selectable regardless if there is a submenu at that location. On a Menu.MenuBrowseList, selectable items will be painted with a right arrow.

Parameters:

index - set the selectable state of the item at this index

flag - whether the item is selectable

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

isSelectable

public boolean isSelectable(int index)

Returns whether the item at the specified index is selectable. An item will be selectable if it has a submenu or if it was set as non-selectable via setSelectable.

Parameters:

index - the item index

Returns:

whether the item at the specified index is selectable.

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setIcon

public void setIcon(int index,
                    Image icon)

Sets the icon for the item at the specified index.

Parameters:

index - set the icon for the item at this index

icon - the new icon, may be null

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setDefaultBackAPM

public static void setDefaultBackAPM(String clip)

Sets the default sound to play when the user navigates to a parent menu. This usually happens when the left NavPlus arrow is tapped. The sound is played before the parent's itemChanged handler is called. However, the sound is not played if there is no parent menu. This is set to null by default.

Parameters:

clip - the new default back sound clip, null to unset

setDefaultForwardAPM

public static void setDefaultForwardAPM(String clip)

Sets the default sound to play when the user navigates to a submenu. This usually happens when the right NavPlus arrow is tapped. The sound is played after the current menu's itemSelected and execute handlers are called. However, the sound is not played if there is no submenu. This is set to null by default.

Parameters:

clip - the new default forward sound clip, null to unset

setDefaultSelectAPM

public static void setDefaultSelectAPM(String clip)

Sets the default sound to play when the user selects a menu item having no submenu. This usually happens when the right NavPlus arrow is tapped. If the current item does not have a submenu then the sound is played before current menu's itemSelected and execute handlers are called. This is set to null by default.

Parameters:

clip - the new default select sound clip, null to unset

setBackAPM

public void setBackAPM(String clip)

Sets the sound to play when the user navigates to a parent menu. This overrides the default sound. If this is set to null then the default sound will be used. This is set to null by default.

Parameters:

clip - the new back sound clip, null to unset

See Also:

setDefaultBackAPM(String)

setForwardAPM

public void setForwardAPM(String clip)

Sets the sound to play when the user navigates to a submenu. This overrides the default sound. If this is set to null then the default sound will be used. This is set to null by default.

Parameters:

clip - the new forward sound clip, null to unset

See Also:

setDefaultForwardAPM(String)

setSelectAPM

public void setSelectAPM(String clip)

Sets the sound to play when the user selects a menu item having no submenu. This overrides the default sound. If this is set to null then the default sound will be used. This is set to null by default.

Parameters:

clip - the new select sound clip, null to unset

See Also:

setDefaultSelectAPM(String)

setPlayBackAPM

public void setPlayBackAPM(boolean flag)

Sets whether to play the back sound. This is useful for when the default sound is set but only one or a few menus don't want to have the sound play. If this is set to false then the sound will never play. The default is true.

Parameters:

flag - whether to play any back sound

setPlayForwardAPM

public void setPlayForwardAPM(boolean flag)

Sets whether to play the back sound. This is useful for when the default sound is set but only one or a few menus don't want to have the sound play. If this is set to false then the sound will never play. The default is true.

Parameters:

flag - whether to play any back sound

setPlaySelectAPM

public void setPlaySelectAPM(boolean flag)

Sets whether to play the back sound. This is useful for when the default sound is set but only one or a few menus don't want to have the sound play. If this is set to false then the sound will never play. The default is true.

Parameters:

flag - whether to play any select sound

addAction

public void addAction(int index,
                      Menu.MenuAction action)

Adds an action for the item at the specified index.

Parameters:

index - set the action for the item at this index

action - the new action, may be null

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setOneWayParent

public void setOneWayParent(Menu parent)

Sets the parent for this menu to be the specified menu but does not add this menu to the parent. The new parent can be null.

This method is useful when it is necessary to back out of a menu, say from a transient result, and not be able to navigate back.

Parameters:

parent - the new parent for this menu

setMetadata

public void setMetadata(Object data)

Attaches some arbitrary metadata to this menu.

This can be useful, for example, when a listener object common to several menus needs to quickly determine the identity of the menu it was handed.

Parameters:

data - the new metadata, may be null

See Also:

getMetadata()

getMetadata

public Object getMetadata()

Returns the metadata associated with this menu.

Returns:

the metadata associated with this menu, may be null.

See Also:

setMetadata(Object)

setMetadata

public void setMetadata(int index,
                        Object data)

Attaches some arbitrary metadata to a specific menu item.

Parameters:

index - the item index

data - the new metadata, may be null

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

getMetadata

public Object getMetadata(int index)

Gets the metadata associated with the specified menu item.

Parameters:

index - the item index

Returns:

the metadata associated with the menu item, may be null.

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

getParent

public Menu getParent()

Returns the parent menu, or null if this menu has no parent. A menu can have only one parent.

Returns:

the parent menu, or null if this menu has no parent.

See Also:

add(Object, Image, String, MenuAction, Menu)

getSubmenu

public Menu getSubmenu(int index)

Gets the submenu for the item at the specified index. If the item does not have a submenu then this returns null.

Parameters:

index - get the submenu for the item at this index

Returns:

the submenu for the specified menu item, or null if the item does not have a submenu.

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount()

setSubmenu

public void setSubmenu(int index,
                       Menu submenu)

Sets the submenu at the specified index. A submenu can be removed by setting it to null.

Parameters:

index - sets the submenu at this index

submenu - the new submenu, may be null to remove

Throws:

IndexOutOfBoundsException - if the index is out of range.

Since:

2.5

See Also:

getItemCount()

createBrowseList

protected Menu.MenuBrowseList createBrowseList(Vector items,
                                               BrowseList.Title title)

This gives subclasses the opportunity to use their own Menu.MenuBrowseList implementation, for example to paint icons differently.

This is used by getBrowseList().

Parameters:

items - the items

title - the title

Returns:

a new Menu.MenuBrowseList.

getBrowseList

protected BrowseList getBrowseList()

Gets the browse list display object. If the menu has not changed since the last call to this method then the previous browse list will be returned.

This uses createBrowseList(Vector, BrowseList.Title) to create the browse list.

The browse list returned by this method should not be used to show the menu, as some internal state may not get updated properly and listeners may not get properly notified. Instead, use the show(Display, Transition) method.

Returns:

the browse list display object.

See Also:

createBrowseList(Vector, BrowseList.Title), show(Display, Transition)

fireItemChanged

protected void fireItemChanged(int oldIndex,
                               int newIndex,
                               boolean activated)

Notifies the listener that an item was changed.

Parameters:

oldIndex - the old index

newIndex - the new index

activated - whether the menu was activated

See Also:

Menu.MenuListener.itemChanged(Menu, int, int, boolean)

fireItemSelected

protected void fireItemSelected(int index)

Notifies the listener that an item was selected.

Parameters:

index - the item index

See Also:

Menu.MenuListener.itemSelected(Menu, int)

fireMenuShown

protected void fireMenuShown()

Notifies the listener that the menu was shown on the display.

See Also:

Menu.MenuListener.menuShown(Menu)

setFocusIndex

public void setFocusIndex(int index)

Sets the item index that should have the focus. Note that currently, browse lists do not support setting the current item to the title, so the index must be ≥ zero.

The menu listener will be notified with an item-changed event and with its activated parameter set to false.

Parameters:

index - the new index

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount(), Menu.MenuListener.itemChanged(Menu, int, int, boolean)

getFocusIndex

public int getFocusIndex()

Gets the index of the item that currently has the focus. This will return -1 if the title is showing.

Returns:

the index of the currently focused item.

show

public void show(Display display,
                 Transition t)

Shows the menu on the specified display using the specified transition. The display's current transition will not be changed after this method completes.

The menu listener will be notified with an item-changed event and with its activated parameter set to true. The notification will happen just before it is made active on the display.

After the menu is shown on the display, a menu-shown event is sent.

Parameters:

display - the display

t - the transition

See Also:

Transition, Menu.MenuListener.itemChanged(Menu, int, int, boolean), Menu.MenuListener.menuShown(Menu)

doSelect

public Menu doSelect(int index,
                     Display display,
                     MediaPlayer player)

Selects an item as if it was chosen with a tap on the NavPlus right arrow. This returns the new menu if there is a submenu and this otherwise.

Parameters:

index - select this menu item

display - use this display

player - an optional media player

Returns:

the submenu if there is one, and this if there is no submenu.

Throws:

IndexOutOfBoundsException - if the index is out of range.

See Also:

getItemCount(), setForwardAPM(String)

handleMenuEvent

public Menu handleMenuEvent(MenuEvent event,
                            Display display,
                            MediaPlayer player)

Handles a menu event by properly displaying the information. The display and player arguments are the visual and audio UI objects used to indicate any menu effects and changes.

This will return itself if we have not changed to a parent menu or submenu.

Parameters:

event - the menu event

display - the display object for setting the browse lists

player - an optional media player

Returns:

the new menu, if we have navigated forward or backwards.

toString

public String toString()

Returns a string representation of this menu.

Overrides:

toString in class Object

Returns:

a string representation of this menu.