mousewheellistener.html

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

<div class="linkBHEAD"><a href="windowlistener.html">How to Write Window Listeners</a></div>
<div class="linkAHEAD"><a href="api.html">Listener API Table</a></div>
<div class="linkAHEAD"><a href="problems.html">Solving Common Event-Handling Problems</a></div>
</div>
    </div>
    <div id=MainFlow class=MainFlow_indented>
            <span id=BreadCrumbs>
                <a href=../../index.html target=_top>Home Page</a>
                &gt;
                <a href=../index.html target=_top>Creating a GUI with JFC/Swing</a>
                &gt;
                <a href=index.html target=_top>Writing Event Listeners</a>
            </span>
            <div class=NavBit>
                <a target=_top href=mousemotionlistener.html>&laquo;&nbsp;Previous</a>&nbsp;&bull;&nbsp;<a target=_top href=../TOC.html>Trail</a>&nbsp;&bull;&nbsp;<a target=_top href=propertychangelistener.html>Next&nbsp;&raquo;</a>
            </div>
            <div id=PageTitle>How to Write a Mouse-Wheel Listener</div>
            <blockquote>

Mouse-wheel events tell you when the wheel on the mouse rotates.
For information on listening to other mouse
events, such as clicks, see <a href=mouselistener.html>How
to Write a Mouse Listener</a>.  For information on listening
to mouse-dragged events, see
<a href=mousemotionlistener.html>How to Write a Mouse-Motion
Listener</a>.
Not all mice have wheels and, in that case,
mouse-wheel events are never generated.
There is no way to programmatically detect whether the mouse
is equipped with a mouse wheel.

<blockquote><hr><strong>Version note:</strong>&nbsp;The <code>MouseWheelListener</code> interface was introduced
in release 1.4.
<hr></blockquote>

<p>
You don't usually need to implement a mouse-wheel listener.
The mouse wheel is used primarily for scrolling, and
scroll panes automatically register mouse-wheel listeners
that react to the mouse wheel appropriately.
<p>
However, if you create a custom component to be used inside a
scroll pane you may need to customize
its scrolling behavior &#151; specifically you might
need to set the unit and block increments.
For a text area, for example, scrolling one
unit means scrolling by one line of text.
A block increment typically scrolls an entire "page",
or the size of the viewport.
For more information, see
<a class="TutorialLink" target="_top" href="../components/scrollpane.html#scrollable">Implementing a Scrolling-Savvy Client</a> in the 
<a class="TutorialLink" target="_top" href="../components/scrollpane.html">How to Use Scroll Panes</a> page.

<p>
To generate mouse-wheel events the 
cursor must be <em>over</em> the component registered to
listen for mouse-wheel events. The type of scrolling that occurs,
either <code>WHEEL_UNIT_SCROLL</code> or
<code>WHEEL_BLOCK_SCROLL</code>,
is platform dependent.  The amount that the mouse wheel scrolls
is also platform dependent. Both the type and amount of scrolling
may be settable via the mouse control panel for your platform.

<p>
The following example demonstrates mouse-wheel events.

<h4 align=center><font color=red>[PENDING: Screenshot with
    sample output forthcoming.]</font></h4>

<p>
<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/events/examples/MouseWheelEventDemo.jnlp">Run
     MouseWheelEventDemo</a> using
     <a href=http://java.sun.com/products/javawebstart>
     Java<sup><font size=-2>TM</font></sup> Web Start</a>.
     Or, to compile and run the example yourself,
     consult the
     <a href="examples/index.html#MouseWheelEventDemo">example index</a>.

<li> Move the cursor over the text area.

<li> Rotate the mouse wheel away from you. 
     You will see one or more mouse-wheel events in
     the <em>up</em> direction.

<li> Rotate the mouse wheel in the opposite direction.
     You will see mouse-wheel events in the <em>down</em>
     direction.

<li>Try changing your mouse wheel's scrolling
    behavior your system's mouse control panel to see how 
    the output changes.  You should not need to restart the demo
    to see the changes take effect.
</ol>
<hr></blockquote>

<p>
The output from MouseWheelEventDemo for a
system that uses unit increments for its mouse wheel
might look like this:

<blockquote><pre>
javax.swing.JTextArea: Mouse wheel moved UP 1 notch(es)
    Scroll type: WHEEL_UNIT_SCROLL
    Scroll amount: 3 unit increments per notch
    Units to scroll: -3 unit increments
    Vertical unit increment: 16 pixels
</pre></blockquote>

The scroll amount, returned by <code>getScrollAmount</code>,
indicates how many units will be scrolled and is always a positive
number.  The units to scroll, returned by <code>getUnitsToScroll</code>,
is positive when scrolling down and negative when scrolling up.
The number of pixels for the vertical unit is obtained from the
vertical scroll bar using the <code>getUnitIncrement</code> method.
In the preceding example, rolling the mouse wheel one notch upward
should result in the text area scrolling upward 48 pixels (3x16).

<p>
For a system that uses block increments for mouse-wheel scrolling, for
the same movement of the mouse wheel the output might look like this:

<blockquote><pre>
javax.swing.JTextArea: Mouse wheel moved UP 1 notch(es)
    Scroll type: WHEEL_BLOCK_SCROLL
    Vertical block increment: 307 pixels
</pre></blockquote>

The vertical block increment is obtained from the vertical
scroll bar using the <code>getBlockIncrement</code> method.
In this case, rolling the mouse wheel upward one notch means
that the text area should scroll upward 307 pixels.

<p>
You can find the demo's code in

<a class="SourceLink" target="_blank" href="examples/MouseWheelEventDemo.java"><code>MouseWheelEventDemo.java</code></a>. Here is the code that's related to mouse-wheel event
handling:

<blockquote><pre>
public class MouseWheelEventDemo ... implements MouseWheelListener ... {
    public MouseWheelEventDemo() {
        <em>//where initialization occurs:</em>
        //Register for mouse-wheel events on the text area.
        textArea.addMouseWheelListener(this);
        ...
    }

    public void mouseWheelMoved(MouseWheelEvent e) {
       String message;
       int notches = e.getWheelRotation();
       if (notches < 0) {
           message = "Mouse wheel moved UP "
                        + -notches + " notch(es)" + newline;
       } else {
           message = "Mouse wheel moved DOWN "
                        + notches + " notch(es)" + newline;
       }
       if (e.getScrollType() == MouseWheelEvent.WHEEL_UNIT_SCROLL) {
           message += "    Scroll type: WHEEL_UNIT_SCROLL" + newline;
           message += "    Scroll amount: " + e.getScrollAmount()
                   + " unit increments per notch" + newline;
           message += "    Units to scroll: " + e.getUnitsToScroll()
                   + " unit increments" + newline;
           message += "    Vertical unit increment: "
               + scrollPane.getVerticalScrollBar().getUnitIncrement(1)
               + " pixels" + newline;
       } else { //scroll type == MouseWheelEvent.WHEEL_BLOCK_SCROLL
           message += "    Scroll type: WHEEL_BLOCK_SCROLL" + newline;
           message += "    Vertical block increment: "
               + scrollPane.getVerticalScrollBar().getBlockIncrement(1)
               + " pixels" + newline;
       }
       saySomething(message, e);
    }
    ...
}
</pre></blockquote>

</blockquote>
<h3>
<a name="api">The Mouse Wheel Listener API</a>
</h3>
<blockquote>

<p align=center><a name="mousewheellistener">The MouseWheelListener
   Interface</a>
<p><em>Because <code>MouseWheelListener</code> has only one method,
   it has no corresponding adapter class.  This API was
   introduced in release 1.4.
   </em>
<table border=1>
<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/java/awt/event/MouseWheelListener.html#mouseWheelMoved(java.awt.event.MouseWheelEvent)">mouseWheelMoved(MouseWheelEvent)</a></td>
<td>Called when the mouse wheel is rotated.
</td>
</tr>
</table>

<p align=center><a name="mousewheelevent">The MouseWheelEvent Class</a>
<p><em>All of this API was introduced in release 1.4.</em>
<table border=1>
<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/java/awt/event/MouseWheelEvent.html#getScrollType()">int getScrollType()</a></td>
<td>Return the type of scrolling to be used.  Possible values
    are <code>WHEEL_BLOCK_SCROLL</code> and
    <code>WHEEL_UNIT_SCROLL</code> and are determined by the
    native platform.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/MouseWheelEvent.html#getWheelRotation()">int getWheelRotation()</a></td>
<td>Return the number of notches the mouse wheel was rotated. If
    the mouse wheel rotated towards the user (down) the value is
    positive.  If the mouse wheel rotated away from the user (up)
    the value is negative.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/MouseWheelEvent.html#getScrollAmount()">int getScrollAmount()</a></td>
<td>Return the number of units that should be scrolled per notch.
    This is always a positive number and is only
    valid if the scroll type is
    <code>MouseWheelEvent.WHEEL_UNIT_SCROLL</code>.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/event/MouseWheelEvent.html#getUnitsToScroll()">int getUnitsToScroll()</a></td>
<td>Return the positive or negative units to scroll for the
     current event. This is only valid when the scroll type is 
    <code>MouseWheelEvent.WHEEL_UNIT_SCROLL</code>.
</td>
</tr>
</table>

</blockquote>
<a name="eg">
<h3>Examples that Use Mouse Wheel Listeners</h3>
</a>
<blockquote>
The following table lists the
examples that use mouse-wheel listeners.
<p>

<table>
<tr>
<th align=left> Example
</th>
<th align=left> Where Described
</th>
<th align=left> Notes

</th>
</tr>

<tr valign=top>
<td> <a href="examples/index.html#MouseWheelEventDemo"><code>MouseWheelEventDemo</code></a>
</td>
<td> This section
</td>
<td> Reports all mouse wheel events that occur within a text area
     to demonstrate the circumstances under which mouse wheel
     events are fired.
</td>
</tr>
</table>
        </blockquote>
        <div class=NavBit>
            <a target=_top href=mousemotionlistener.html>&laquo; Previous</a>
            &bull;
            <a target=_top href=../TOC.html>Trail</a>
            &bull;
            <a target=_top href=propertychangelistener.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 Write a Mouse-Motion Listener
        <br><b>Next page:</b> How to Write a Property Change Listener
    </div>
    </body>
</html>