acm.program
Class ProgramMenuBar

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JMenuBar
                  acm.program.ProgramMenuBar

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:

• 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.

Field Summary

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

Constructor Summary

ProgramMenuBar(Program owner)

Method Summary

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.

Field Detail

public static final int SHIFT

Constant indicating that an accelerator key requires the SHIFT modifier.

See Also:

Constant Field Values

Constructor Detail

public ProgramMenuBar(Program owner)

Creates an empty ProgramMenuBar.

Usage:

ProgramMenuBar mbar = new ProgramMenuBar(owner);

Parameter:

owner

The Program that owns this menu bar.

Method Detail

public JMenuItem createFocusedItem(String action)

Creates a focused menu item with the specified action command.

Usage:

JMenuItem item = createFocusedItem(action);

Parameter:

action

The action command generated by this menu item

public JMenuItem createFocusedItem(String action, int key)

Creates a focused menu item with the specified action command and accelerator key.

Usage:

JMenuItem item = createFocusedItem(action, key);

Parameters:

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

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.

Usage:

JMenuItem item = createProgramItem(action);

Parameter:

action

The action command generated by this menu item

public JMenuItem createProgramItem(String action, int key)

Creates a program menu item with the specified action command and accelerator key.

Usage:

JMenuItem item = createProgramItem(action, key);

Parameters:

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

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.

Usage:

JMenuItem item = mbar.createStandardItem(action);

Parameter:

action

The action command identifying the menu item to be created

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.

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.

public boolean getMacMenuBarFlag()

Retrieves the setting of the Mac menu bar flag.

Usage:	boolean flag = getMacMenuBarFlag();
Returns:	true if Mac menu style is supported; false otherwise

public Program getProgram()

Returns the Program object associated with this menu.

Usage:	Program program = mbar.getProgram();
Returns:	The program associated with this menu bar

public void install(Component comp)

Installs the menu bar in the JFrame or Program object enclosing the component comp.

Usage:

mbar.install(comp);

Parameter:

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

public boolean isFocusedItem(JMenuItem item)

Returns true if the item is a focused item.

Usage:

if (mbar.isFocusedItem(item)) . . .

Parameter:

item	A menu item installed in the menu bar

Returns:

true if the item is a program item

public Iterator<JMenuItem> iterator()

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

Usage:

Iterator iterator = mbar.iterator(); return An iterator that enumerates the menu items

Specified by:

iterator in interface Iterable<JMenuItem>

public void setAccelerator(JMenuItem item, int key)

Sets the accelerator for the item as appropriate to the operating system conventions.

Usage:

mbar.setAccelerator(item, key);

Parameters:

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

public void setEnabled(String action, boolean flag)

Enables or disables any menu items that generate the specified action command.

Usage:

mbar.setEnabled(action, flag);

Parameters:

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

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.

Usage:

setFocusedListener(listener);

Parameter:

listener

An ActionListener that responds to focused items

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.

Usage:

setMacMenuBarFlag(flag);

Parameter:

flag	true to use Mac menu style; false otherwise