acm.program

Class ProgramMenuBar

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JMenuBar

acm.program.ProgramMenuBar

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.lang.Iterable<javax.swing.JMenuItem>, javax.accessibility.Accessible, javax.swing.MenuElement

public class ProgramMenuBar
extends javax.swing.JMenuBar
implements java.lang.Iterable<javax.swing.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:

• Focused items correspond to actions that are relevant only to the component with the keyboard focus (such as Cut, Copy, and Paste). Clients create focused items by calling createFocusedItem. Activating a focused item passes an action event to the listener set by calling setFocusedListener, which should be called whenever a component interested in responding to menu actions gains the keyboard focus.

• Program items correspond to actions that are relevant throughout the lifetime of the program (such as Quit and Print). Clients create program items by calling createProgramItem. Activating a program item passes an action event to the menuAction method in the Program object that created the menu bar.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JMenuBar

javax.swing.JMenuBar.AccessibleJMenuBar

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

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

java.awt.Container.AccessibleAWTContainer

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

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static int	SHIFT Constant indicating that an accelerator key requires the SHIFT modifier.

Fields inherited from class javax.swing.JComponent

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

accessibleContext, 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

Constructors

Constructor and Description
ProgramMenuBar(Program owner) Creates an empty ProgramMenuBar.

Method Summary

Modifier and Type	Method and Description
protected void	addEditMenu() Installs the Edit menu.
protected void	addEditMenuItems(javax.swing.JMenu menu) Adds the standard Edit items to the specified menu.
protected void	addFileMenu() Installs the File menu.
protected void	addFileMenuItems(javax.swing.JMenu menu) Adds the standard File items to the specified menu.
protected void	addMenus() Adds menus to the menu bar.
javax.swing.JMenuItem	createFocusedItem(java.lang.String action) Creates a focused menu item with the specified action command.
javax.swing.JMenuItem	createFocusedItem(java.lang.String action, int key) Creates a focused menu item with the specified action command and accelerator key.
javax.swing.JMenuItem	createProgramItem(java.lang.String action) Creates a program menu item with the specified action command.
javax.swing.JMenuItem	createProgramItem(java.lang.String action, int key) Creates a program menu item with the specified action command and accelerator key.
javax.swing.JMenuItem	createStandardItem(java.lang.String action) Creates one of the standard menu items implemented by the ProgramMenuBar class.
boolean	fireAccelerator(java.awt.event.KeyEvent e) Triggers the accelerator associated with the keystroke implied by the key event.
void	fireActionListeners(java.awt.event.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(javax.swing.JFrame frame) Installs the menu bar in the JFrame or Program object enclosing the component comp.
boolean	isFocusedItem(javax.swing.JMenuItem item) Returns true if the item is a focused item.
java.util.Iterator<javax.swing.JMenuItem>	iterator() Returns an iterator that enumerates the individual menu items under the control of the menu bar.
void	setAccelerator(javax.swing.JMenuItem item, int key) Sets the accelerator for the item as appropriate to the operating system conventions.
void	setEnabled(java.lang.String action, boolean flag) Enables or disables any menu items that generate the specified action command.
void	setFocusedListener(java.awt.event.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, getBaseline, getBaselineResizeBehavior, 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, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, 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, 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, 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, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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

getProgram

public Program getProgram()

Returns the Program object associated with this menu.

Returns:

The program associated with this menu bar

createStandardItem

public javax.swing.JMenuItem createStandardItem(java.lang.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

createProgramItem

public javax.swing.JMenuItem createProgramItem(java.lang.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 javax.swing.JMenuItem createProgramItem(java.lang.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

createFocusedItem

public javax.swing.JMenuItem createFocusedItem(java.lang.String action)

Creates a focused menu item with the specified action command.

Parameters:

action - The action command generated by this menu item

createFocusedItem

public javax.swing.JMenuItem createFocusedItem(java.lang.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

isFocusedItem

public boolean isFocusedItem(javax.swing.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

setAccelerator

public void setAccelerator(javax.swing.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(java.lang.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

install

public void install(javax.swing.JFrame frame)

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

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

getMacMenuBarFlag

public boolean getMacMenuBarFlag()

Retrieves the setting of the Mac menu bar flag.

Returns:

true if Mac menu style is supported; false otherwise

fireActionListeners

public void fireActionListeners(java.awt.event.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.

fireAccelerator

public boolean fireAccelerator(java.awt.event.KeyEvent e)

Triggers the accelerator associated with the keystroke implied by the key event. This method returns true if such an accelerator exists.

setFocusedListener

public void setFocusedListener(java.awt.event.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

iterator

public java.util.Iterator<javax.swing.JMenuItem> iterator()

Returns an iterator that enumerates the individual menu items under the control of the menu bar.

Specified by:

iterator in interface java.lang.Iterable<javax.swing.JMenuItem>

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.

addFileMenu

protected void addFileMenu()

Installs the File menu.

addEditMenu

protected void addEditMenu()

Installs the Edit menu.

addFileMenuItems

protected void addFileMenuItems(javax.swing.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

addEditMenuItems

protected void addEditMenuItems(javax.swing.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