Serializable
MenuDragMouseEvent
, MouseWheelEvent
public non-sealed class MouseEvent extends InputEvent
EventListener
to the component (MouseListener
or MouseMotionListener
), or by invoking Component.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 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
. Some extra mouse buttons are added to extend the standard set of buttons represented by the following constants:BUTTON1
, BUTTON2
, and BUTTON3
. Extra buttons have no assigned BUTTONx
constants as well as their button masks have no assigned BUTTONx_DOWN_MASK
constants. Nevertheless, ordinal numbers starting from 4 may be used as button numbers (button ids). Values obtained by the getMaskForButton(button)
method may be used as button masks.
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
. An unspecified behavior will be caused if the id
parameter of any particular MouseEvent
instance is not in the range from MOUSE_FIRST
to MOUSE_LAST
-1 (MOUSE_WHEEL
is not acceptable).
Modifier and Type | Field | Description |
---|---|---|
static final int |
BUTTON1 |
Indicates mouse button #1; used by getButton() . |
static final int |
BUTTON2 |
Indicates mouse button #2; used by getButton() . |
static final int |
BUTTON3 |
Indicates mouse button #3; used by getButton() . |
static final int |
MOUSE_CLICKED |
The "mouse clicked" event. |
static final int |
MOUSE_DRAGGED |
The "mouse dragged" event. |
static final int |
MOUSE_ENTERED |
The "mouse entered" event. |
static final int |
MOUSE_EXITED |
The "mouse exited" event. |
static final int |
MOUSE_FIRST |
The first number in the range of ids used for mouse events. |
static final int |
MOUSE_LAST |
The last number in the range of ids used for mouse events. |
static final int |
MOUSE_MOVED |
The "mouse moved" event. |
static final int |
MOUSE_PRESSED |
The "mouse pressed" event. |
static final int |
MOUSE_RELEASED |
The "mouse released" event. |
static final int |
MOUSE_WHEEL |
The "mouse wheel" event. |
static final int |
NOBUTTON |
Indicates no mouse buttons; used by getButton() . |
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
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
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
source
Constructor | Description |
---|---|
MouseEvent |
Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, click count, and popupTrigger flag. |
MouseEvent |
Constructs a MouseEvent object with the specified source component, type, time, modifiers, coordinates, click count, popupTrigger flag, and button number. |
MouseEvent |
Constructs a MouseEvent object with the specified source component, type, time, modifiers, coordinates, absolute coordinates, click count, popupTrigger flag, and button number. |
Modifier and Type | Method | Description |
---|---|---|
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. |
Point |
getLocationOnScreen() |
Returns the absolute x, y position of the event. |
static String |
getMouseModifiersText |
Returns a String instance describing the modifier keys and mouse buttons that were down during the event, 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 |
getXOnScreen() |
Returns the absolute horizontal x position of the event. |
int |
getY() |
Returns the vertical y position of the event relative to the source component. |
int |
getYOnScreen() |
Returns the absolute vertical y position of the event. |
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 |
Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets. |
consume, getMaskForButton, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
getComponent
getSource
public static final int MOUSE_FIRST
public static final int MOUSE_LAST
public static final int MOUSE_CLICKED
MouseEvent
occurs when a mouse button is pressed and released.public static final int MOUSE_PRESSED
MouseEvent
occurs when a mouse button is pushed down.public static final int MOUSE_RELEASED
MouseEvent
occurs when a mouse button is let up.public static final int MOUSE_MOVED
MouseEvent
occurs when the mouse position changes.public static final int MOUSE_ENTERED
MouseEvent
occurs when the mouse cursor enters the unobscured part of component's geometry.public static final int MOUSE_EXITED
MouseEvent
occurs when the mouse cursor exits the unobscured part of component's geometry.public static final int MOUSE_DRAGGED
MouseEvent
occurs when the mouse position changes while a mouse button is pressed.public static final int MOUSE_WHEEL
MouseWheelEvent
. It occurs when a mouse equipped with a wheel has its wheel rotated.public static final int NOBUTTON
getButton()
.public static final int BUTTON1
getButton()
.public static final int BUTTON2
getButton()
.public static final int BUTTON3
getButton()
.public MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
MouseEvent
object with the specified source component, type, time, modifiers, coordinates, click count, popupTrigger flag, and button number. 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 eventid
- An integer indicating the type of event. For information on allowable values, see the class description for MouseEvent
when
- A long integer that gives the time the event occurred. Passing negative or zero value is not recommendedmodifiers
- a modifier mask describing the modifier keys and mouse buttons (for example, shift, ctrl, alt, and meta) that are down during the event. Only extended modifiers are allowed to be used as a value for this parameter (see the InputEvent.getModifiersEx()
class for the description of extended modifiers). Passing negative parameter is not recommended. Zero value means that no modifiers were passedx
- The horizontal x coordinate for the mouse location. It is allowed to pass negative valuesy
- The vertical y coordinate for the mouse location. It is allowed to pass negative valuesclickCount
- The number of mouse clicks associated with event. Passing negative value is not recommendedpopupTrigger
- A boolean that equals true
if this event is a trigger for a popup menubutton
- An integer that indicates, which of the mouse buttons has changed its state. The following rules are applied to this parameter: disabled
by Java then it is allowed to create MouseEvent
objects only with the standard buttons: NOBUTTON
, BUTTON1
, BUTTON2
, and BUTTON3
. enabled
by Java then it is allowed to create MouseEvent
objects with the standard buttons. In case the support for extended mouse buttons is enabled
by Java, then in addition to the standard buttons, MouseEvent
objects can be created using buttons from the range starting from 4 to MouseInfo.getNumberOfButtons()
if the mouse has more than three buttons. IllegalArgumentException
- if button
is less than zeroIllegalArgumentException
- if source
is nullIllegalArgumentException
- if button
is greater than BUTTON3 and the support for extended mouse buttons is disabled
by JavaIllegalArgumentException
- if button
is greater than the current number of buttons
and the support for extended mouse buttons is enabled
by JavaIllegalArgumentException
- if an invalid button
value is passed inIllegalArgumentException
- if source
is nullpublic MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
MouseEvent
object with the specified source component, type, modifiers, coordinates, click count, and popupTrigger flag. 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 eventid
- An integer indicating the type of event. For information on allowable values, see the class description for MouseEvent
when
- A long integer that gives the time the event occurred. Passing negative or zero value is not recommendedmodifiers
- a modifier mask describing the modifier keys and mouse buttons (for example, shift, ctrl, alt, and meta) that are down during the event. Only extended modifiers are allowed to be used as a value for this parameter (see the InputEvent.getModifiersEx()
class for the description of extended modifiers). Passing negative parameter is not recommended. Zero value means that no modifiers were passedx
- The horizontal x coordinate for the mouse location. It is allowed to pass negative valuesy
- The vertical y coordinate for the mouse location. It is allowed to pass negative valuesclickCount
- The number of mouse clicks associated with event. Passing negative value is not recommendedpopupTrigger
- A boolean that equals true
if this event is a trigger for a popup menuIllegalArgumentException
- if source
is nullpublic MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, int button)
MouseEvent
object with the specified source component, type, time, modifiers, coordinates, absolute coordinates, click count, popupTrigger flag, and button number. 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 eventid
- An integer indicating the type of event. For information on allowable values, see the class description for MouseEvent
when
- A long integer that gives the time the event occurred. Passing negative or zero value is not recommendedmodifiers
- a modifier mask describing the modifier keys and mouse buttons (for example, shift, ctrl, alt, and meta) that are down during the event. Only extended modifiers are allowed to be used as a value for this parameter (see the InputEvent.getModifiersEx()
class for the description of extended modifiers). Passing negative parameter is not recommended. Zero value means that no modifiers were passedx
- The horizontal x coordinate for the mouse location. It is allowed to pass negative valuesy
- The vertical y coordinate for the mouse location. It is allowed to pass negative valuesxAbs
- The absolute horizontal x coordinate for the mouse location It is allowed to pass negative valuesyAbs
- The absolute vertical y coordinate for the mouse location It is allowed to pass negative valuesclickCount
- The number of mouse clicks associated with event. Passing negative value is not recommendedpopupTrigger
- A boolean that equals true
if this event is a trigger for a popup menubutton
- An integer that indicates, which of the mouse buttons has changed its state. The following rules are applied to this parameter: disabled
by Java then it is allowed to create MouseEvent
objects only with the standard buttons: NOBUTTON
, BUTTON1
, BUTTON2
, and BUTTON3
. enabled
by Java then it is allowed to create MouseEvent
objects with the standard buttons. In case the support for extended mouse buttons is enabled
by Java, then in addition to the standard buttons, MouseEvent
objects can be created using buttons from the range starting from 4 to MouseInfo.getNumberOfButtons()
if the mouse has more than three buttons. IllegalArgumentException
- if button
is less than zeroIllegalArgumentException
- if source
is nullIllegalArgumentException
- if button
is greater than BUTTON3 and the support for extended mouse buttons is disabled
by JavaIllegalArgumentException
- if button
is greater than the current number of buttons
and the support for extended mouse buttons is enabled
by JavaIllegalArgumentException
- if an invalid button
value is passed inIllegalArgumentException
- if source
is nullpublic Point getLocationOnScreen()
Point
object containing the absolute x and y coordinates.public int getXOnScreen()
public int getYOnScreen()
public int getX()
public int getY()
public Point getPoint()
Point
object containing the x and y coordinates relative to the source componentpublic void translatePoint(int x, int y)
x
(horizontal) and y
(vertical) offsets.x
- the horizontal x value to add to the current x coordinate positiony
- the vertical y value to add to the current y coordinate positionpublic int getClickCount()
public int getButton()
MouseInfo.getNumberOfButtons()
value. The returned value includes at least the following constants: NOBUTTON
BUTTON1
BUTTON2
BUTTON3
if (anEvent.getButton() == MouseEvent.BUTTON1) {In particular, for a mouse with one, two, or three buttons this method may return the following values:
NOBUTTON
) BUTTON1
) BUTTON2
) BUTTON3
) BUTTON3
have no constant identifier. So if a mouse with five buttons is installed, this method may return the following values: NOBUTTON
) BUTTON1
) BUTTON2
) BUTTON3
) Note: If support for extended mouse buttons is disabled
by Java then the AWT event subsystem does not produce mouse events for the extended mouse buttons. So it is not expected that this method returns anything except NOBUTTON
, BUTTON1
, BUTTON2
, BUTTON3
.
MouseInfo.getNumberOfButtons()
if support for the extended mouse buttons is enabled
by Java. That range includes NOBUTTON
, BUTTON1
, BUTTON2
, BUTTON3
; NOBUTTON
, BUTTON1
, BUTTON2
or BUTTON3
if support for the extended mouse buttons is disabled
by Javapublic boolean isPopupTrigger()
Note: Popup menus are triggered differently on different systems. Therefore, isPopupTrigger
should be checked in both mousePressed
and mouseReleased
for proper cross-platform functionality.
public static String getMouseModifiersText(int modifiers)
String
instance 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 the InputEvent.ALT_MASK
and InputEvent.BUTTON2_MASK
have equal values, so the "Alt" string is returned for both modifiers. Likewise, the InputEvent.META_MASK
and InputEvent.BUTTON3_MASK
have equal values, so the "Meta" string is returned for both modifiers.
Note that passing negative parameter is incorrect, and will cause the returning an unspecified string. Zero parameter means that no modifiers were passed and will cause the returning an empty string.
modifiers
- A modifier mask describing the modifier keys and mouse buttons that were down during the eventpublic String paramString()
paramString
in class ComponentEvent
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/event/MouseEvent.html