java.awt.event
Class MouseEvent

java.lang.Object
  extended by java.util.EventObject
      extended by java.awt.AWTEvent
          extended by java.awt.event.ComponentEvent
              extended by java.awt.event.InputEvent
                  extended by java.awt.event.MouseEvent
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MenuDragMouseEvent, MouseWheelEvent

public class MouseEvent
extends InputEvent

This event is generated for a mouse event. There are three main categories of mouse events: Regular events include pressing, releasing, and clicking buttons, as well as moving over the boundary of the unobscured portion of a component. Motion events include movement and dragging. Wheel events are covered separately by the subclass MouseWheelEvent.

A mouse event is tied to the unobstructed visible component that the mouse cursor was over at the time of the action. The button that was most recently pressed is the only one that shows up in getModifiers, and is returned by getButton, while all buttons that are down show up in getModifiersEx.

Drag events may be cut short if native drag-and-drop operations steal the event. Likewise, if a mouse drag exceeds the bounds of a window or virtual device, some platforms may clip the path to fit in the bounds of the component.

Since:
1.1
See Also:
MouseAdapter, MouseListener, MouseMotionAdapter, MouseMotionListener, MouseWheelListener, Serialized Form

Field Summary
static int BUTTON1
          This indicates that button 1 changed state.
static int BUTTON2
          This indicates that button 2 changed state.
static int BUTTON3
          This indicates that button 3 changed state.
static int MOUSE_CLICKED
          This event id indicates that the mouse was clicked.
static int MOUSE_DRAGGED
          This event id indicates that the mouse was dragged over a component.
static int MOUSE_ENTERED
          This event id indicates that the mouse entered a component.
static int MOUSE_EXITED
          This event id indicates that the mouse exited a component.
static int MOUSE_FIRST
          This is the first id in the range of event ids used by this class.
static int MOUSE_LAST
          This is the last id in the range of event ids used by this class.
static int MOUSE_MOVED
          This event id indicates that the mouse was moved.
static int MOUSE_PRESSED
          This event id indicates that the mouse was pressed.
static int MOUSE_RELEASED
          This event id indicates that the mouse was released.
static int MOUSE_WHEEL
          This event id indicates that the mouse wheel was rotated.
static int NOBUTTON
          This indicates that no button changed state.
 
Fields inherited from 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 inherited from class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
 
Fields inherited from 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 inherited from class java.util.EventObject
source
 
Constructor Summary
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
          Initializes a new instance of MouseEvent with the specified information.
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
          Initializes a new instance of MouseEvent with the specified information.
MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int absX, int absY, int clickCount, boolean popupTrigger, int button)
          Creates a new MouseEvent.
 
Method Summary
 int getButton()
          Returns which button, if any, was the most recent to change state.
 int getClickCount()
          This method returns the number of mouse clicks associated with this event.
 Point getLocationOnScreen()
           
static String getMouseModifiersText(int modifiers)
          Returns a string describing the modifiers, such as "Shift" or "Ctrl+Button1".
 Point getPoint()
          This method returns a Point for the x,y position of the mouse pointer.
 int getX()
          This method returns the X coordinate of the mouse position.
 int getXOnScreen()
           
 int getY()
          This method returns the Y coordinate of the mouse position.
 int getYOnScreen()
           
 boolean isPopupTrigger()
          This method tests whether or not the event is a popup menu trigger.
 String paramString()
          Returns a string identifying this event.
 void translatePoint(int dx, int dy)
          Translates the event coordinates by the specified x and y offsets.
 
Methods inherited from class java.awt.event.InputEvent
consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
 
Methods inherited from class java.awt.event.ComponentEvent
getComponent
 
Methods inherited from class java.awt.AWTEvent
getID, setSource, toString
 
Methods inherited from class java.util.EventObject
getSource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MOUSE_FIRST

public static final int MOUSE_FIRST
This is the first id in the range of event ids used by this class.

See Also:
Constant Field Values

MOUSE_LAST

public static final int MOUSE_LAST
This is the last id in the range of event ids used by this class.

See Also:
Constant Field Values

MOUSE_CLICKED

public static final int MOUSE_CLICKED
This event id indicates that the mouse was clicked.

See Also:
Constant Field Values

MOUSE_PRESSED

public static final int MOUSE_PRESSED
This event id indicates that the mouse was pressed.

See Also:
Constant Field Values

MOUSE_RELEASED

public static final int MOUSE_RELEASED
This event id indicates that the mouse was released.

See Also:
Constant Field Values

MOUSE_MOVED

public static final int MOUSE_MOVED
This event id indicates that the mouse was moved.

See Also:
Constant Field Values

MOUSE_ENTERED

public static final int MOUSE_ENTERED
This event id indicates that the mouse entered a component.

See Also:
Constant Field Values

MOUSE_EXITED

public static final int MOUSE_EXITED
This event id indicates that the mouse exited a component.

See Also:
Constant Field Values

NOBUTTON

public static final int NOBUTTON
This indicates that no button changed state.

Since:
1.4
See Also:
getButton(), Constant Field Values

BUTTON1

public static final int BUTTON1
This indicates that button 1 changed state.

Since:
1.4
See Also:
getButton(), Constant Field Values

BUTTON2

public static final int BUTTON2
This indicates that button 2 changed state.

Since:
1.4
See Also:
getButton(), Constant Field Values

BUTTON3

public static final int BUTTON3
This indicates that button 3 changed state.

Since:
1.4
See Also:
getButton(), Constant Field Values

MOUSE_DRAGGED

public static final int MOUSE_DRAGGED
This event id indicates that the mouse was dragged over a component.

See Also:
Constant Field Values

MOUSE_WHEEL

public static final int MOUSE_WHEEL
This event id indicates that the mouse wheel was rotated.

Since:
1.4
See Also:
Constant Field Values
Constructor Detail

MouseEvent

public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger,
                  int button)
Initializes a new instance of MouseEvent with the specified information. Note that an invalid id leads to unspecified results.

Parameters:
source - the source of the event
id - the event id
when - the timestamp of when the event occurred
modifiers - the modifier keys during the event, in old or new style
x - the X coordinate of the mouse point
y - the Y coordinate of the mouse point
clickCount - the number of mouse clicks for this event
popupTrigger - true if this event triggers a popup menu
button - the most recent mouse button to change state
Throws:
IllegalArgumentException - if source is null or button is invalid
Since:
1.4

MouseEvent

public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger)
Initializes a new instance of MouseEvent with the specified information. Note that an invalid id leads to unspecified results.

Parameters:
source - the source of the event
id - the event id
when - the timestamp of when the event occurred
modifiers - the modifier keys during the event, in old or new style
x - the X coordinate of the mouse point
y - the Y coordinate of the mouse point
clickCount - the number of mouse clicks for this event
popupTrigger - true if this event triggers a popup menu
Throws:
IllegalArgumentException - if source is null

MouseEvent

public MouseEvent(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int absX,
                  int absY,
                  int clickCount,
                  boolean popupTrigger,
                  int button)
Creates a new MouseEvent. This is like the other constructors and adds specific absolute coordinates.

Parameters:
source - the source of the event
id - the event id
when - the timestamp of when the event occurred
modifiers - the modifier keys during the event, in old or new style
x - the X coordinate of the mouse point
y - the Y coordinate of the mouse point
absX - the absolute X screen coordinate of this event
absY - the absolute Y screen coordinate of this event
clickCount - the number of mouse clicks for this event
popupTrigger - true if this event triggers a popup menu
button - the most recent mouse button to change state
Throws:
IllegalArgumentException - if source is null or button is invalid
Since:
1.6
Method Detail

getX

public int getX()
This method returns the X coordinate of the mouse position. This is relative to the source component.

Returns:
the x coordinate

getY

public int getY()
This method returns the Y coordinate of the mouse position. This is relative to the source component.

Returns:
the y coordinate

getLocationOnScreen

public Point getLocationOnScreen()
Since:
1.6

getXOnScreen

public int getXOnScreen()
Since:
1.6

getYOnScreen

public int getYOnScreen()
Since:
1.6

getPoint

public Point getPoint()
This method returns a Point for the x,y position of the mouse pointer. This is relative to the source component.

Returns:
a Point for the event position

translatePoint

public void translatePoint(int dx,
                           int dy)
Translates the event coordinates by the specified x and y offsets.

Parameters:
dx - the value to add to the X coordinate of this event
dy - the value to add to the Y coordiante of this event

getClickCount

public int getClickCount()
This method returns the number of mouse clicks associated with this event.

Returns:
the number of mouse clicks for this event

getButton

public int getButton()
Returns which button, if any, was the most recent to change state. This will be one of NOBUTTON, BUTTON1, BUTTON2, or BUTTON3.

Returns:
the button that changed state
Since:
1.4

isPopupTrigger

public boolean isPopupTrigger()
This method tests whether or not the event is a popup menu trigger. This should be checked in both MousePressed and MouseReleased to be cross-platform compatible, as different systems have different popup triggers.

Returns:
true if the event is a popup menu trigger

getMouseModifiersText

public static String getMouseModifiersText(int modifiers)
Returns a string describing the modifiers, such as "Shift" or "Ctrl+Button1". XXX Sun claims this can be localized via the awt.properties file - how do we implement that?

Parameters:
modifiers - the old-style modifiers to convert to text
Returns:
a string representation of the modifiers in this bitmask

paramString

public String paramString()
Returns a string identifying this event. This is formatted as the field name of the id type, followed by the (x,y) point, the most recent button changed, modifiers (if any), extModifiers (if any), and clickCount.

Overrides:
paramString in class ComponentEvent
Returns:
a string identifying this event