MouseEvent JDK 1.6)

Description

public class MouseEvent

An event which indicates that a mouse action occurred in a component.

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 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 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 MouseEvent.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.

See also: MouseAdapter MouseListener MouseMotionAdapter MouseMotionListener MouseWheelListener Tutorial: Writing a Mouse Listener Tutorial: Writing a Mouse Motion Listener

Constructors

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. 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.
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
Throws:
- IllegalArgumentException - if source is null

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. 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.
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 an invalid button value is passed in
- IllegalArgumentException - if source is null
Since: 1.4

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 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.
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
- 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.
Throws:
- IllegalArgumentException - if an invalid button value is passed in
- IllegalArgumentException - if source is null
Since: 1.6

Methods

Hide/Show inherited methods

public void consume () [Inherited From InputEvent]

Consumes this event so that it will not be processed in the default manner by the source which originated it.

public int getButton ()

Returns which, if any, of the mouse buttons has changed state.

Returns which, if any, of the mouse buttons has changed state.
Returns: one of the following constants: NOBUTTON, BUTTON1, BUTTON2 or BUTTON3.
Since: 1.4

public int getClickCount ()

Returns the number of mouse clicks associated with this event.

public Component getComponent () [Inherited From ComponentEvent]

Returns the originator of the event.

Returns the originator of the event.
Returns: the Component object that originated the event, or null if the object is not a Component.

public int getID () [Inherited From AWTEvent]

Returns the event type.

public Point getLocationOnScreen ()

Returns the absolute x, y position of the 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.
Returns: a Point object containing the absolute x and y coordinates.
Since: 1.6
See Also: GraphicsConfiguration,

public int getModifiers () [Inherited From InputEvent]

Returns the modifier mask for this event.

public int getModifiersEx () [Inherited From InputEvent]

Returns the extended modifier mask for this event.

Returns the extended modifier mask for this event. Extended modifiers represent the state of all modal keys, such as ALT, CTRL, META, and the mouse buttons just after the event occurred

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:

    MOUSE_PRESSED:  BUTTON1_DOWN_MASK
    MOUSE_PRESSED:  BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK
    MOUSE_RELEASED: BUTTON2_DOWN_MASK
    MOUSE_CLICKED:  BUTTON2_DOWN_MASK
    MOUSE_RELEASED: 
    MOUSE_CLICKED:

It is not recommended to compare the return value of this method using == because new modifiers can be added in the future. For example, the appropriate way to check that SHIFT and BUTTON1 are down, but CTRL is up is demonstrated by the following code:

    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
    int offmask = CTRL_DOWN_MASK;
    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
        ...
    }

The above code will work even if new modifiers are added.
Since: 1.4

publicstatic String getModifiersExText (int modifiers) [Inherited From InputEvent]

Returns a String describing the extended modifier keys and mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".

publicstatic String getMouseModifiersText (int modifiers)

Returns a String describing the modifier keys and mouse buttons that were down during the event, such as "Shift", or "Ctrl+Shift".

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.
Returns: string a text description of the combination of modifier keys and mouse buttons that were down during the event
Parameters:
- modifiers - a modifier mask describing the modifier keys and mouse buttons that were down during the event
Since: 1.4
See Also: InputEvent.getModifiersExText(int),

public Point getPoint ()

Returns the x,y position of the event relative to the source component.

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

public Object getSource () [Inherited From EventObject]

The object on which the Event initially occurred.

public long getWhen () [Inherited From InputEvent]

Returns the timestamp of when this event occurred.

public int getX ()

Returns the horizontal x position of the event relative to the source component.

public int getXOnScreen ()

Returns the absolute horizontal x position of the event.

public int getY ()

Returns the vertical y position of the event relative to the source component.

public int getYOnScreen ()

Returns the absolute vertical y position of the event.

public boolean isAltDown () [Inherited From InputEvent]

Returns whether or not the Alt modifier is down on this event.

public boolean isAltGraphDown () [Inherited From InputEvent]

Returns whether or not the AltGraph modifier is down on this event.

public boolean isConsumed () [Inherited From InputEvent]

Returns whether or not this event has been consumed.

public boolean isControlDown () [Inherited From InputEvent]

Returns whether or not the Control modifier is down on this event.

public boolean isMetaDown () [Inherited From InputEvent]

Returns whether or not the Meta modifier is down on this event.

public boolean isPopupTrigger ()

Returns whether or not this mouse event is the popup menu trigger event for the platform.

public boolean isShiftDown () [Inherited From InputEvent]

Returns whether or not the Shift modifier is down on this event.

public String paramString () [Overrides ComponentEvent]

Returns a parameter string identifying this event.

public void setSource (Object newSource) [Inherited From AWTEvent]

Retargets an event to a new source.

public String toString () [Inherited From AWTEvent]

Returns a String representation of this object.

publicsynchronized void translatePoint (int x, int y)

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

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

Fields

Hide/Show inherited fields

publicfinalstatic long ACTION_EVENT_MASK = "128" [Inherited From AWTEvent]

The event mask for selecting action events.

publicfinalstatic long ADJUSTMENT_EVENT_MASK = "256" [Inherited From AWTEvent]

The event mask for selecting adjustment events.

publicfinalstatic int ALT_DOWN_MASK = "512" [Inherited From InputEvent]

The Alt key extended modifier constant.

publicfinalstatic int ALT_GRAPH_DOWN_MASK = "8192" [Inherited From InputEvent]

The AltGraph key extended modifier constant.

publicfinalstatic int ALT_GRAPH_MASK = "32" [Inherited From InputEvent]

The AltGraph key modifier constant.

publicfinalstatic int ALT_MASK = "8" [Inherited From InputEvent]

The Alt key modifier constant.

pack-private int button

Indicates which, if any, of the mouse buttons has changed state.

Indicates which, if any, of the mouse buttons has changed state.

The only legal values are the following constants:
NOBUTTON,
BUTTON1,
BUTTON2 or
BUTTON3.
Serial:
See Also: MouseEvent.getButton().,

publicfinalstatic int BUTTON1 = "1"

Indicates mouse button #1; used by MouseEvent.getButton().

publicfinalstatic int BUTTON1_DOWN_MASK = "1024" [Inherited From InputEvent]

The Mouse Button1 extended modifier constant.

publicfinalstatic int BUTTON1_MASK = "16" [Inherited From InputEvent]

The Mouse Button1 modifier constant.

publicfinalstatic int BUTTON2 = "2"

Indicates mouse button #2; used by MouseEvent.getButton().

publicfinalstatic int BUTTON2_DOWN_MASK = "2048" [Inherited From InputEvent]

The Mouse Button2 extended modifier constant.

publicfinalstatic int BUTTON2_MASK = "8" [Inherited From InputEvent]

The Mouse Button2 modifier constant.

publicfinalstatic int BUTTON3 = "3"

Indicates mouse button #3; used by MouseEvent.getButton().

publicfinalstatic int BUTTON3_DOWN_MASK = "4096" [Inherited From InputEvent]

The Mouse Button3 extended modifier constant.

publicfinalstatic int BUTTON3_MASK = "4" [Inherited From InputEvent]

The Mouse Button3 modifier constant.

pack-private int clickCount

Indicates the number of quick consecutive clicks of a mouse button.

Indicates the number of quick consecutive clicks of
a mouse button.
clickCount will be valid for only three mouse events :

MOUSE_CLICKED,
MOUSE_PRESSED and
MOUSE_RELEASED.
For the above, the clickCount will be at least 1.
For all other events the count will be 0.
Serial:
See Also: MouseEvent.getClickCount().,

publicfinalstatic long COMPONENT_EVENT_MASK = "1" [Inherited From AWTEvent]

The event mask for selecting component events.

publicfinalstatic int COMPONENT_FIRST = "100" [Inherited From ComponentEvent]

The first number in the range of ids used for component events.

publicfinalstatic int COMPONENT_HIDDEN = "103" [Inherited From ComponentEvent]

This event indicates that the component was rendered invisible.

publicfinalstatic int COMPONENT_LAST = "103" [Inherited From ComponentEvent]

The last number in the range of ids used for component events.

publicfinalstatic int COMPONENT_MOVED = "100" [Inherited From ComponentEvent]

This event indicates that the component's position changed.

publicfinalstatic int COMPONENT_RESIZED = "101" [Inherited From ComponentEvent]

This event indicates that the component's size changed.

publicfinalstatic int COMPONENT_SHOWN = "102" [Inherited From ComponentEvent]

This event indicates that the component was made visible.

protected boolean consumed [Inherited From AWTEvent]

Controls whether or not the event is sent back down to the peer once the source has processed it - false means it's sent to the peer; true means it's not.

publicfinalstatic long CONTAINER_EVENT_MASK = "2" [Inherited From AWTEvent]

The event mask for selecting container events.

publicfinalstatic int CTRL_DOWN_MASK = "128" [Inherited From InputEvent]

The Control key extended modifier constant.

publicfinalstatic int CTRL_MASK = "2" [Inherited From InputEvent]

The Control key modifier constant.

pack-privatefinalstatic int FIRST_HIGH_BIT = "16384" [Inherited From InputEvent]

publicfinalstatic long FOCUS_EVENT_MASK = "4" [Inherited From AWTEvent]

The event mask for selecting focus events.

publicfinalstatic long HIERARCHY_BOUNDS_EVENT_MASK = "65536" [Inherited From AWTEvent]

The event mask for selecting hierarchy bounds events.

publicfinalstatic long HIERARCHY_EVENT_MASK = "32768" [Inherited From AWTEvent]

The event mask for selecting hierarchy events.

pack-privatefinalstatic int HIGH_MODIFIERS = "-16384" [Inherited From InputEvent]

protected int id [Inherited From AWTEvent]

The event's id.

publicfinalstatic long INPUT_METHOD_EVENT_MASK = "2048" [Inherited From AWTEvent]

The event mask for selecting input method events.

publicfinalstatic long INVOCATION_EVENT_MASK = "16384" [Inherited From AWTEvent]

The event mask for selecting invocation events.

publicfinalstatic long ITEM_EVENT_MASK = "512" [Inherited From AWTEvent]

The event mask for selecting item events.

pack-privatefinalstatic int JDK_1_3_MODIFIERS = "63" [Inherited From InputEvent]

publicfinalstatic long KEY_EVENT_MASK = "8" [Inherited From AWTEvent]

The event mask for selecting key events.

publicfinalstatic int META_DOWN_MASK = "256" [Inherited From InputEvent]

The Meta key extended modifier constant.

publicfinalstatic int META_MASK = "4" [Inherited From InputEvent]

The Meta key modifier constant.

pack-private int modifiers [Inherited From InputEvent]

The state of the modifier mask at the time the input event was fired.

publicfinalstatic int MOUSE_CLICKED = "500"

The "mouse clicked" event.

The "mouse clicked" event. This MouseEvent
occurs when a mouse button is pressed and released.

publicfinalstatic int MOUSE_DRAGGED = "506"

The "mouse dragged" event.

The "mouse dragged" event. This MouseEvent
occurs when the mouse position changes while a mouse button is pressed.

publicfinalstatic int MOUSE_ENTERED = "504"

The "mouse entered" event.

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

publicfinalstatic long MOUSE_EVENT_MASK = "16" [Inherited From AWTEvent]

The event mask for selecting mouse events.

publicfinalstatic int MOUSE_EXITED = "505"

The "mouse exited" event.

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

publicfinalstatic int MOUSE_FIRST = "500"

The first number in the range of ids used for mouse events.

publicfinalstatic int MOUSE_LAST = "507"

The last number in the range of ids used for mouse events.

publicfinalstatic long MOUSE_MOTION_EVENT_MASK = "32" [Inherited From AWTEvent]

The event mask for selecting mouse motion events.

publicfinalstatic int MOUSE_MOVED = "503"

The "mouse moved" event.

The "mouse moved" event. This MouseEvent
occurs when the mouse position changes.

publicfinalstatic int MOUSE_PRESSED = "501"

The "mouse pressed" event.

The "mouse pressed" event. This MouseEvent
occurs when a mouse button is pushed down.

publicfinalstatic int MOUSE_RELEASED = "502"

The "mouse released" event.

The "mouse released" event. This MouseEvent
occurs when a mouse button is let up.

publicfinalstatic int MOUSE_WHEEL = "507"

The "mouse wheel" event.

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

publicfinalstatic long MOUSE_WHEEL_EVENT_MASK = "131072" [Inherited From AWTEvent]

The event mask for selecting mouse wheel events.

publicfinalstatic int NOBUTTON = "0"

Indicates no mouse buttons; used by MouseEvent.getButton().

publicfinalstatic long PAINT_EVENT_MASK = "8192" [Inherited From AWTEvent]

The event mask for selecting paint events.

pack-private boolean popupTrigger

A property used to indicate whether a Popup Menu should appear with a certain gestures.

A property used to indicate whether a Popup Menu
should appear with a certain gestures.
If popupTrigger = false,
no popup menu should appear. If it is true
then a popup menu should appear.
Serial:
See Also: PopupMenu, MouseEvent.isPopupTrigger(),

publicfinalstatic int RESERVED_ID_MAX = "1999" [Inherited From AWTEvent]

The maximum value for reserved AWT event IDs.

pack-privatefinalstatic long serialVersionUID = "-2482525981698309786" [Inherited From InputEvent]

publicfinalstatic int SHIFT_DOWN_MASK = "64" [Inherited From InputEvent]

The Shift key extended modifier constant.

publicfinalstatic int SHIFT_MASK = "1" [Inherited From InputEvent]

The Shift key modifier constant.

protectedtransient Object source [Inherited From EventObject]

The object on which the Event initially occurred.

publicfinalstatic long TEXT_EVENT_MASK = "1024" [Inherited From AWTEvent]

The event mask for selecting text events.

pack-private long when [Inherited From InputEvent]

The input event's Time stamp in UTC format.

publicfinalstatic long WINDOW_EVENT_MASK = "64" [Inherited From AWTEvent]

The event mask for selecting window events.

publicfinalstatic long WINDOW_FOCUS_EVENT_MASK = "524288" [Inherited From AWTEvent]

The event mask for selecting window focus events.

publicfinalstatic long WINDOW_STATE_EVENT_MASK = "262144" [Inherited From AWTEvent]

The event mask for selecting window state events.

pack-private int x

The mouse event's x coordinate.

pack-private int y

The mouse event's y coordinate.