menu.html

jsf、swing的官方指南

usually along the top of a window.
A popup menu is a menu that is invisible
until the user makes a platform-specific mouse action,
such as pressing the right mouse button,
over a popup-enabled component.
The popup menu then appears under the cursor.

<p>

The following figure shows many of Swing's menu-related components:
a menu bar,
menus, menu items,
radio button menu items, check box menu items,
and separators.
As you can see, a menu item can have either an image or text, or both.
You can also specify other properties, such as font and color.

<p><center><IMG SRC="../../figures/uiswing/components/MenuLookDemo.png" WIDTH="474" HEIGHT="287" ALIGN="BOTTOM" ALT="MenuLookDemo"></center></p>
<p align=center>
<font color=gray>
[PENDING: This figure will be updated.
We may also add callouts for each component type.]
</font>
</p>

<p>
The rest of this section teaches you about the menu components
and tells you how to use
various menu features:

<ul>
<li> <a href="#hierarchy">The menu component hierarchy</a>
<li> <a href="#create">Creating menus</a>
<li> <a href="#event">Handling events from menu items</a>
<li> <a href="#mnemonic">Enabling keyboard operation</a>
<li> <a href="#popup">Bringing up a popup menu</a>
<li> <a href="#custom">Customizing menu layout</a>
<li> <a href="#api">The Menu API</a>
<li> <a href="#eg">Examples that use menus</a>
</ul>


</blockquote>
<h3>
<a name="hierarchy">The Menu Component Hierarchy</a>
</h3>
<blockquote>

Here is a picture of the inheritance hierarchy for the menu-related classes:

<p><center><IMG SRC="../../figures/uiswing/components/object.gif" WIDTH="444" HEIGHT="239" ALIGN="BOTTOM" ALT="The inheritance hierarchy for menu classes"></center></p>
As the figure shows, menu items (including menus) are simply
<a href="button.html">buttons</a>.
You might be wondering how a menu,
if it's only a button, shows its menu items.
The answer is that when a menu is activated,
it automatically brings up a popup menu
that displays the menu items.


</blockquote>
<h3>
<a name="create">Creating Menus</a>
</h3>
<blockquote>

The following code
creates the menus shown near the beginning of this menu section.
The bold lines of code create and connect the menu objects;
the other code sets up or customizes the menu objects.
You can find the entire program in

<a class="SourceLink" target="_blank" href="examples/MenuLookDemo.java"><code>MenuLookDemo.java</code></a>.
Other required files are listed in the
<a href="examples/index.html#MenuLookDemo">example index</a>.
You can use Java<sup><font size=-2>TM</font></sup> Web Start to
<a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/MenuLookDemo.jnlp"><b><i>run MenuLookDemo</i></b></a> (it requires release 6).

<blockquote><hr><strong>Note:</strong>&nbsp;
Because this code has no event handling,
the menus do nothing useful
except look like they should.
If you run the example,
you'll notice that despite the lack of custom event handling,
menus and submenus appear when they should,
and the check boxes and radio buttons
respond appropriately when the user chooses them.
<hr></blockquote>


<blockquote><pre>
<em>//Where the GUI is created:</em>
JMenuBar menuBar;
JMenu menu, submenu;
JMenuItem menuItem;
JRadioButtonMenuItem rbMenuItem;
JCheckBoxMenuItem cbMenuItem;

//Create the menu bar.
<b>menuBar = new JMenuBar();</b>

//Build the first menu.
<b>menu = new JMenu("A Menu");</b>
menu.setMnemonic(KeyEvent.VK_A);
menu.getAccessibleContext().setAccessibleDescription(
        "The only menu in this program that has menu items");
<b>menuBar.add(menu);</b>

//a group of JMenuItems
<b>menuItem = new JMenuItem("A text-only menu item"</b>,
                         KeyEvent.VK_T<b>);</b>
menuItem.setAccelerator(KeyStroke.getKeyStroke(
        KeyEvent.VK_1, ActionEvent.ALT_MASK));
menuItem.getAccessibleContext().setAccessibleDescription(
        "This doesn't really do anything");
<b>menu.add(menuItem);</b>

<b>menuItem = new JMenuItem("Both text and icon",
                         new ImageIcon("images/middle.gif"));</b>
menuItem.setMnemonic(KeyEvent.VK_B);
<b>menu.add(menuItem);</b>

<b>menuItem = new JMenuItem(new ImageIcon("images/middle.gif"));</b>
menuItem.setMnemonic(KeyEvent.VK_D);
<b>menu.add(menuItem);</b>

//a group of radio button menu items
<b>menu.addSeparator();</b>
ButtonGroup group = new ButtonGroup();
<b>rbMenuItem = new JRadioButtonMenuItem("A radio button menu item");</b>
rbMenuItem.setSelected(true);
rbMenuItem.setMnemonic(KeyEvent.VK_R);
group.add(rbMenuItem);
<b>menu.add(rbMenuItem);</b>

<b>rbMenuItem = new JRadioButtonMenuItem("Another one");</b>
rbMenuItem.setMnemonic(KeyEvent.VK_O);
group.add(rbMenuItem);
<b>menu.add(rbMenuItem);</b>

//a group of check box menu items
<b>menu.addSeparator();</b>
<b>cbMenuItem = new JCheckBoxMenuItem("A check box menu item");</b>
cbMenuItem.setMnemonic(KeyEvent.VK_C);
<b>menu.add(cbMenuItem);</b>

<b>cbMenuItem = new JCheckBoxMenuItem("Another one");</b>
cbMenuItem.setMnemonic(KeyEvent.VK_H);
<b>menu.add(cbMenuItem);</b>

//a submenu
<b>menu.addSeparator();</b>
<b>submenu = new JMenu("A submenu");</b>
submenu.setMnemonic(KeyEvent.VK_S);

<b>menuItem = new JMenuItem("An item in the submenu");</b>
menuItem.setAccelerator(KeyStroke.getKeyStroke(
        KeyEvent.VK_2, ActionEvent.ALT_MASK));
<b>submenu.add(menuItem);</b>

<b>menuItem = new JMenuItem("Another item");</b>
<b>submenu.add(menuItem);</b>
<b>menu.add(submenu);</b>

//Build second menu in the menu bar.
<b>menu = new JMenu("Another Menu");</b>
menu.setMnemonic(KeyEvent.VK_N);
menu.getAccessibleContext().setAccessibleDescription(
        "This menu does nothing");
<b>menuBar.add(menu);</b>

...
<b>frame.setJMenuBar(<em>theJMenuBar</em>);</b>
</pre></blockquote>
<p>

As the code shows,
to set the menu bar for a <code>JFrame</code>,
you use the <code>setJMenuBar</code> method.
To add a <code>JMenu</code> to a <code>JMenuBar</code>,
you use the <code>add(JMenu)</code> method.
To add menu items and submenus to a <code>JMenu</code>,
you use the <code>add(JMenuItem)</code> method.

<blockquote><hr><strong>Note:</strong>&nbsp;Menu items, like other components,
can be in at most one container.
If you try to add a menu item to a second menu,
the menu item will be removed from the first menu
before being added to the second.
For a way of implementing multiple components that do the same thing,
see
<a class="TutorialLink" target="_top" href="../misc/action.html">How to Use Actions</a>.
<hr></blockquote>

<p>
Other methods
in the preceding code include <code>setAccelerator</code> and
<code>setMnemonic</code>,
which are discussed a little later in
<a href="#mnemonic">Enabling Keyboard Operation</a>.
The <code>setAccessibleDescription</code> method
is discussed in
<a class="TutorialLink" target="_top" href="../misc/access.html">How to Support Assistive Technologies</a>.


</blockquote>
<h3>
<a name="event">Handling Events from Menu Items</a>
</h3>
<blockquote>

To detect when the user chooses a <code>JMenuItem</code>,
you can listen for action events
(just as you would for a
<a href="button.html"><code>JButton</code></a>).
To detect when the user chooses a <code>JRadioButtonMenuItem</code>,
you can listen for either action events or
item events,
as described in
<a href="button.html#radiobutton">How to Use Radio Buttons</a>.
For <code>JCheckBoxMenuItem</code>s,
you generally listen for item events,
as described in
<a href="button.html#checkbox">How to Use Check Boxes</a>.

<p>

The following picture shows a program
that adds event detection to the preceding example.
The program's code is in

<a class="SourceLink" target="_blank" href="examples/MenuDemo.java"><code>MenuDemo.java</code></a>.
Other required files are listed in the
<a href="examples/index.html#MenuDemo">example index</a>.
You can use Java Web Start to
<a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/MenuDemo.jnlp"><b><i>run MenuDemo</i></b></a> (it requires release 6).

<p><center><IMG SRC="../../figures/uiswing/components/MenuDemo.png" WIDTH="450" HEIGHT="260" ALIGN="BOTTOM" ALT="The text area shows the action and item events our listeners detected."></center></p><p align=center>

Here is the code that implements
the event handling:

<blockquote><pre>
public class MenuDemo ... implements ActionListener,
                                     ItemListener {
    ...
    public MenuDemo() {
        <em>//...for each JMenuItem instance:</em>
        menuItem.addActionListener(this);
        ...
        <em>//for each JRadioButtonMenuItem: </em>
        rbMenuItem.addActionListener(this);
        ...
        <em>//for each JCheckBoxMenuItem: </em>
        cbMenuItem.addItemListener(this);
        ...
    }

    public void actionPerformed(ActionEvent e) {
        <em>//...Get information from the action event...
        //...Display it in the text area...</em>
    }

    public void itemStateChanged(ItemEvent e) {
        <em>//...Get information from the item event...
        //...Display it in the text area...</em>
    }
</pre></blockquote>

For examples of handling action and item events,
see the <a href="button.html">button</a>,
<a href="button.html#radiobutton">radio button</a>, and
<a href="button.html#checkbox">check box</a> sections,
as well as the <a href="#eg">list of examples</a>
at the end of this section.

</blockquote>
<h3>
<a name="mnemonic">Enabling Keyboard Operation</a>
</h3>
<blockquote>

Menus support two kinds of keyboard alternatives:
mnemonics and accelerators.
<em>Mnemonics</em> offer a way to use the keyboard to navigate
the menu hierarchy,
increasing the accessibility of programs.
<em>Accelerators</em>, on the other hand,
offer keyboard shortcuts to <em>bypass</em> navigating
the menu hierarchy.
Mnemonics are for all users;
accelerators are for power users.

<p>

A mnemonic is a key that
makes an already visible menu item be chosen.
For example, in <code>MenuDemo</code>
the first menu has the mnemonic A,
and its second menu item has the mnemonic B.
This means that, when you run <code>MenuDemo</code>
with the Java look and feel,
pressing the Alt and A keys makes
the first menu appear.
While the first menu is visible,
pressing the B key (with or without Alt)
makes the second menu item be chosen.
A menu item generally displays its mnemonic
by underlining the first occurrence of the mnemonic character
in the menu item's text,
as the following snapshot shows.

<p><center><IMG SRC="../../figures/uiswing/components/Menu-mnemonic.png" WIDTH="217" HEIGHT="29" ALIGN="BOTTOM" ALT="B is the mnemonic character for this menu item"></center></p>

<p>

An accelerator is a key combination
that causes a menu item to be chosen,
whether or not it's visible.
For example, pressing the Alt and 2 keys in <code>MenuDemo</code>
makes the first item in the first menu's submenu be chosen,
without bringing up any menus.
Only leaf menu items &#151; menus that don't bring up other menus &#151;
can have accelerators.
The following snapshot shows how the Java look and feel
displays a menu item that has an accelerator.

<p><center><IMG SRC="../../figures/uiswing/components/Menu-accel.png" WIDTH="179" HEIGHT="24" ALIGN="BOTTOM" ALT="Alt+2 advertises this menu item's accelerator"></center></p>
<p align=center>

You can specify a mnemonic either when constructing the menu item
or with the <code>setMnemonic</code> method.
To specify an accelerator,
use the <code>setAccelerator</code> method.
Here are examples of setting mnemonics and accelerators:

<blockquote><pre>
//Setting the mnemonic when constructing a menu item:
menuItem = new JMenuItem("A text-only menu item",
                         KeyEvent.VK_T);

//Setting the mnemonic after creation time:
menuItem.setMnemonic(KeyEvent.VK_T);

//Setting the accelerator:
menuItem.setAccelerator(KeyStroke.getKeyStroke(
        KeyEvent.VK_T, ActionEvent.ALT_MASK));
</pre></blockquote>

As you can see,
you set a mnemonic
by specifying the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/KeyEvent.html"><code>KeyEvent</code></a> constant corresponding to the key the user should press.
To specify an accelerator you must use a
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/KeyStroke.html"><code>KeyStroke</code></a> object,
which combines a key
(specified by a <code>KeyEvent</code> constant)
and a modifier-key mask
(specified by an
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/ActionEvent.html"><code>ActionEvent</code></a> constant).

<blockquote><hr><strong>Note:</strong>&nbsp;Because popup menus, unlike regular menus,
aren't always contained by a component,
accelerators in popup menu items
don't work unless the popup menu is visible.
<hr></blockquote>


</blockquote>
<h3>