keybinding.html

来自「jsf、swing的官方指南」· HTML 代码 · 共 806 行 · 第 1/2 页

Each <code>JComponent</code> has
one action map and three input maps.
The input maps correspond to the following focus situations:

<dl>
<dt> <code>JComponent.WHEN_FOCUSED</code>
<dd> The component has the keyboard focus.
The <code>WHEN_FOCUSED</code> input map
is typically used when the component has no children.
For example, buttons bind the Space key using
the <code>WHEN_FOCUSED</code> map.
<p>
<dt> <code>JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code>
<dd> The component contains (or is) the component that has the focus.
This input map
is commonly used for a composite component &#151;
a component whose implementation depends on child components.
For example, <code>JTable</code>s
make all their bindings using
<code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code>
so that if the user is editing,
the up-arrow key (for example) still changes the selected cell.
<p>
<dt> <code>JComponent.WHEN_IN_FOCUSED_WINDOW</code>
<dd> The component's window either has the focus or contains the component
that has the focus.
This input map
is commonly used for mnemonics or accelerators,
which need to be active regardless of where focus is in the window.
</dl>

When the user types a key,
the <code>JComponent</code> key event processing code
searches through one or more input maps
to find a valid binding for the key.
When it finds a binding,
it looks up the corresponding action
in the action map.
If the action is enabled, the binding is valid and the action is executed.
If it's disabled, the search for a valid binding continues.

<p>
If more than one binding exists for the key,
only the first valid one found is used.
Input maps are checked in this order:

<ol>
<li> The focused component's <code>WHEN_FOCUSED</code> input map.
<li> The focused component's <code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code> input map.
<li> The <code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code> input maps of
     the focused component's parent,
     and then its parent's parent, and so on,
     continuing up the containment hierarchy.
     Note: Input maps for disabled components are skipped.
<li> The <code>WHEN_IN_FOCUSED_WINDOW</code> input maps of all the
     enabled components
     in the focused window are searched.
     Because the order of searching the components is unpredictable,
     <b>avoid duplicate <code>WHEN_IN_FOCUSED_WINDOW</code> bindings!</b>
</ol>

<p>
Let's consider what happens in two typical key binding cases:
a button reacting to the Space key,
and a frame with a default button
reacting to the Enter key.

<p>
In the first case, assume the user presses the Space key
while a <code>JButton</code> has the keyboard focus.
First, the button's key listeners are notified of the event.
Assuming none of the key listeners <em>consumes</em> the event
(by invoking the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/InputEvent.html#consume()"><code>consume</code></a> method on the <code>KeyEvent</code>)
the button's <code>WHEN_FOCUSED</code> input map is consulted.
A binding is found because <code>JButton</code> uses that input map
to bind Space to an action name.
The action name is looked up in the button's action map,
and the <code>actionPerformed</code> method of the action is invoked.
The <code>KeyEvent</code> is automatically consumed,
and processing stops.

<p>
In the second case,
assume the Enter key is pressed
while the focus is anywhere inside a frame that has a default button
(set using the <code>JRootPane</code>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JRootPane.html#setDefaultButton(javax.swing.JButton)"><code>setDefaultButton</code></a> method).
Whatever the focused component is,
its key listeners are first notified.
Assuming none of them consumes the key event
the focused component's <code>WHEN_FOCUSED</code> input map is consulted.
If it has no binding for the key,
the focused component's <code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code>
input map is consulted
and then (if no binding is found)
the <code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code> input maps
of each of the component's ancestors in the containment hierarchy.
Eventually, the root pane's
<code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code> input map
is searched.
Since that input map has a valid binding for Enter,
the action is executed,
causing the default button to be clicked.


</blockquote>
<h3>
<a name="howto">
How to Make and Remove Key Bindings
</a>
</h3>
<blockquote>

<p>
Here is an example of specifying that a component
should react to the F2 key:

<blockquote>
<pre>
component.getInputMap().put(KeyStroke.getKeyStroke("F2"),
                            "doSomething");
component.getActionMap().put("doSomething",
                             anAction);
<em>//where anAction is a javax.swing.Action</em>
</pre>
</blockquote>

<p>
As the preceding code shows,
to get a component's action map
you use the <code>getActionMap</code> method
(inherited from <code>JComponent</code>).
To get an input map,
you can use the <code>getInputMap(int)</code> method,
where the integer is one of the <code>JComponent.WHEN_*FOCUSED*</code>
constants shown in the preceding list.
Or, in the usual case where the constant is
<code>JComponent.WHEN_FOCUSED</code>,
you can just use <code>getInputMap</code> with no arguments.

<p>
To add an entry to one of the maps,
use the <code>put</code> method.
You specify a key
using a <code>KeyStroke</code> object,
which you can get using the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/KeyStroke.html#getKeyStroke(java.lang.String)"><code>KeyStroke.getKeyStroke(String)</code></a> method.
You can find examples of creating <code>Action</code>s
(to put in an action map) in
<a class="TutorialLink" target="_top" href="../misc/action.html">How to Use Actions</a>.

<p>
Here's a slightly more complex example
that specifies that a component
should react to the Space key
as if the user clicked the mouse.

<blockquote>
<pre>
component.getInputMap().put(KeyStroke.getKeyStroke("SPACE"),
                            "pressed");
component.getInputMap().put(KeyStroke.getKeyStroke("released SPACE"),
                            "released");
component.getActionMap().put("pressed",
                             pressedAction);
component.getActionMap().put("released",
                             releasedAction);
<em>//where pressedAction and releasedAction are javax.swing.Action objects</em>
</pre>
</blockquote>

<p>
To make a component ignore a key that it normally responds to,
you can use the special action name "none".
For example, the following code makes a component ignore the F2 key.
</p>

<blockquote>
<pre>
component.getInputMap().put(KeyStroke.getKeyStroke("F2"),
                            "none");
</pre>
</blockquote>

<blockquote><hr><strong>Note:</strong>&nbsp;The preceding code doesn't prevent
the relevant
<code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code> and
<code>WHEN_IN_FOCUSED_WINDOW</code> input maps
from being searched
for an F2 key binding.
To prevent this search,
you must use a valid action instead of "none".
For example:

<blockquote><pre>
Action doNothing = new AbstractAction() {
    public void actionPerformed(ActionEvent e) {
        //do nothing
    }
};
component.getInputMap().put(KeyStroke.getKeyStroke("F2"),
                            "doNothing");
component.getActionMap().put("doNothing",
                             doNothing);
</pre></blockquote>

<hr></blockquote>


</blockquote>
<h3>
<a name="api">The Key Binding API</a>
</h3>
<blockquote>
The following tables list the commonly used API
for key bindings.
Also see the API table
<a class="TutorialLink" target="_top" href="action.html#actionapi">Creating and Using an Action</a>, in the section
<a class="TutorialLink" target="_top" href="action.html">How to Use Actions</a>.


<ul>
<li><a href="#inputmap">Creating and Using InputMaps</a>
<li><a href="#actionmap">Creating and Using ActionMaps</a>
</ul>

<p>
<table border=1>
<caption><a name="inputmap">Getting and Using InputMaps</a></caption>
<tr>
<th align=left>Method</th>
<th align=left>Purpose</th>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JComponent.html#getInputMap()">InputMap getInputMap()</a>    <br>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JComponent.html#getInputMap(int)">InputMap getInputMap(int)</a>    <br>
 <em>(in <code>JComponent</code>)</em>
</td>
<td>Get one of the input maps for the component.
    The arguments can be one of these <code>JComponent</code> constants:
    <code>WHEN_FOCUSED</code>,
    <code>WHEN_IN_FOCUSED_WINDOW</code>, or
    <code>WHEN_ANCESTOR_OF_FOCUSED_COMPONENT</code>.
    The no-argument method gets the <code>WHEN_FOCUSED</code> input map.
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/InputMap.html#put(javax.swing.KeyStroke, java.lang.Object)">void put(KeyStroke, Object)</a> <br>
 <em>(in <code>InputMap</code>)</em>
</td>
<td>Set the action name associated with the specified key stroke.
    If the second argument is <code>null</code>,
    this method removes the binding for the key stroke.
    To make the key stroke be ignored,
    use <code>"none"</code> as the second argument.
    </td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/KeyStroke.html#getKeyStroke(java.lang.String)">static KeyStroke getKeyStroke(String)</a> <br>
 <em>(in <code>KeyStroke</code>)</em>
</td>
<td>Get the object specifying a particular user keyboard activity.
Typical arguments are "alt shift X", "INSERT", and "typed a".
See the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/KeyStroke.html"><code>KeyStroke</code> API documentation</a> for full details
and for other forms of the <code>getKeyStroke</code> method.
    </td>
</tr>

</table>

<p>
<table border=1>
<caption><a name="actionmap">Getting and Using ActionMaps</a></caption>
<tr>
<th align=left>Method</th>
<th align=left>Purpose</th>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JComponent.html#getActionMap()">ActionMap getActionMap()</a>    <br>
 <em>(in <code>JComponent</code>)</em>
</td>
<td>Get the object that maps names into actions for the component.
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/ActionMap.html#put(java.lang.Object, javax.swing.Action)">void put(Object, Action)</a> <br>
 <em>(in <code>ActionMap</code>)</em>
</td>
<td>Set the action associated with the specified name.
    If the second argument is <code>null</code>,
    this method removes the binding for the name.
    </td>
</tr>
</table>

</blockquote>

<h3>
<a name="eg">Examples that Use Key Bindings</a>
</h3>
<blockquote>
The following table lists examples that
use key bindings:
<p>
<table>
<tr valign = top>
<th align=left> Example</th>
<th align=left> Where Described</th>
<th align=left> Notes</th>
</tr>

<tr valign = top>
<td>
<a href=../components/examples/index.html#TableFTFEditDemo>
TableFTFEditDemo</a>
<td>
<a class="TutorialLink" target="_top" href="../components/table.html">How to Use Tables</a></td>
<td> The 
<a class="TutorialLink" target="_top" href="../components/examples/IntegerEditor.java">IntegerEditor</a> class registers a key binding on a formatted text field
to validate the input when the user presses the Enter key.
</td>
</tr>

<tr valign = top>
<td>
<a href=../components/examples/index.html#SliderDemo3>
SliderDemo3</a>
<td>
<a class="TutorialLink" target="_top" href="../components/slider.html">How to Use Sliders</a></td>
<td>A key binding is registered on a text field
to validate the input when the user presses the Enter key.
</td>
</tr>

<tr valign = top>
<td>
<a href=../components/examples/index.html#TextComponentDemo>
TextComponentDemo</a>
<td>
<a class="TutorialLink" target="_top" href="../components/generaltext.html">Text Component Features</a></td>
<td>Key bindings are registered on a text pane
to navigate through the text when the user presses
the Control-B, Control-F, Control-P, and Control-N
keys.
</td>
</tr>

<tr valign = top>
<td>
<a href=../misc/examples/index.html#DragPictureDemo>
DragPictureDemo</a>
<td>
<a class="TutorialLink" target="_top" href="../dnd/intro.html">Introduction to Drag and Drop and Data Transfer</a></td>
<td> The 
<a class="TutorialLink" target="_top" href="../dnd/examples/DTPicture.java">DTPicture</a> class registers key bindings on a custom component
to cut, copy, and paste when the user
presses the Control-X, Control-C, and Control-V keys.
</td>
</tr>

</table>
        </blockquote>
        <div class=NavBit>
            <a target=_top href=focus.html>&laquo; Previous</a>
            &bull;
            <a target=_top href=../TOC.html>Trail</a>
            &bull;
            <a target=_top href=problems.html>Next &raquo;</a>
        </div>
    </div>
    <div id=Footer>
<div id=TagNotes>
    Problems with the examples? Try <a target="_blank"
        href=../../information/run-examples.html>Compiling and Running
        the Examples: FAQs</a>.
    <br>
    Complaints? Compliments? Suggestions? <a target="_blank"
        href="http://developer.sun.com/contact/tutorial_feedback.jsp">Give
    us your feedback</a>.
<br><br>
    <a target="_blank" href="../../information/copyright.html">Copyright</a>
    1995-2006 Sun Microsystems, Inc.  All rights reserved.
    <span id=Download>
</span></div> 

    </div>
    <div class=PrintHeaders>
        <b>Previous page:</b> How to Use the Focus Subsystem
        <br><b>Next page:</b> Solving Common Problems Using Other Swing Features
    </div>
    </body>
</html>