Cómo escribir un Oyente de Mouse

Los eventos de Mouse nos cuentan cuando el usuario usa el ratón (o un dispositivo de entrada similar) para interactuar con un componente. Los eventos Mouse ocurren cuando el cursor entra o sale del área de pantalla de un componente, o cuando el usuario pulsa o libera el botón del ratón. Como seguir la pista del movimiento del ratón significa mas sobrecarga del sistema que seguir la pista de los eventos de ratón, los eventos mouse-motion se han separado en otro tipo de oyente (puedes ver Cómo escribir un Oyente de Mouse Motion).

Métodos de Eventos Mouse

El interface MouseListener y su correspondiente clase adaptadora, MouseAdapter, contienen estos métodos:
void mouseClicked(MouseEvent)
Llamado justo después de que el usario pulse sobre el componente escuchado.
void mouseEntered(MouseEvent)
Llamado justo después de que el cursor entre en los límites del componente escuchado.
void mouseExited(MouseEvent)
Llamado justo después de que el cursor salga de los límites del componente escuchado.
void mousePressed(MouseEvent)
Llamado justo después de que el usuario pulse un botón del ratón mientras el cursor está sobre el componente escuchado.
void mouseReleased(MouseEvent)
Llamdo justo después de que el usuario libere un botón del ratón después de una pulsación sobre el componente esuchado.

Una complicación afecta a los evntos mouse-entered, mouse-exited, y mouse-released. Cuando el usuario arrastra (pulsa y mantiene el botón del ratón y luego mueve el ratón), entonces el componente sobre el que estaba el cursor cuando empezó el arrastre es el que recibe todos los subsecuentes eventos de mouse y mouse-motion incluyendo la liberación del botón. Esto significa que ningún otro componente recibera un sólo evento del ratón -- ni siquiera un evento mouse-released -- mientras está ocurriendo el arrastre.

Ejemplos de Manejo de Eventos Mouse

El siguiente applet contiene un oyente de mouse. En la parte superior del applet hay un área vacía, (implementada por una clase llamda BlankArea). El oyente de mouse escucha los eventos del BlankArea y de su contenedor, que es un ejemplar de MouseEventDemo. Cada vez que ocurre un evento de mouse, se muestra un mensaje descriptivo sobre el área blanca. Moviendo el cursor sobre el área blanca y ocasionalmente pulsado algún botón del ratón podemos generar eventos mouse.

Pulsa esta imagen para ejecutar el applet.
Esto es una imagen del GUI del Applet. Para ejecutarlo, pulsa sobre ella. El applet aparecerá en una nueva ventana de tu navegador..

Prueba esto:
  1. Mueve el cursor dentro del rectángulo amarillo de la parte superior del applet.
    Verás uno o más eventos mouse-entered.
  2. Pulsa y mantén el botón del ratón..
    Verás un evento mouse-pressed. Podrías ver algún evento extra como un mouse-exited o mouse-entered.
  3. Libera el botón del ratón.
    Verás une vento mouse-released. Si no has movido el ratón, seguirá un evento mouse-clicked.
  4. Pulsa y mantén el botón del ratón, y arrástralo para el cursor termine fuera del área del applet. Libera el botón del ratón.
    Verás un evento mouse-pressed, seguido de un evento mouse-exited, seguido por un evento mouse-released. No se ha notificado el movimiento del cursor. Para obtener eventos mouse-motion, necesitamos implementar un oyente de mouse-motion.
Puedes encontrar el código del applet en MouseEventDemo.java y BlankArea.java. Aquí tenemos el código de manejo de eventos del applet: 
public class MouseEventDemo ... implements MouseListener {
	...//where initialization occurs:
        //Register for mouse events on blankArea and applet (panel).
        blankArea.addMouseListener(this);
        addMouseListener(this);
    ...

    public void mousePressed(MouseEvent e) {
       saySomething("Mouse pressed; # of clicks: "
                    + e.getClickCount(), e);
    }

    public void mouseReleased(MouseEvent e) {
       saySomething("Mouse released; # of clicks: "
                    + e.getClickCount(), e);
    }

    public void mouseEntered(MouseEvent e) {
       saySomething("Mouse entered", e);
    }

    public void mouseExited(MouseEvent e) {
       saySomething("Mouse exited", e);
    }

    public void mouseClicked(MouseEvent e) {
       saySomething("Mouse clicked (# of clicks: "
                    + e.getClickCount() + ")", e);
    }

    void saySomething(String eventDescription, MouseEvent e) {
        textArea.append(eventDescription + " detected on "
                        + e.getComponent().getClass().getName()
                        + "." + newline);
    }
}
Podemos encontrar más ejemplos de oyentes de ratón en los siguientes ficheros fuente:

La Clase MouseEvent
Cada método de evento mouse tiene un sólo parámetero: un objeto MouseEvent. La clase MouseEvent define los siguientes métodos :

int getClickCount()
Devuelve el número de pulsaciones que el usuario ha realizado (incluyendo este evento).

int getX()
int getY()
Point getPoint()
Devuelve la posición (x,y) en la que ocurrió el evento, relativa al componente que generó el evento.
boolean isPopupTrigger()
Devuelve true si el evento mouse debería hacer que apareciera un menú popup. Como los disparadores de menús popup son dependientes de la plataforma, si nuestro programa los usa, deberíamos llamar a isPopupTrigger en todos los eventos mouse-pressed y mouse-released geneados por componentes sobre los que el popup pueda aparecer.

La clase MouseEvent hereda los siguientes métodos de ComponentEvent.

Component getComponent
Devuelve el componente que generó el evento. Podemos usar este método en vez de getSource.

La clase MouseEvent hereda otros muchos métodos útiles de InputEvent:

void consume()
Hace que el evento no sea procesado por el padre del componente. Se podría usar este método para descartar letras tecleadas en un campo de texto que sólo hacepta números.
int getWhen()
Devuelve el momento en que ocurrió el evento.

boolean isAltDown()
boolean isControlDown()
boolean isMetaDown()
boolean isShiftDown()
Devuelven el estado individual de las teclas modificadores en el momento en que se generó el evento.

int getModifiers()
Devuelve el estado de todas las teclas modificadoras y botónes del ratón, cuando se generó el evento. Podemos usar este método para determinar qué botón fue pulsado (o liberado) cuando el evento del ratón fue generado. La clase InputEvent define estas constantes para usarlas con el método getModifiers: ALT_MASK, BUTTON1_MASK, BUTTON2__MASK, BUTTON3_MASK, CTRL_MASK, META_MASK, y SHIFT_MASK. Por ejemplo, la siguiente expresión es verdadera si se pulsó el botón derecho: 
(mouseEvent.getModifiers() & InputEvent.BUTTON3_MASK)
== InputEvent.BUTTON3_MASK
La clase SwingUtilities contiene métodos de conveniencia para determinar si se ha pulsado un botón particular del ratón:
static boolean isLeftMouseButton(MouseEvent)
static boolean isMiddleMouseButton(MouseEvent)
static boolean isLEFTMouseButton(MouseEvent)

Ozito