acm.program
Class ProgramMenuBar

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JMenuBar
                  extended by acm.program.ProgramMenuBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Iterable<JMenuItem>, Accessible, MenuElement

public class ProgramMenuBar
extends JMenuBar
implements Iterable<JMenuItem>

This class standardizes the menu bars used in the ACM program package. The fundamental principles behind the design of this package are:

  1. The most common menu operations (including, for example, the standard editing operations cut, copy, and paste) should always be available and require no action on the part of the programmer.

  2. It should be easy to extend the menu bar without interfering with the standard operations.

  3. Menu bars should work in a familiar way on each of the major platforms. In particular, Macintosh users expect there to be a single menu bar at the top of the screen rather than a menu bar in each window.

These goals turn out to be difficult to achieve simultaneously. In particular, supporting both Macintosh-style and Windows-style menu bars requires creating a parallel MenuBar structure behind the underlying JMenuBar, which accounts for much of the complexity in this implementation.

Using the ProgramMenuBar class The ProgramMenuBar class supports two distinct disciplines for listening for menu actions:

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JMenuBar
JMenuBar.AccessibleJMenuBar
 
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static int SHIFT
          Constant indicating that an accelerator key requires the SHIFT modifier.
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
ProgramMenuBar(Program owner)
          Creates an empty ProgramMenuBar.
 
Method Summary
protected  void addEditMenu()
          Installs the Edit menu.
protected  void addEditMenuItems(JMenu menu)
          Adds the standard Edit items to the specified menu.
protected  void addFileMenu()
          Installs the File menu.
protected  void addFileMenuItems(JMenu menu)
          Adds the standard File items to the specified menu.
protected  void addMenus()
          Adds menus to the menu bar.
 JMenuItem createFocusedItem(String action)
          Creates a focused menu item with the specified action command.
 JMenuItem createFocusedItem(String action, int key)
          Creates a focused menu item with the specified action command and accelerator key.
 JMenuItem createProgramItem(String action)
          Creates a program menu item with the specified action command.
 JMenuItem createProgramItem(String action, int key)
          Creates a program menu item with the specified action command and accelerator key.
 JMenuItem createStandardItem(String action)
          Creates one of the standard menu items implemented by the ProgramMenuBar class.
 boolean fireAccelerator(KeyEvent e)
          Triggers the accelerator associated with the keystroke implied by the key event.
 void fireActionListeners(ActionEvent e)
          Fires the action listeners responsible for handling the specified event.
 boolean getMacMenuBarFlag()
          Retrieves the setting of the Mac menu bar flag.
 Program getProgram()
          Returns the Program object associated with this menu.
 void install(Component comp)
          Installs the menu bar in the JFrame or Program object enclosing the component comp.
 boolean isFocusedItem(JMenuItem item)
          Returns true if the item is a focused item.
 Iterator<JMenuItem> iterator()
          Returns an iterator that enumerates the individual menu items under the control of the menu bar.
 void setAccelerator(JMenuItem item, int key)
          Sets the accelerator for the item as appropriate to the operating system conventions.
 void setEnabled(String action, boolean flag)
          Enables or disables any menu items that generate the specified action command.
 void setFocusedListener(ActionListener listener)
          Registers a listener that responds while the caller holds the keyboard focus.
 void setMacMenuBarFlag(boolean flag)
          Sets a flag indicating whether applications running on the Macintosh should use standard Mac menus.
 
Methods inherited from class javax.swing.JMenuBar
add, addNotify, getAccessibleContext, getComponent, getComponentAtIndex, getComponentIndex, getHelpMenu, getMargin, getMenu, getMenuCount, getSelectionModel, getSubElements, getUI, getUIClassID, isBorderPainted, isSelected, menuSelectionChanged, paintBorder, paramString, processKeyBinding, processKeyEvent, processMouseEvent, removeNotify, setBorderPainted, setHelpMenu, setMargin, setSelected, setSelectionModel, setUI, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SHIFT

public static final int SHIFT
Constant indicating that an accelerator key requires the SHIFT modifier.

See Also:
Constant Field Values
Constructor Detail

ProgramMenuBar

public ProgramMenuBar(Program owner)
Creates an empty ProgramMenuBar.

Parameters:
owner - The Program that owns this menu bar.
Method Detail

addEditMenu

protected void addEditMenu()
Installs the Edit menu.


addEditMenuItems

protected void addEditMenuItems(JMenu menu)
Adds the standard Edit items to the specified menu. Subclasses can override this method to change the list of items.

Parameters:
menu - The menu to which the Edit items are added

addFileMenu

protected void addFileMenu()
Installs the File menu.


addFileMenuItems

protected void addFileMenuItems(JMenu menu)
Adds the standard File items to the specified menu. Subclasses can override this method to change the list of items.

Parameters:
menu - The menu to which the File items are added

addMenus

protected void addMenus()
Adds menus to the menu bar. Subclasses that wish to change the composition of the menu bar beyond the default File and Edit menus should override this method with one that adds the desired menus.


createFocusedItem

public JMenuItem createFocusedItem(String action)
Creates a focused menu item with the specified action command.

Parameters:
action - The action command generated by this menu item

createFocusedItem

public JMenuItem createFocusedItem(String action,
                                   int key)
Creates a focused menu item with the specified action command and accelerator key.

Parameters:
action - The action command generated by this menu item
key - The integer value of the keystroke accelerator

createProgramItem

public JMenuItem createProgramItem(String action)
Creates a program menu item with the specified action command. The initial item has the same label as the action command, but clients can change this name by calling setName on the item.

Parameters:
action - The action command generated by this menu item

createProgramItem

public JMenuItem createProgramItem(String action,
                                   int key)
Creates a program menu item with the specified action command and accelerator key.

Parameters:
action - The action command generated by this menu item
key - The integer value of the keystroke accelerator

createStandardItem

public JMenuItem createStandardItem(String action)
Creates one of the standard menu items implemented by the ProgramMenuBar class. The menu item is identified by its action command.

Parameters:
action - The action command identifying the menu item to be created

fireAccelerator

public boolean fireAccelerator(KeyEvent e)
Triggers the accelerator associated with the keystroke implied by the key event. This method returns true if such an accelerator exists.


fireActionListeners

public void fireActionListeners(ActionEvent e)
Fires the action listeners responsible for handling the specified event. The process of choosing the appropriate handlers takes into account whether the action command is designated as program or focused.


getMacMenuBarFlag

public boolean getMacMenuBarFlag()
Retrieves the setting of the Mac menu bar flag.

Returns:
true if Mac menu style is supported; false otherwise

getProgram

public Program getProgram()
Returns the Program object associated with this menu.

Returns:
The program associated with this menu bar

install

public void install(Component comp)
Installs the menu bar in the JFrame or Program object enclosing the component comp.

Parameters:
comp - A descendant of the frame in which the menu is to be installed

isFocusedItem

public boolean isFocusedItem(JMenuItem item)
Returns true if the item is a focused item.

Parameters:
item - A menu item installed in the menu bar
Returns:
true if the item is a program item

iterator

public Iterator<JMenuItem> iterator()
Returns an iterator that enumerates the individual menu items under the control of the menu bar.

Specified by:
iterator in interface Iterable<JMenuItem>

setAccelerator

public void setAccelerator(JMenuItem item,
                           int key)
Sets the accelerator for the item as appropriate to the operating system conventions.

Parameters:
item - The menu item triggered by this accelerator
key - The integer value of the keystroke accelerator

setEnabled

public void setEnabled(String action,
                       boolean flag)
Enables or disables any menu items that generate the specified action command.

Parameters:
action - The action command triggered by the menu item
flag - true to enable the item, false to disable it

setFocusedListener

public void setFocusedListener(ActionListener listener)
Registers a listener that responds while the caller holds the keyboard focus. The caller should register its listener when it acquires the keyboard focus and set it to null when it loses it.

Parameters:
listener - An ActionListener that responds to focused items

setMacMenuBarFlag

public void setMacMenuBarFlag(boolean flag)
Sets a flag indicating whether applications running on the Macintosh should use standard Mac menus. The default is true. Setting this value to false means that Mac programs use the same in-window JMenuBar approach used on other platforms.

Parameters:
flag - true to use Mac menu style; false otherwise