How to Write a Mouse Wheel Listener

Mouse wheel events tell you when the wheel on the mouse rotates. For information on listening to other mouse events, such as clicks, see How to Write a Mouse Listener (page 689). For information on listening to mouse-dragged events, see How to Write a Mouse-Motion Listener (page 695). 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.

Version Note: The MouseWheelListener ^[30] interface was introduced in release 1.4.

^[30] MouseWheelListener API documentation: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/MouseWheelListener.html.

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.

However, if you create a custom component to be used inside a scroll pane you may need to customize its scrolling behavior 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 Implementing a Scrolling-Savvy Client (page 333) in Chapter 7.

To generate mouse wheel events the cursor must be over the component registered to listen for mouse wheel events. The type of scrolling that occurs, either WHEEL_UNIT_SCROLL or WHEEL_BLOCK_SCROLL , 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.

The MouseWheelEventDemo example demonstrates mouse wheel events (see Figure 12).

Figure 12. The MouseWheelEventDemo application.

Try This:

1. 

   Run MouseWheelEventDemo using Java Web Start or compile and run the example yourself. ^[31]

   ^[31] To run MouseWheelEventDemo using Java Web Start, click the MouseWheelEventDemo link on the RunExamples/events.html page on the CD. You can find the source files here: JavaTutorial/uiswing/events/example-1dot4/index.html#MouseWheelEventDemo .

2. Move the cursor over the text area.

3. Rotate the mouse wheel away from you. You will see one or more mouse wheel events in the up direction.

4. Rotate the mouse wheel in the opposite direction. You will see mouse wheel events in the down direction.

5. Try changing your mouse wheel's scrolling behavior in 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.

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

 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 

The scroll amount, returned by getScrollAmount , indicates how many units will be scrolled and is always a positive number. The units to scroll, returned by getUnitsToScroll , 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 getUnitIncrement method. In the preceding example, rolling the mouse wheel one notch upward should result in the text area scrolling upward 48 pixels (3 x 16).

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:

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

The vertical block increment is obtained from the vertical scroll bar using the getBlock-Increment method. In this case, rolling the mouse wheel upward one notch means that the text area should scroll upward 307 pixels.

You can find the demo's code in MouseWheelEventDemo.java . Here's the code that's related to mouse wheel event handling:

 public class MouseWheelEventDemo ... implements MouseWheelListener ... {  //...where initialization occurs:  //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);     }     ... } 

The Mouse Wheel Listener API

Table 28 lists the methods in the MouseWheelListener interface and Table 29 describes the methods in the MouseWheelEvent class. Note that because MouseWheelListener has only one method, it has no corresponding adapter class. Also refer to the MouseWheelListener API documentation at: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/MouseWheelListener.html. The MouseWheelEvent API documentation is at: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/MouseWheelEvent.html.

Table 28. The MouseWheelListener Interface (This API was introduced in release 1.4.)

Method	Purpose
mouseWheelMoved(MouseWheelEvent)	Called when the mouse wheel is rotated .

Table 29. The MouseWheelEvent Class (This API was introduced in release 1.4.)

Method	Purpose
int getScrollType()	Return the type of scrolling to be used. Possible values are WHEEL_BLOCK_SCROLL and WHEEL_UNIT_SCROLL and are determined by the native platform.
int getWheelRotation()	Return the number of notches the mouse wheel was rotated. If the mouse wheel rotated toward the user (down) the value is positive. If the mouse wheel rotated away from the user (up) the value is negative.
int getScrollAmount()	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 MouseWheelEvent.WHEEL_UNIT_SCROLL .
int getUnitsToScroll()	Return the positive or negative units to scroll for the current event. This is only valid when the scroll type is MouseWheelEvent.WHEEL_UNIT_SCROLL .

Examples That Use Mouse Wheel Listeners

The following examples use mouse wheel listeners.

Example	Where Described	Notes
MouseWheelEventDemo	This section	Reports all mouse wheel events that occur within a text area to demonstrate the circumstances under which mouse wheel events are fired .