MouseEvent (Java 2 Platform SE v1.4.1)

java.awt.event
Class MouseEvent
java.lang.Object
  |
  +--java.util.EventObject
        |
        +--java.awt.AWTEvent
              |
              +--java.awt.event.ComponentEvent
                    |
                    +--java.awt.event.InputEvent
                          |
                          +--java.awt.event.MouseEvent
All Implemented Interfaces:
Serializable

Direct Known Subclasses:
MenuDragMouseEvent, MouseWheelEvent

public class MouseEvent
extends InputEvent

An event which indicates that a mouse action occurred in a component. A mouse action is considered to occur in a particular component if and only if the mouse cursor is over the unobscured part of the component's bounds when the action happens. Component bounds can be obscurred by the visible component's children or by a menu or by a top-level window. This event is used both for mouse events (click, enter, exit) and mouse motion events (moves and drags).
This low-level event is generated by a component object for:

Mouse Events

a mouse button is pressed
a mouse button is released
a mouse button is clicked (pressed and released)
the mouse cursor enters the unobscured part of component's geometry
the mouse cursor exits the unobscured part of component's geometry

Mouse Motion Events

the mouse is moved
the mouse is dragged

A MouseEvent object is passed to every MouseListener or MouseAdapter object which is registered to receive the "interesting" mouse events using the component's addMouseListener method. (MouseAdapter objects implement the MouseListener interface.) Each such listener object gets a MouseEvent containing the mouse event.
A MouseEvent object is also passed to every MouseMotionListener or MouseMotionAdapter object which is registered to receive mouse motion events using the component's addMouseMotionListener method. (MouseMotionAdapter objects implement the MouseMotionListener interface.) Each such listener object gets a MouseEvent containing the mouse motion event.
When a mouse button is clicked, events are generated and sent to the registered MouseListeners. The state of modal keys can be retrieved using InputEvent.getModifiers() and InputEvent.getModifiersEx(). The button mask returned by InputEvent.getModifiers() reflects only the button that changed state, not the current state of all buttons. (Note: Due to overlap in the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK, this is not always true for mouse events involving modifier keys). To get the state of all buttons and modifier keys, use InputEvent.getModifiersEx(). The button which has changed state is returned by getButton()
For example, if the first mouse button is pressed, events are sent in the following order:
    id              modifiers    button           
    MOUSE_PRESSED:  BUTTON1_MASK BUTTON1
    MOUSE_RELEASED: BUTTON1_MASK BUTTON1
    MOUSE_CLICKED:  BUTTON1_MASK BUTTON1
 
When multiple mouse buttons are pressed, each press, release, and click results in a separate event.
For example, if the user presses button 1 followed by button 2, and then releases them in the same order, the following sequence of events is generated:
    id              modifiers    button           
    MOUSE_PRESSED:  BUTTON1_MASK BUTTON1
    MOUSE_PRESSED:  BUTTON2_MASK BUTTON2
    MOUSE_RELEASED: BUTTON1_MASK BUTTON1
    MOUSE_CLICKED:  BUTTON1_MASK BUTTON1
    MOUSE_RELEASED: BUTTON2_MASK BUTTON2
    MOUSE_CLICKED:  BUTTON2_MASK BUTTON2
 
If button 2 is released first, the MOUSE_RELEASED/MOUSE_CLICKED pair for BUTTON2_MASK arrives first, followed by the pair for BUTTON1_MASK.
MOUSE_DRAGGED events are delivered to the Component in which the mouse button was pressed until the mouse button is released (regardless of whether the mouse position is within the bounds of the Component). Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation. In a multi-screen environment mouse drag events are delivered to the Component even if the mouse position is outside the bounds of the GraphicsConfiguration associated with that Component. However, the reported position for mouse drag events in this case may differ from the actual mouse position:

In a multi-screen environment without a virtual device:
The reported coordinates for mouse drag events are clipped to fit within the bounds of the GraphicsConfiguration associated with the Component.
In a multi-screen environment with a virtual device:
The reported coordinates for mouse drag events are clipped to fit within the bounds of the virtual device associated with the Component.

Since:

1.1

See Also:
MouseAdapter, MouseListener, MouseMotionAdapter, MouseMotionListener, MouseWheelListener, Tutorial: Writing a Mouse Listener, Tutorial: Writing a Mouse Motion Listener, Reference: The Java Class Libraries (update file), Serialized Form

Field Summary
static int BUTTON1
    Indicates mouse button #1; used by getButton().
static int BUTTON2
    Indicates mouse button #2; used by getButton().
static int BUTTON3
    Indicates mouse button #3; used by getButton().
static int MOUSE_CLICKED
    The "mouse clicked" event.
static int MOUSE_DRAGGED
    The "mouse dragged" event.
static int MOUSE_ENTERED
    The "mouse entered" event.
static int MOUSE_EXITED
    The "mouse exited" event.
static int MOUSE_FIRST
    The first number in the range of ids used for mouse events.
static int MOUSE_LAST
    The last number in the range of ids used for mouse events.
static int MOUSE_MOVED
    The "mouse moved" event.
static int MOUSE_PRESSED
    The "mouse pressed" event.
static int MOUSE_RELEASED
    The "mouse released" event.
static int MOUSE_WHEEL
    The "mouse wheel" event.
static int NOBUTTON
    Indicates no mouse buttons; used by getButton().

Fields inherited from class java.awt.event.InputEvent
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK

Fields inherited from class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN

Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK

Fields inherited from class java.util.EventObject
source

Constructor Summary
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
    Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
    Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.

Method Summary
int getButton()
    Returns which, if any, of the mouse buttons has changed state.
int getClickCount()
    Returns the number of mouse clicks associated with this event.
static String getMouseModifiersText(int modifiers)
    Returns a String describing the modifier key(s), such as "Shift", or "Ctrl+Shift".
Point getPoint()
    Returns the x,y position of the event relative to the source component.
int getX()
    Returns the horizontal x position of the event relative to the source component.
int getY()
    Returns the vertical y position of the event relative to the source component.
boolean isPopupTrigger()
    Returns whether or not this mouse event is the popup menu trigger event for the platform.
String paramString()
    Returns a parameter string identifying this event.
void translatePoint(int x, int y)
    Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.

Methods inherited from class java.awt.event.InputEvent
consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown

Methods inherited from class java.awt.event.ComponentEvent
getComponent

Methods inherited from class java.awt.AWTEvent
getID, setSource, toString

Methods inherited from class java.util.EventObject
getSource

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MOUSE_FIRST
public static final int MOUSE_FIRST
The first number in the range of ids used for mouse events.

See Also:
Constant Field Values

MOUSE_LAST
public static final int MOUSE_LAST
The last number in the range of ids used for mouse events.

See Also:
Constant Field Values

MOUSE_CLICKED
public static final int MOUSE_CLICKED
The "mouse clicked" event. This MouseEvent occurs when a mouse button is pressed and released.

See Also:
Constant Field Values

MOUSE_PRESSED
public static final int MOUSE_PRESSED
The "mouse pressed" event. This MouseEvent occurs when a mouse button is pushed down.

See Also:
Constant Field Values

MOUSE_RELEASED
public static final int MOUSE_RELEASED
The "mouse released" event. This MouseEvent occurs when a mouse button is let up.

See Also:
Constant Field Values

MOUSE_MOVED
public static final int MOUSE_MOVED
The "mouse moved" event. This MouseEvent occurs when the mouse position changes.

See Also:
Constant Field Values

MOUSE_ENTERED
public static final int MOUSE_ENTERED
The "mouse entered" event. This MouseEvent occurs when the mouse cursor enters the unobscured part of component's geometry.

See Also:
Constant Field Values

MOUSE_EXITED
public static final int MOUSE_EXITED
The "mouse exited" event. This MouseEvent occurs when the mouse cursor exits the unobscured part of component's geometry.

See Also:
Constant Field Values

NOBUTTON
public static final int NOBUTTON
Indicates no mouse buttons; used by getButton().

Since:

1.4

See Also:
Constant Field Values

BUTTON1
public static final int BUTTON1
Indicates mouse button #1; used by getButton().

Since:

1.4

See Also:
Constant Field Values

BUTTON2
public static final int BUTTON2
Indicates mouse button #2; used by getButton().

Since:

1.4

See Also:
Constant Field Values

BUTTON3
public static final int BUTTON3
Indicates mouse button #3; used by getButton().

Since:

1.4

See Also:
Constant Field Values

MOUSE_DRAGGED
public static final int MOUSE_DRAGGED
The "mouse dragged" event. This MouseEvent occurs when the mouse position changes while a mouse button is pressed.

See Also:
Constant Field Values

MOUSE_WHEEL
public static final int MOUSE_WHEEL
The "mouse wheel" event. This is the only MouseWheelEvent. It occurs when a mouse equipped with a wheel has its wheel rotated.

Since:

1.4

See Also:
Constant Field Values

Constructor Detail

MouseEvent
public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger,
                  int button)
Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.
Note that passing in an invalid id results in unspecified behavior.

Parameters:
source - the Component that originated the event
id - the integer that identifies the event
when - a long int that gives the time the event occurred
modifiers - the modifier keys down during event (e.g. shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.
x - the horizontal x coordinate for the mouse location
y - the vertical y coordinate for the mouse location
clickCount - the number of mouse clicks associated with event
popupTrigger - a boolean, true if this event is a trigger for a popup menu
button - which of the mouse buttons has changed state. NOBUTTON, BUTTON1, BUTTON2 or BUTTON3.
Throws:
IllegalArgumentException - if if an invalid button value is passed in.
Since:

1.4

MouseEvent
public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger)
Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.
Note that passing in an invalid id results in unspecified behavior.

Parameters:
source - the Component that originated the event
id - the integer that identifies the event
when - a long int that gives the time the event occurred
modifiers - the modifier keys down during event (e.g. shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.
x - the horizontal x coordinate for the mouse location
y - the vertical y coordinate for the mouse location
clickCount - the number of mouse clicks associated with event
popupTrigger - a boolean, true if this event is a trigger for a popup menu

Method Detail

getX
public int getX()
Returns the horizontal x position of the event relative to the source component.

Returns:
x an integer indicating horizontal position relative to the component

getY
public int getY()
Returns the vertical y position of the event relative to the source component.

Returns:
y an integer indicating vertical position relative to the component

getPoint
public Point getPoint()
Returns the x,y position of the event relative to the source component.

Returns:
a Point object containing the x and y coordinates relative to the source component

translatePoint
public void translatePoint(int x,
                           int y)
Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.

Parameters:
x - the horizontal x value to add to the current x coordinate position
y - the vertical y value to add to the current y coordinate position

getClickCount
public int getClickCount()
Returns the number of mouse clicks associated with this event.

Returns:
integer value for the number of clicks

getButton
public int getButton()
Returns which, if any, of the mouse buttons has changed state.

Since:

1.4

isPopupTrigger
public boolean isPopupTrigger()
Returns whether or not this mouse event is the popup menu trigger event for the platform.
Note: Popup menus are triggered differently on different systems. Therefore, isPopupTrigger should be checked in both mousePressed and mouseReleased for proper cross-platform functionality.

Returns:
boolean, true if this event is the popup menu trigger for this platform

getMouseModifiersText
public static String getMouseModifiersText(int modifiers)
Returns a String describing the modifier key(s), such as "Shift", or "Ctrl+Shift". These strings can be localized by changing the awt.properties file.

Returns:
string a text description of the combination of modifier keys that were held down during the event
Since:

1.4

paramString
public String paramString()
Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.

Overrides:
paramString in class ComponentEvent

Returns:
a string identifying the event and its attributes

Field Summary
static int	BUTTON1 Indicates mouse button #1; used by getButton().
static int	BUTTON2 Indicates mouse button #2; used by getButton().
static int	BUTTON3 Indicates mouse button #3; used by getButton().
static int	MOUSE_CLICKED The "mouse clicked" event.
static int	MOUSE_DRAGGED The "mouse dragged" event.
static int	MOUSE_ENTERED The "mouse entered" event.
static int	MOUSE_EXITED The "mouse exited" event.
static int	MOUSE_FIRST The first number in the range of ids used for mouse events.
static int	MOUSE_LAST The last number in the range of ids used for mouse events.
static int	MOUSE_MOVED The "mouse moved" event.
static int	MOUSE_PRESSED The "mouse pressed" event.
static int	MOUSE_RELEASED The "mouse released" event.
static int	MOUSE_WHEEL The "mouse wheel" event.
static int	NOBUTTON Indicates no mouse buttons; used by getButton().

Method Summary
int	getButton() Returns which, if any, of the mouse buttons has changed state.
int	getClickCount() Returns the number of mouse clicks associated with this event.
static String	getMouseModifiersText(int modifiers) Returns a String describing the modifier key(s), such as "Shift", or "Ctrl+Shift".
Point	getPoint() Returns the x,y position of the event relative to the source component.
int	getX() Returns the horizontal x position of the event relative to the source component.
int	getY() Returns the vertical y position of the event relative to the source component.
boolean	isPopupTrigger() Returns whether or not this mouse event is the popup menu trigger event for the platform.
String	paramString() Returns a parameter string identifying this event.
void	translatePoint(int x, int y) Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.

java.awt.event Class MouseEvent

Field Summary

Constructor Summary

Method Summary

Field Detail

MOUSE_FIRST

MOUSE_LAST

MOUSE_CLICKED

MOUSE_PRESSED

MOUSE_RELEASED

MOUSE_MOVED

MOUSE_ENTERED

MOUSE_EXITED

NOBUTTON

BUTTON1

BUTTON2

BUTTON3

MOUSE_DRAGGED

MOUSE_WHEEL

Constructor Detail

MouseEvent

MouseEvent

Method Detail

getX

getY

getPoint

translatePoint

getClickCount

getButton

isPopupTrigger

getMouseModifiersText

paramString

java.awt.event
Class MouseEvent