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

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:


 

Field Summary
int SHIFT
Constant indicating that an accelerator key requires the SHIFT modifier.
 
Constructor Summary
ProgramMenuBar(Program owner)
Creates an empty ProgramMenuBar.
 
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