com.ccg.awt
Class MenuChoice

java.lang.Object
  java.awt.MenuComponent
      java.awt.MenuItem
          java.awt.Menu
              com.ccg.awt.MenuChoice

All Implemented Interfaces:

ItemListener, ItemSelectable, MenuContainer, Serializable, EventListener, Accessible

public class MenuChoice
extends Menu
implements ItemListener, ItemSelectable

Create a flyout menu of choices from a LookupKeyed.

This class is designed to simplify the task of presenting a list of choices to a user. The current implementation forces the user to select exactly one of the choices shown. The developer can check what is currently selected via the getText() and getNumber() methods.

In addition, if you want to monitor when the user makes a new selection, you can use the addItemListener(java.awt.event.ItemListener) method.

Also, check out the static create(com.ccg.util.Lookup, java.lang.String) method which lets one dynamically load the menu from a Lookup object. This simplifies the process of localizing your menus.

Since:

1.0

Version:

$Revision: 1.6 $

Author:

$Author: pkb $

See Also:

create(com.ccg.util.Lookup, java.lang.String), Demo.html, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Menu

Menu.AccessibleAWTMenu

Nested classes/interfaces inherited from class java.awt.MenuItem

MenuItem.AccessibleAWTMenuItem

Nested classes/interfaces inherited from class java.awt.MenuComponent

MenuComponent.AccessibleAWTMenuComponent

Constructor Summary

MenuChoice(String name, boolean isTearOff, LookupKeyed cf)
Create the menu object and add a bunch of menu items.

Method Summary

void	addItemListener(ItemListener l) Monitor the object for changes in selection.
static MenuChoice	create(Lookup lookup, String tag) The easy way to create localizable flyout menu choices.
Number	getNumber() Get the Number representation of the current selection.
Object	getObject() Get the associated object with the current selection.
Object[]	getSelectedObjects() Get the selected item.
String	getText() Get the current text which has been selected by the user.
void	itemStateChanged(ItemEvent e) Monitor the user's current choice.
void	removeItemListener(ItemListener l) Stop listening for changes in state.
void	setNumberFormat(NumberFormat nf) Set the parser used to convert strings to numeric values.
void	setText(String text) Set which item is currently selected.

Methods inherited from class java.awt.Menu

add, add, addNotify, addSeparator, countItems, getAccessibleContext, getItem, getItemCount, insert, insert, insertSeparator, isTearOff, paramString, remove, remove, removeAll, removeNotify

Methods inherited from class java.awt.MenuItem

addActionListener, deleteShortcut, disable, disableEvents, enable, enable, enableEvents, getActionCommand, getActionListeners, getLabel, getListeners, getShortcut, isEnabled, processActionEvent, processEvent, removeActionListener, setActionCommand, setEnabled, setLabel, setShortcut

Methods inherited from class java.awt.MenuComponent

dispatchEvent, getFont, getName, getParent, getPeer, getTreeLock, postEvent, setFont, setName, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.awt.MenuContainer

getFont, postEvent

Constructor Detail

MenuChoice

public MenuChoice(String name,
                  boolean isTearOff,
                  LookupKeyed cf)

Create the menu object and add a bunch of menu items. This constructor creates a new Menu object (this object) and adds a bunch of menu choice items to it based on the contents of the LookupKeyed object passed. At construction time, none of the available options will be initially selected. Use the setText(java.lang.String) method if there is a particular option you want to initially set (or be lazy and use the create(com.ccg.util.Lookup, java.lang.String) method and let it do the work for you).

Parameters:

name - Name form the menu (same as Menu).

tearOff - Do you want a tear off menu? (typically set to false).

cf - The LookupKeyed used to initialize the flyout menu choices with. The string representation of each key in the LookupKeyed table is added as an available option.

Since:

1.0

See Also:

create(com.ccg.util.Lookup, java.lang.String)

Method Detail

setText

public void setText(String text)

Set which item is currently selected. This method allows one to set the currently selected item in the flyout choice menu. It verifies that the text entered is valid and different than the current item selected. It then unselects the current item, sets the one specified and notifies all of the item listeners that a new choice has been selected. This method is called automatically when the user selects an item (so you don't need to worry about the user's actions).

Parameters:

text - New value to set the selected item to. Ok if null or not one of the allowed values.

Since:

1.0

See Also:

getText(), getNumber()

getText

public String getText()

Get the current text which has been selected by the user. This method returns the currently selected item by its text value (what the user sees). If no item is currently selected, then null is returned.

Returns:

Text value (what the user sees) of the currently selected item.

Since:

1.0

See Also:

getNumber(), setText(java.lang.String)

getObject

public Object getObject()

Get the associated object with the current selection. This method returns the object associated with currently selected item by its text value (what the user sees). If no item is currently selected, then null is returned.

Returns:

Object associated with the currently selected item.

Since:

1.0

See Also:

getNumber(), setText(java.lang.String)

getNumber

public Number getNumber()

Get the Number representation of the current selection.

This method uses the getObject() method to fetch the data currently associated with the users current selection. It then takes the string representation of this value and converts it to to a Number object using either the systems default number parser, or the specific number parser last set via setNumberFormat(java.text.NumberFormat).

Returns:

Number object associated with the currently selected item, or null if no item is currently selected or there was a problem with the conversion to a number.

Since:

1.0

See Also:

getText(), getObject(), setNumberFormat(java.text.NumberFormat)

setNumberFormat

public void setNumberFormat(NumberFormat nf)

Set the parser used to convert strings to numeric values. By default, the getNumber() method uses the system default number parser for parsing strings to numeric values. This may work for most cases, however if you want to specify a object to convert the associated data values (from the getObject() method) to a Number), you can use this method.

Parameters:

arg1 - Any object derived from NumberFormat which is capable of converting strings to Numbers.

Since:

1.0

See Also:

getNumber()

itemStateChanged

public void itemStateChanged(ItemEvent e)

Monitor the user's current choice. This method is not intended for other to call (you should use the setText(java.lang.String) method directly instead). It is used internally by this object to monitor when the user selects one of the items in the list of choices. It gets the text of the selection made and then invokes the setText(java.lang.String) method to update this object and notify any interested listeners.

Specified by:

itemStateChanged in interface ItemListener

Parameters:

ie - ItemEvent which is occurring.

Since:

1.0

See Also:

setText(java.lang.String)

create

public static MenuChoice create(Lookup lookup,
                                String tag)

The easy way to create localizable flyout menu choices. This method creates a MenuChoice object based on the contents of a Lookup object. This has two nice advantages. One, it simplifies the process of localizing your application. Two, it removes the decision of what should appear in the menu from the code. Using this method, you can use standard Java property files to:

• Control whether or not your menu choices even exist (you can prevent menus from being shown).
• Control what strings are presented as choices to the user and what numeric values are associated with each string.
• Control whether a default item is selected initially, and if so which one.

Consider the following example resource file:

 # Options for the size of the last flash marker (under Setting menu)
 # It's a choose one option menu. Commenting out either value disables
 # the menu from appearing in the applet

 Marker.label=Last Marker
 Marker.choices=4816322000
 Marker.default=Medium
 

If we were to load the above resource file as a ResourceBundle indirectly using the TagLookup class. For example, if we were working on the "MyProj" class in the "myproject" package, we could store its resources in "myproject.MyProjStrings" (don't forget the ".poperties" extension). The following code fragment demonstrates how this approach could be used:

 void foo(myproject.MyProj ms) {
   Lookup _strings = new TagLookup(ms.getClass(),null);
   MenuChoice mc = MenuChoice.create(rb,"Marker");
 }
 

That's all there is to it, you would have created the menu choices with the values "Tiny", "Small", "Medium", "Big" and "CAD" presented to the user. The default menu item would be "Medium". In addition you would have associated numbers with each of the choices (remember the getNumber() method?).

Parameters:

lookup - A Lookup object used to find the values for your strings. See the LookupCreate class to see how you can create these for a ResourceBundle. Also, the TagLookup class has a nice way of loading them as well.

tag - Name of your fly out menu in the resource bundle (it was "Marker" in the above example).

Returns:

A new MenuChoice if both "tag.choice" and "tag.label" are defined and valid in the resource bundle. If "tag.default" is found in the resource bundle, it will be the initially selected item. If valid values are not found in the resource bundle, then null is returned (this allows one to remove menus simply by commenting out lines in the resource bundle - as long as you handle the null which might be returned).

Since:

1.0

See Also:

addItemListener(java.awt.event.ItemListener), getText(), getNumber()

getSelectedObjects

public Object[] getSelectedObjects()

Get the selected item. This method was required since this object implements the ItemSelectable interface. You will find it easier to get the selected item using the getText() and getNumber() methods instead. However, in the future, if this object is extended to support multiple selections, this method may have more importance.

Specified by:

getSelectedObjects in interface ItemSelectable

Returns:

Array of currently selected objects. Never returns null, but may return a zero length array (if no items are selected).

Since:

1.0

See Also:

getText(), getNumber()

addItemListener

public void addItemListener(ItemListener l)

Monitor the object for changes in selection. Whenever the setText(java.lang.String) method detects that a new valid selection has been made (one that is different from the current selection), it notifies all the registered listeners of the event. Use this method to register an object as a interested listener.

Specified by:

addItemListener in interface ItemSelectable

Parameters:

listener - The listener that wants to know when the user changes the current selection.

Since:

1.0

See Also:

setText(java.lang.String), getText(), getNumber()

removeItemListener

public void removeItemListener(ItemListener l)

Stop listening for changes in state.

Specified by:

removeItemListener in interface ItemSelectable

Parameters:

listener - Listener which no longer cares when the current selection is changed.

Since:

1.0

See Also:

addItemListener(java.awt.event.ItemListener)