MouseEvent (Java 2 Platform SE 5.0) (original) (raw)

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 everyMouseListener 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 everyMouseMotionListener orMouseMotionAdapter object which is registered to receive mouse motion events using the component'saddMouseMotionListener 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, useInputEvent.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 bybutton 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, theMOUSE_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 theComponent even if the mouse position is outside the bounds of theGraphicsConfiguration 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

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

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

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

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. 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. This method throws anIllegalArgumentException 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 orBUTTON3.

Throws:

[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang") - if an invalid button value is passed in

[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang") - if source is null

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. This method throws anIllegalArgumentException 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](../../../java/lang/IllegalArgumentException.html "class in java.lang") - if source is null

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.

Returns:

one of the following constants:NOBUTTON,BUTTON1,BUTTON2 orBUTTON3.

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 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 andInputEvent.BUTTON2_MASK have the same value, so the string "Alt" is returned for both modifiers. Likewise,InputEvent.META_MASK andInputEvent.BUTTON3_MASK have the same value, so the string "Meta" is returned for both modifiers.

Parameters:

modifiers - a modifier mask describing the modifier keys and mouse buttons that were down during the event

Returns:

string a text description of the combination of modifier keys and mouse buttons that were down during the event

Since:

1.4

See Also:

InputEvent.getModifiersExText(int)

paramString

public String paramString()

Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.

Overrides:

[paramString](../../../java/awt/event/ComponentEvent.html#paramString%28%29) in class [ComponentEvent](../../../java/awt/event/ComponentEvent.html "class in java.awt.event")

Returns:

a string identifying the event and its attributes

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 2004, 2010 Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.