java.lang.Object | |||||
↳ | java.util.EventObject | ||||
↳ | java.awt.AWTEvent | ||||
↳ | java.awt.event.ComponentEvent | ||||
↳ | java.awt.event.InputEvent | ||||
↳ | java.awt.event.MouseEvent |
Known Direct Subclasses |
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.
For lightweight components, such as Swing's components, mouse events
are only dispatched to the component if the mouse event type has been
enabled on the component. A mouse event type is enabled by adding the
appropriate mouse-based EventListener
to the component
(MouseListener
or MouseMotionListener
), or by invoking
enableEvents(long)
with the appropriate mask parameter
(AWTEvent.MOUSE_EVENT_MASK
or AWTEvent.MOUSE_MOTION_EVENT_MASK
).
If the mouse event type has not been enabled on the component, the
corresponding mouse events are dispatched to the first ancestor that
has enabled the mouse event type.
For example, if a MouseListener
has been added to a component, or
enableEvents(AWTEvent.MOUSE_EVENT_MASK)
has been invoked, then all
the events defined by MouseListener
are dispatched to the component.
On the other hand, if a MouseMotionListener
has not been added and
enableEvents
has not been invoked with
AWTEvent.MOUSE_MOTION_EVENT_MASK
, then mouse motion events are not
dispatched to the component. Instead the mouse motion events are
dispatched to the first ancestors that has enabled mouse motion
events.
This low-level event is generated by a component object for:
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 MouseListener
s.
The state of modal keys can be retrieved using getModifiers()
and getModifiersEx()
.
The button mask returned by 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
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 buttonWhen multiple mouse buttons are pressed, each press, release, and click results in a separate event.MOUSE_PRESSED
:BUTTON1_MASK
BUTTON1
MOUSE_RELEASED
:BUTTON1_MASK
BUTTON1
MOUSE_CLICKED
:BUTTON1_MASK
BUTTON1
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 buttonIf button 2 is released first, theMOUSE_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
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:
GraphicsConfiguration
associated with
the Component
.
Component
.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | BUTTON1 | Indicates mouse button #1; used by getButton() . |
|||||||||
int | BUTTON2 | Indicates mouse button #2; used by getButton() . |
|||||||||
int | BUTTON3 | Indicates mouse button #3; used by getButton() . |
|||||||||
int | MOUSE_CLICKED | The "mouse clicked" event. | |||||||||
int | MOUSE_DRAGGED | The "mouse dragged" event. | |||||||||
int | MOUSE_ENTERED | The "mouse entered" event. | |||||||||
int | MOUSE_EXITED | The "mouse exited" event. | |||||||||
int | MOUSE_FIRST | The first number in the range of ids used for mouse events. | |||||||||
int | MOUSE_LAST | The last number in the range of ids used for mouse events. | |||||||||
int | MOUSE_MOVED | The "mouse moved" event. | |||||||||
int | MOUSE_PRESSED | The "mouse pressed" event. | |||||||||
int | MOUSE_RELEASED | The "mouse released" event. | |||||||||
int | MOUSE_WHEEL | The "mouse wheel" event. | |||||||||
int | NOBUTTON | Indicates no mouse buttons; used by getButton() . |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.awt.event.InputEvent
| |||||||||||
From class
java.awt.event.ComponentEvent
| |||||||||||
From class
java.awt.AWTEvent
|
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.awt.AWTEvent
| |||||||||||
From class
java.util.EventObject
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a
MouseEvent object with the
specified source component,
type, modifiers, coordinates, and click count. | |||||||||||
Constructs a
MouseEvent object with the
specified source component,
type, modifiers, coordinates, and click count. | |||||||||||
Constructs a
MouseEvent object with the
specified source component,
type, modifiers, coordinates, absolute coordinates, and click count. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns which, if any, of the mouse buttons has changed state.
| |||||||||||
Returns the number of mouse clicks associated with this event.
| |||||||||||
Returns the absolute x, y position of the event.
| |||||||||||
Returns a
String describing the modifier keys and
mouse buttons that were down during the event, such as "Shift",
or "Ctrl+Shift". | |||||||||||
Returns the x,y position of the event relative to the source component.
| |||||||||||
Returns the horizontal x position of the event relative to the
source component.
| |||||||||||
Returns the absolute horizontal x position of the event.
| |||||||||||
Returns the vertical y position of the event relative to the
source component.
| |||||||||||
Returns the absolute vertical y position of the event.
| |||||||||||
Returns whether or not this mouse event is the popup menu
trigger event for the platform.
| |||||||||||
Returns a parameter string identifying this event.
| |||||||||||
Translates the event's coordinates to a new position
by adding specified
x (horizontal) and y
(vertical) offsets. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.awt.event.InputEvent
| |||||||||||
From class
java.awt.event.ComponentEvent
| |||||||||||
From class
java.awt.AWTEvent
| |||||||||||
From class
java.util.EventObject
| |||||||||||
From class
java.lang.Object
|
Indicates mouse button #1; used by getButton()
.
Indicates mouse button #2; used by getButton()
.
Indicates mouse button #3; used by getButton()
.
The "mouse clicked" event. This MouseEvent
occurs when a mouse button is pressed and released.
The "mouse dragged" event. This MouseEvent
occurs when the mouse position changes while a mouse button is pressed.
The "mouse entered" event. This MouseEvent
occurs when the mouse cursor enters the unobscured part of component's
geometry.
The "mouse exited" event. This MouseEvent
occurs when the mouse cursor exits the unobscured part of component's
geometry.
The first number in the range of ids used for mouse events.
The last number in the range of ids used for mouse events.
The "mouse moved" event. This MouseEvent
occurs when the mouse position changes.
The "mouse pressed" event. This MouseEvent
occurs when a mouse button is pushed down.
The "mouse released" event. This MouseEvent
occurs when a mouse button is let up.
The "mouse wheel" event. This is the only MouseWheelEvent
.
It occurs when a mouse equipped with a wheel has its wheel rotated.
Indicates no mouse buttons; used by getButton()
.
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. Creating an invalid event (such
as by using more than one of the old _MASKs, or modifier/button
values which don't match) results in unspecified behavior.
An invocation of the form
MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger, button)
behaves in exactly the same way as the invocation
MouseEvent
(source, id, when, modifiers,
x, y, xAbs, yAbs, clickCount, popupTrigger, button)
where xAbs and yAbs defines as source's location on screen plus
relative coordinates x and y.
xAbs and yAbs are set to zero if the source is not showing.
This method throws an
IllegalArgumentException
if source
is null
.
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 . |
IllegalArgumentException | if an invalid button
value is passed in |
---|---|
IllegalArgumentException | if source is null |
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.
An invocation of the form
MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)
behaves in exactly the same way as the invocation
MouseEvent
(source, id, when, modifiers,
x, y, xAbs, yAbs, clickCount, popupTrigger, MouseEvent.NOBUTTON)
where xAbs and yAbs defines as source's location on screen plus
relative coordinates x and y.
xAbs and yAbs are set to zero if the source is not showing.
This method throws an IllegalArgumentException
if source
is null
.
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 |
IllegalArgumentException | if source is null
|
---|
Constructs a MouseEvent
object with the
specified source component,
type, modifiers, coordinates, absolute coordinates, and click count.
Note that passing in an invalid id
results in
unspecified behavior. Creating an invalid event (such
as by using more than one of the old _MASKs, or modifier/button
values which don't match) results in unspecified behavior.
Even if inconsistent values for relative and absolute coordinates are
passed to the constructor, the mouse event instance is still
created and no exception is thrown.
This method throws an
IllegalArgumentException
if source
is null
.
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 |
xAbs | the absolute horizontal x coordinate for the mouse location |
yAbs | the absolute 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 . |
IllegalArgumentException | if an invalid button
value is passed in |
---|---|
IllegalArgumentException | if source is null |
Returns which, if any, of the mouse buttons has changed state.
NOBUTTON
,
BUTTON1
,
BUTTON2
or
BUTTON3
.Returns the number of mouse clicks associated with this event.
Returns the absolute x, y position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, these coordinates are relative to the virtual coordinate system. Otherwise, these coordinates are relative to the coordinate system associated with the Component's GraphicsConfiguration.
Point
object containing the absolute x
and y coordinates.Returns a String
describing the modifier keys and
mouse buttons that were down during the event, such as "Shift",
or "Ctrl+Shift". These strings can be localized by changing
the awt.properties
file.
Note that InputEvent.ALT_MASK
and
InputEvent.BUTTON2_MASK
have the same value,
so the string "Alt" is returned for both modifiers. Likewise,
InputEvent.META_MASK
and
InputEvent.BUTTON3_MASK
have the same value,
so the string "Meta" is returned for both modifiers.
modifiers | a modifier mask describing the modifier keys and mouse buttons that were down during the event |
---|
Returns the x,y position of the event relative to the source component.
Point
object containing the x and y coordinates
relative to the source component
Returns the horizontal x position of the event relative to the source component.
Returns the absolute horizontal x position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, this coordinate is relative to the virtual coordinate system. Otherwise, this coordinate is relative to the coordinate system associated with the Component's GraphicsConfiguration.
Returns the vertical y position of the event relative to the source component.
Returns the absolute vertical y position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, this coordinate is relative to the virtual coordinate system. Otherwise, this coordinate is relative to the coordinate system associated with the Component's GraphicsConfiguration.
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 a parameter string identifying this event. This method is useful for event-logging and for debugging.
Translates the event's coordinates to a new position
by adding specified x
(horizontal) and y
(vertical) offsets.
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 |