If you write programs that show drawings, and you want users to manipulate the drawings with a mouse, then you need to process mouse events. Mouse events are more complex than button clicks or timer ticks.

You use a mouse listener to capture mouse events.

A mouse listener must implement the MouseListener interface, which contains the following five methods:

public interface MouseListener
{
   void mousePressed(MouseEvent event);
       // Called when a mouse button has been pressed on a component
   void mouseReleased(MouseEvent event);
       // Called when a mouse button has been released on a component
   void mouseClicked(MouseEvent event);
       // Called when the mouse has been clicked on a component
   void mouseEntered(MouseEvent event);
       // Called when the mouse enters a component
   void mouseExited(MouseEvent event);
       // Called when the mouse exits a component
}

The mousePressed and mouseReleased methods are called whenever a mouse button is pressed or released. If a button is pressed and released in quick succession, and the mouse has not moved, then the mouseClicked method is called as well. The mouseEntered and mouseExited methods can be used to paint a user-interface component in a special way whenever the mouse is pointing inside it.

The most commonly used method is mousePressed. Users generally expect that their actions are processed as soon as the mouse button is pressed.

You add a mouse listener to a component by calling the addMouseListener method:

public class MyMouseListener implements MouseListener
{
   // Implements five methods
}

MouseListener listener = new MyMouseListener();
component.addMouseListener(listener);

In our sample program, a user clicks on a component containing a rectangle. Whenever the mouse button is pressed, the rectangle is moved to the mouse location. We first enhance the RectangleComponent class and add a moveTo method to move the rectangle to a new position.

ch09/mouse/RectangleComponent.java

1  import java.awt.Graphics;
2  import java.awt.Graphics2D;
3  import java.awt.Rectangle;
4  import javax.swing.JComponent;
5
6  /**
7     This component displays a rectangle that can be moved.
8  */
9  public class RectangleComponent extends JComponent
10 {
11    public RectangleComponent()
12    {
13       // The rectangle that the paint method draws
14       box = new Rectangle(BOX_X, BOX_Y,
15             BOX_WIDTH, BOX_HEIGHT);
16    }
17
18    public void paintComponent(Graphics g)
19    {
20       super.paintComponent(g);
21       Graphics2D g2 = (Graphics2D) g;
22
23       g2.draw(box);
24    }
25
26    /**
27       Moves the rectangle to the given location.
28       @param x the x-position of the new location
29       @param y the y-position of the new location
30    */
31    public void moveTo(int x, int y)
32    {
33       box.setLocation(x, y);
34       repaint();
35    }
36
37    private Rectangle box;
38
39    private static final int BOX_X = 100;
40    private static final int BOX_Y = 100;
41    private static final int BOX_WIDTH = 20;
42    private static final int BOX_HEIGHT = 30;
43 }

Note the call to repaint in the moveTo method. As explained in the preceding section, this call causes the component to repaint itself and show the rectangle in the new position.

Now, add a mouse listener to the component. Whenever the mouse is pressed, the listener moves the rectangle to the mouse location.

class MousePressListener implements MouseListener
{
   public void mousePressed(MouseEvent event)
   {
      int x = event.getX();
      int y = event.getY();
      component.moveTo(x, y);
   }

   // Do-nothing methods
   public void mouseReleased(MouseEvent event) {}
   public void mouseClicked(MouseEvent event) {}
   public void mouseEntered(MouseEvent event) {}
   public void mouseExited(MouseEvent event) {}
}

It often happens that a particular listener specifies actions only for one or two of the listener methods. Nevertheless, all five methods of the interface must be implemented. The unused methods are simply implemented as do-nothing methods.

Go ahead and run the RectangleComponentViewer program. Whenever you click the mouse inside the frame, the top left corner of the rectangle moves to the mouse pointer (see Figure 9-5).

ch09/mouse/RectangleComponentViewer.java

1  import java.awt.event.MouseListener;
2  import java.awt.event.MouseEvent;
3  import javax.swing.JFrame;
4
5  /**
6     This program displays a RectangleComponent.
7  */
8  public class RectangleComponentViewer
9  {
10    public static void main(String[] args)
11    {
12       final RectangleComponent component = new RectangleComponent();
13
14       // Add mouse press listener
15
16       class MousePressListener implements MouseListener
17       {
18          public void mousePressed(MouseEvent event)
19          {
20             int x = event.getX();
21             int y = event.getY();
22             component.moveTo(x, y);
23          }
24
25          // Do-nothing methods
26          public void mouseReleased(MouseEvent event) {}
27          public void mouseClicked(MouseEvent event) {}
28          public void mouseEntered(MouseEvent event) {}
29          public void mouseExited(MouseEvent event) {}
30       }
31
32       MouseListener listener = new MousePressListener();
33       component.addMouseListener(listener);
34
35       JFrame frame = new JFrame();
36       frame.add(component);
37
38       frame.setSize(FRAME_WIDTH, FRAME_HEIGHT);
39       frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
40       frame.setVisible(true);
41    }
42
43    private static final int FRAME_WIDTH = 300;
44    private static final int FRAME_HEIGHT = 400;
45 }

FIGURE 9-5    Clicking the Mouse Moves the Rectangle