Class MouseEvent
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
MenuDragMouseEvent
,MouseWheelEvent
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:
- 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 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:
- In a multi-screen environment without a virtual device:
The reported coordinates for mouse drag events are clipped to fit within the bounds of theGraphicsConfiguration
associated with theComponent
. - 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 theComponent
.
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).
- Since:
- 1.1
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Indicates mouse button #1; used bygetButton()
.static final int
Indicates mouse button #2; used bygetButton()
.static final int
Indicates mouse button #3; used bygetButton()
.static final int
The "mouse clicked" event.static final int
The "mouse dragged" event.static final int
The "mouse entered" event.static final int
The "mouse exited" event.static final int
The first number in the range of ids used for mouse events.static final int
The last number in the range of ids used for mouse events.static final int
The "mouse moved" event.static final int
The "mouse pressed" event.static final int
The "mouse released" event.static final int
The "mouse wheel" event.static final int
Indicates no mouse buttons; used bygetButton()
.Fields declared in 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 declared in class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
Fields declared in 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 declared in class java.util.EventObject
source
-
Constructor Summary
ConstructorDescriptionMouseEvent
(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger) Constructs aMouseEvent
object with the specified source component, type, modifiers, coordinates, click count, and popupTrigger flag.MouseEvent
(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button) Constructs aMouseEvent
object with the specified source component, type, time, modifiers, coordinates, click count, popupTrigger flag, and button number.MouseEvent
(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, int button) Constructs aMouseEvent
object with the specified source component, type, time, modifiers, coordinates, absolute coordinates, click count, popupTrigger flag, and button number. -
Method Summary
Modifier and TypeMethodDescriptionint
Returns which, if any, of the mouse buttons has changed state.int
Returns the number of mouse clicks associated with this event.Returns the absolute x, y position of the event.static String
getMouseModifiersText
(int modifiers) Returns aString
instance describing the modifier keys and mouse buttons that were down during the event, such as "Shift", or "Ctrl+Shift".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
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
Returns the absolute vertical y position of the event.boolean
Returns whether or not this mouse event is the popup menu trigger event for the platform.Returns a parameter string identifying this event.void
translatePoint
(int x, int y) Translates the event's coordinates to a new position by adding specifiedx
(horizontal) andy
(vertical) offsets.Methods declared in class java.awt.event.InputEvent
consume, getMaskForButton, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
Methods declared in class java.awt.event.ComponentEvent
getComponent
Methods declared in class java.util.EventObject
getSource
-
Field Details
-
MOUSE_FIRST
public static final int MOUSE_FIRSTThe first number in the range of ids used for mouse events.- See Also:
-
MOUSE_LAST
public static final int MOUSE_LASTThe last number in the range of ids used for mouse events.- See Also:
-
MOUSE_CLICKED
public static final int MOUSE_CLICKEDThe "mouse clicked" event. ThisMouseEvent
occurs when a mouse button is pressed and released.- See Also:
-
MOUSE_PRESSED
public static final int MOUSE_PRESSEDThe "mouse pressed" event. ThisMouseEvent
occurs when a mouse button is pushed down.- See Also:
-
MOUSE_RELEASED
public static final int MOUSE_RELEASEDThe "mouse released" event. ThisMouseEvent
occurs when a mouse button is let up.- See Also:
-
MOUSE_MOVED
public static final int MOUSE_MOVEDThe "mouse moved" event. ThisMouseEvent
occurs when the mouse position changes.- See Also:
-
MOUSE_ENTERED
public static final int MOUSE_ENTEREDThe "mouse entered" event. ThisMouseEvent
occurs when the mouse cursor enters the unobscured part of component's geometry.- See Also:
-
MOUSE_EXITED
public static final int MOUSE_EXITEDThe "mouse exited" event. ThisMouseEvent
occurs when the mouse cursor exits the unobscured part of component's geometry.- See Also:
-
MOUSE_DRAGGED
public static final int MOUSE_DRAGGEDThe "mouse dragged" event. ThisMouseEvent
occurs when the mouse position changes while a mouse button is pressed.- See Also:
-
MOUSE_WHEEL
public static final int MOUSE_WHEELThe "mouse wheel" event. This is the onlyMouseWheelEvent
. It occurs when a mouse equipped with a wheel has its wheel rotated.- Since:
- 1.4
- See Also:
-
NOBUTTON
public static final int NOBUTTONIndicates no mouse buttons; used bygetButton()
.- Since:
- 1.4
- See Also:
-
BUTTON1
public static final int BUTTON1Indicates mouse button #1; used bygetButton()
.- Since:
- 1.4
- See Also:
-
BUTTON2
public static final int BUTTON2Indicates mouse button #2; used bygetButton()
.- Since:
- 1.4
- See Also:
-
BUTTON3
public static final int BUTTON3Indicates mouse button #3; used bygetButton()
.- Since:
- 1.4
- See Also:
-
-
Constructor Details
-
MouseEvent
public MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button) Constructs aMouseEvent
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 invocationMouseEvent(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 anIllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheComponent
that originated the eventid
- An integer indicating the type of event. For information on allowable values, see the class description forMouseEvent
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 theInputEvent.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 equalstrue
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:- If support for the extended mouse buttons is
disabled
by Java then it is allowed to createMouseEvent
objects only with the standard buttons:NOBUTTON
,BUTTON1
,BUTTON2
, andBUTTON3
. - If support for the extended mouse buttons is
enabled
by Java then it is allowed to createMouseEvent
objects with the standard buttons. In case the support for extended mouse buttons isenabled
by Java, then in addition to the standard buttons,MouseEvent
objects can be created using buttons from the range starting from 4 toMouseInfo.getNumberOfButtons()
if the mouse has more than three buttons.
- If support for the extended mouse buttons is
- Throws:
IllegalArgumentException
- ifbutton
is less than zeroIllegalArgumentException
- ifsource
is nullIllegalArgumentException
- ifbutton
is greater than BUTTON3 and the support for extended mouse buttons isdisabled
by JavaIllegalArgumentException
- ifbutton
is greater than thecurrent number of buttons
and the support for extended mouse buttons isenabled
by JavaIllegalArgumentException
- if an invalidbutton
value is passed inIllegalArgumentException
- ifsource
is null- Since:
- 1.4
- See Also:
-
MouseEvent
public MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger) Constructs aMouseEvent
object with the specified source component, type, modifiers, coordinates, click count, and popupTrigger flag. An invocation of the formMouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)
behaves in exactly the same way as the invocationMouseEvent(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 anIllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheComponent
that originated the eventid
- An integer indicating the type of event. For information on allowable values, see the class description forMouseEvent
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 theInputEvent.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 equalstrue
if this event is a trigger for a popup menu- Throws:
IllegalArgumentException
- ifsource
is null- See Also:
-
MouseEvent
public MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, int button) Constructs aMouseEvent
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
ifsource
isnull
.- Parameters:
source
- TheComponent
that originated the eventid
- An integer indicating the type of event. For information on allowable values, see the class description forMouseEvent
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 theInputEvent.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 equalstrue
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:- If support for the extended mouse buttons is
disabled
by Java then it is allowed to createMouseEvent
objects only with the standard buttons:NOBUTTON
,BUTTON1
,BUTTON2
, andBUTTON3
. - If support for the extended mouse buttons is
enabled
by Java then it is allowed to createMouseEvent
objects with the standard buttons. In case the support for extended mouse buttons isenabled
by Java, then in addition to the standard buttons,MouseEvent
objects can be created using buttons from the range starting from 4 toMouseInfo.getNumberOfButtons()
if the mouse has more than three buttons.
- If support for the extended mouse buttons is
- Throws:
IllegalArgumentException
- ifbutton
is less than zeroIllegalArgumentException
- ifsource
is nullIllegalArgumentException
- ifbutton
is greater than BUTTON3 and the support for extended mouse buttons isdisabled
by JavaIllegalArgumentException
- ifbutton
is greater than thecurrent number of buttons
and the support for extended mouse buttons isenabled
by JavaIllegalArgumentException
- if an invalidbutton
value is passed inIllegalArgumentException
- ifsource
is null- Since:
- 1.6
- See Also:
-
-
Method Details
-
getLocationOnScreen
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.- Returns:
- a
Point
object containing the absolute x and y coordinates. - Since:
- 1.6
- See Also:
-
getXOnScreen
public int getXOnScreen()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:
- x an integer indicating absolute horizontal position.
- Since:
- 1.6
- See Also:
-
getYOnScreen
public int getYOnScreen()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:
- y an integer indicating absolute vertical position.
- Since:
- 1.6
- See Also:
-
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
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 specifiedx
(horizontal) andy
(vertical) offsets.- Parameters:
x
- the horizontal x value to add to the current x coordinate positiony
- 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. The returned value is ranged from 0 to theMouseInfo.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:- 0 (
NOBUTTON
) - 1 (
BUTTON1
) - 2 (
BUTTON2
) - 3 (
BUTTON3
)
BUTTON3
have no constant identifier. So if a mouse with five buttons is installed, this method may return the following values:- 0 (
NOBUTTON
) - 1 (
BUTTON1
) - 2 (
BUTTON2
) - 3 (
BUTTON3
) - 4
- 5
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 exceptNOBUTTON
,BUTTON1
,BUTTON2
,BUTTON3
.- Returns:
- one of the values from 0 to
MouseInfo.getNumberOfButtons()
if support for the extended mouse buttons isenabled
by Java. That range includesNOBUTTON
,BUTTON1
,BUTTON2
,BUTTON3
;
NOBUTTON
,BUTTON1
,BUTTON2
orBUTTON3
if support for the extended mouse buttons isdisabled
by Java - Since:
- 1.4
- See Also:
-
-
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 bothmousePressed
andmouseReleased
for proper cross-platform functionality.- Returns:
- boolean, true if this event is the popup menu trigger for this platform
-
getMouseModifiersText
Returns aString
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 theawt.properties
file.Note that the
InputEvent.ALT_MASK
andInputEvent.BUTTON2_MASK
have equal values, so the "Alt" string is returned for both modifiers. Likewise, theInputEvent.META_MASK
andInputEvent.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.
- Parameters:
modifiers
- A modifier mask describing the modifier keys and mouse buttons that were down during the event- Returns:
- string string text description of the combination of modifier keys and mouse buttons that were down during the event
- Since:
- 1.4
- See Also:
-
paramString
Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.- Overrides:
paramString
in classComponentEvent
- Returns:
- a string identifying the event and its attributes
-