How to Write a Mouse-Motion Listener

How to Write a Mouse-Motion Listener

Mouse-motion events tell you when the user uses the mouse (or a similar input device) to move the onscreen cursor. For information on listening for other kinds of mouse events, such as clicks, see How to Write a Mouse Listener (page 689). For information on listening for mouse wheel events, see How to Write a Mouse Wheel Listener (page 699). If your program needs to detect both mouse events and mouse-motion events, you can use Swing's convenient MouseInputAdapter class, which implements both MouseListener and Mouse-MotionListener .

Figure 11 shows an example with a mouse-motion listener. It's exactly like the example in How to Write a Mouse Listener (page 689), except for substituting MouseMotionListener ^[28] for MouseListener , implementing the mouseDragged and mouseMoved methods instead of the mouse listener methods , and displaying coordinates instead of numbers of clicks.

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

Figure 11. The MouseMotionEventDemo application.

Try This:

1. 

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

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

2. Move the cursor into the yellow rectangle at the top of the window. You'll see one or more mouse-moved events.

3. Press and hold the mouse button, and then move the mouse so that the cursor is outside the yellow rectangle. You'll see mouse-dragged events.

Here's the code from MouseMotionEventDemo.java that implements the mouse-motion event handling:

 public class MouseMotionEventDemo extends JPanel                                   implements MouseMotionListener {  //...in initialization code:  //Register for mouse events on blankArea and panel.         blankArea.addMouseMotionListener(this);         addMouseMotionListener(this);         ...     }     public void mouseMoved(MouseEvent e) {        saySomething("Mouse moved", e);     }     public void mouseDragged(MouseEvent e) {        saySomething("Mouse dragged", e);     }     void saySomething(String eventDescription, MouseEvent e) {         textArea.append(eventDescription                         + " (" + e.getX() + "," + e.getY() + ")"                         + " detected on "                         + e.getComponent().getClass().getName()                         + newline);     } } 

A more interesting example is SelectionDemo , which is discussed in Introduction to Painting Concepts (page 134) in Chapter 6. The program draws a rectangle illustrating the user's current dragging. To do this, it must implement an event handler for three kinds of mouse events: mouse presses, mouse drags , and mouse releases. To be informed of all these events, the handler must implement both the MouseListener and MouseMotionListener interfaces, and be registered as both a mouse listener and a mouse-motion listener. To avoid having to define empty methods, the handler doesn't implement either listener interface directly. Instead, it extends MouseInputAdapter , as the following code snippet shows.

  ...//where initialization occurs:  MyListener myListener = new MyListener();     addMouseListener(myListener);     addMouseMotionListener(myListener); ... private class MyListener extends MouseInputAdapter {     public void mousePressed(MouseEvent e) {         int x = e.getX();         int y = e.getY();         currentRect = new Rectangle(x, y, 0, 0);         updateDrawableRect(getWidth(), getHeight());         repaint();     }     public void mouseDragged(MouseEvent e) {         updateSize(e);     }     public void mouseReleased(MouseEvent e) {         updateSize(e);     }     ...     void updateSize(MouseEvent e) {         int x = e.getX();         int y = e.getY();         ...         repaint(...);     } 

The Mouse-Motion Listener API

Table 27 lists the methods in the MouseMotionListener . Each mouse-motion event method has a single parameterand it's not called MouseMotionEvent . Instead, each mouse-motion event method uses a MouseEvent argument. You can find methods defined by the Mouse-Event class and its superclass InputEvent in Table 25 (page 692) and Table 26 (page 693), respectively. Also refer to the relevant API documentation at:

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/MouseMotionListener.html

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/MouseEvent.html

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/InputEvent.html

Table 27. The MouseMotionListener Interface (The corresponding adapter class is MouseMotionAdapter . ^[a] )

Method	Purpose
mouseDragged(MouseEvent)	Called in response to the user moving the mouse while holding a mouse button down. This event is fired by the component that fired the most recent mouse-pressed event, even if the cursor is no longer over that component.
mouseMoved(MouseEvent)	Called in response to the user moving the mouse with no mouse buttons pressed. This event is fired by the component that's currently under the cursor.

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

Examples That Use Mouse-Motion Listeners

The following examples use mouse-motion listeners.

Example	Where Described	Notes
MouseMotionEventDemo	This section	Reports all mouse-motion events that occur within a blank panel to demonstrate the circumstances under which mouse-motion events are fired.
LayeredPaneDemo and LayeredPaneDemo2	How to Use Layered Panes (page 258)	Moves an image of Duke around within a layered pane in response to mouse-motion events.
SelectionDemo	Introduction to Painting Concepts (page 134)	An applet that lets the user drag a rectangle to select a portion of an image. Uses a subclass of MouseInputAdapter to listen to both mouse events and mouse-motion events.
GlassPaneDemo	How to Use Root Panes (page 316)	Uses a subclass of MouseInputAdapter to listen to mouse events and mouse-motion events on the root pane's glass pane. Redispatches the events to underlying components .
ScrollDemo	How to Use Scroll Panes (page 325)	The label subclass, ScrollablePicture , uses a mouse-motion listener to allow the user to scroll the picture even when the user drags outside the window.