Save This Page
Home » openjdk-7 » java » awt » event » [javadoc | source]
java.awt.event
public class: MouseEvent [javadoc | source]
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

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 {@code EventListener} to the component (MouseListener or MouseMotionListener ), or by invoking Component#enableEvents(long) with the appropriate mask parameter ({@code AWTEvent.MOUSE_EVENT_MASK} or {@code 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 {@code MouseListener} has been added to a component, or {@code enableEvents(AWTEvent.MOUSE_EVENT_MASK)} has been invoked, then all the events defined by {@code MouseListener} are dispatched to the component. On the other hand, if a {@code MouseMotionListener} has not been added and {@code enableEvents} has not been invoked with {@code 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 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.

Some extra mouse buttons are added to extend the standard set of buttons represented by the following constants:{@code BUTTON1}, {@code BUTTON2}, and {@code BUTTON3}. Extra buttons have no assigned {@code BUTTONx} constants as well as their button masks have no assigned {@code 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:

An unspecified behavior will be caused if the {@code id} parameter of any particular {@code MouseEvent} instance is not in the range from {@code MOUSE_FIRST} to {@code MOUSE_LAST}-1 ({@code MOUSE_WHEEL} is not acceptable).

Field Summary
public static final  int MOUSE_FIRST    The first number in the range of ids used for mouse events. 
public static final  int MOUSE_LAST    The last number in the range of ids used for mouse events. 
public static final  int MOUSE_CLICKED    The "mouse clicked" event. This MouseEvent occurs when a mouse button is pressed and released. 
public static final  int MOUSE_PRESSED    The "mouse pressed" event. This MouseEvent occurs when a mouse button is pushed down. 
public static final  int MOUSE_RELEASED    The "mouse released" event. This MouseEvent occurs when a mouse button is let up. 
public static final  int MOUSE_MOVED    The "mouse moved" event. This MouseEvent occurs when the mouse position changes. 
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. 
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. 
public static final  int MOUSE_DRAGGED    The "mouse dragged" event. This MouseEvent occurs when the mouse position changes while a mouse button is pressed. 
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 -
 
public static final  int NOBUTTON    Indicates no mouse buttons; used by #getButton .
    since: 1.4 -
 
public static final  int BUTTON1    Indicates mouse button #1; used by #getButton .
    since: 1.4 -
 
public static final  int BUTTON2    Indicates mouse button #2; used by #getButton .
    since: 1.4 -
 
public static final  int BUTTON3    Indicates mouse button #3; used by #getButton .
    since: 1.4 -
 
 int x    The mouse event's x coordinate. The x value is relative to the component that fired the event. 
 int y    The mouse event's y coordinate. The y value is relative to the component that fired the event. 
 int clickCount    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. 
 int button    Indicates which, if any, of the mouse buttons has changed state. The valid values are ranged from 0 to the value returned by the MouseInfo.getNumberOfButtons() method. This range already includes constants {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2}, and {@code BUTTON3} if these buttons are present. So it is allowed to use these constants too. For example, for a mouse with two buttons this field may contain the following values:
  • 0 ({@code NOBUTTON})
  • 1 ({@code BUTTON1})
  • 2 ({@code BUTTON2})
If a mouse has 5 buttons, this field may contain the following values:
  • 0 ({@code NOBUTTON})
  • 1 ({@code BUTTON1})
  • 2 ({@code BUTTON2})
  • 3 ({@code BUTTON3})
  • 4
  • 5
If support for extended mouse buttons is Toolkit#areExtraMouseButtonsEnabled() disabled by Java then the field may not contain the value larger than {@code BUTTON3}.
    Also see:
    getButton()
    java.awt.Toolkit#areExtraMouseButtonsEnabled()
    serial:
 
 boolean popupTrigger    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. 
Fields inherited from java.awt.event.InputEvent:
SHIFT_MASK,  CTRL_MASK,  META_MASK,  ALT_MASK,  ALT_GRAPH_MASK,  BUTTON1_MASK,  BUTTON2_MASK,  BUTTON3_MASK,  SHIFT_DOWN_MASK,  CTRL_DOWN_MASK,  META_DOWN_MASK,  ALT_DOWN_MASK,  BUTTON1_DOWN_MASK,  BUTTON2_DOWN_MASK,  BUTTON3_DOWN_MASK,  ALT_GRAPH_DOWN_MASK,  FIRST_HIGH_BIT,  JDK_1_3_MODIFIERS,  HIGH_MODIFIERS,  when,  modifiers,  serialVersionUID
Fields inherited from java.awt.event.ComponentEvent:
COMPONENT_FIRST,  COMPONENT_LAST,  COMPONENT_MOVED,  COMPONENT_RESIZED,  COMPONENT_SHOWN,  COMPONENT_HIDDEN
Fields inherited from java.awt.AWTEvent:
id,  consumed,  focusManagerIsDispatching,  isPosted,  COMPONENT_EVENT_MASK,  CONTAINER_EVENT_MASK,  FOCUS_EVENT_MASK,  KEY_EVENT_MASK,  MOUSE_EVENT_MASK,  MOUSE_MOTION_EVENT_MASK,  WINDOW_EVENT_MASK,  ACTION_EVENT_MASK,  ADJUSTMENT_EVENT_MASK,  ITEM_EVENT_MASK,  TEXT_EVENT_MASK,  INPUT_METHOD_EVENT_MASK,  INPUT_METHODS_ENABLED_MASK,  PAINT_EVENT_MASK,  INVOCATION_EVENT_MASK,  HIERARCHY_EVENT_MASK,  HIERARCHY_BOUNDS_EVENT_MASK,  MOUSE_WHEEL_EVENT_MASK,  WINDOW_STATE_EVENT_MASK,  WINDOW_FOCUS_EVENT_MASK,  RESERVED_ID_MAX
Fields inherited from java.util.EventObject:
source
Constructor:
 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, 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.
    Parameters:
    source - The Component that originated the event
    id - 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 recommended
    modifiers - The modifier keys down during event (e.g. shift, ctrl, alt, meta) Passing negative parameter is not recommended. Zero value means that no modifiers were passed. Use either an extended _DOWN_MASK or old _MASK modifiers, however do not mix models in the one event. The extended modifiers are preferred for using
    x - The horizontal x coordinate for the mouse location. It is allowed to pass negative values
    y - The vertical y coordinate for the mouse location. It is allowed to pass negative values
    clickCount - The number of mouse clicks associated with event. Passing negative value is not recommended
    popupTrigger - A boolean that equals {@code true} if this event is a trigger for a popup menu
    Throws:
    IllegalArgumentException - if source is null
    Also see:
    getSource()
    getID()
    getWhen()
    getModifiers()
    getX()
    getY()
    getClickCount()
    isPopupTrigger()
 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, 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.

    Parameters:
    source - The Component that originated the event
    id - 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 recommended
    modifiers - The modifier keys down during event (e.g. shift, ctrl, alt, meta) Passing negative parameter is not recommended. Zero value means that no modifiers were passed. Use either an extended _DOWN_MASK or old _MASK modifiers, however do not mix models in the one event. The extended modifiers are preferred for using
    x - The horizontal x coordinate for the mouse location. It is allowed to pass negative values
    y - The vertical y coordinate for the mouse location. It is allowed to pass negative values
    clickCount - The number of mouse clicks associated with event. Passing negative value is not recommended
    popupTrigger - A boolean that equals {@code true} if this event is a trigger for a popup menu
    button - 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 create {@code MouseEvent} objects only with the standard buttons: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2}, and {@code BUTTON3}.
    • If support for the extended mouse buttons is enabled by Java then it is allowed to create {@code 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, {@code MouseEvent} objects can be created using buttons from the range starting from 4 to MouseInfo.getNumberOfButtons() if the mouse has more than three buttons.

    Throws:
    IllegalArgumentException - if {@code button} is less then zero
    IllegalArgumentException - if source is null
    IllegalArgumentException - if {@code button} is greater then BUTTON3 and the support for extended mouse buttons is disabled by Java
    IllegalArgumentException - if {@code button} is greater then the current number of buttons and the support for extended mouse buttons is enabled by Java
    IllegalArgumentException - if an invalid button value is passed in
    IllegalArgumentException - if source is null
    Also see:
    getSource()
    getID()
    getWhen()
    getModifiers()
    getX()
    getY()
    getClickCount()
    isPopupTrigger()
    getButton()
    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, 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.

    Parameters:
    source - The Component that originated the event
    id - 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 recommended
    modifiers - The modifier keys down during event (e.g. shift, ctrl, alt, meta) Passing negative parameter is not recommended. Zero value means that no modifiers were passed. Use either an extended _DOWN_MASK or old _MASK modifiers, however do not mix models in the one event. The extended modifiers are preferred for using
    x - The horizontal x coordinate for the mouse location. It is allowed to pass negative values
    y - The vertical y coordinate for the mouse location. It is allowed to pass negative values
    xAbs - The absolute horizontal x coordinate for the mouse location It is allowed to pass negative values
    yAbs - The absolute vertical y coordinate for the mouse location It is allowed to pass negative values
    clickCount - The number of mouse clicks associated with event. Passing negative value is not recommended
    popupTrigger - A boolean that equals {@code true} if this event is a trigger for a popup menu
    button - 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 create {@code MouseEvent} objects only with the standard buttons: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2}, and {@code BUTTON3}.
    • If support for the extended mouse buttons is enabled by Java then it is allowed to create {@code 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, {@code MouseEvent} objects can be created using buttons from the range starting from 4 to MouseInfo.getNumberOfButtons() if the mouse has more than three buttons.

    Throws:
    IllegalArgumentException - if {@code button} is less then zero
    IllegalArgumentException - if source is null
    IllegalArgumentException - if {@code button} is greater then BUTTON3 and the support for extended mouse buttons is disabled by Java
    IllegalArgumentException - if {@code button} is greater then the current number of buttons and the support for extended mouse buttons is enabled by Java
    IllegalArgumentException - if an invalid button value is passed in
    IllegalArgumentException - if source is null
    Also see:
    getSource()
    getID()
    getWhen()
    getModifiers()
    getX()
    getY()
    getXOnScreen()
    getYOnScreen()
    getClickCount()
    isPopupTrigger()
    getButton()
    button
    Toolkit#areExtraMouseButtonsEnabled()
    java.awt.MouseInfo#getNumberOfButtons()
    InputEvent#getMaskForButton(int)
    since: 1.6 -
Method from java.awt.event.MouseEvent Summary:
getButton,   getClickCount,   getLocationOnScreen,   getModifiersEx,   getMouseModifiersText,   getPoint,   getX,   getXOnScreen,   getY,   getYOnScreen,   isPopupTrigger,   paramString,   translatePoint
Methods from java.awt.event.InputEvent:
consume,   getMaskForButton,   getModifiers,   getModifiersEx,   getModifiersExText,   getWhen,   isAltDown,   isAltGraphDown,   isConsumed,   isControlDown,   isMetaDown,   isShiftDown
Methods from java.awt.event.ComponentEvent:
getComponent,   paramString
Methods from java.awt.AWTEvent:
consume,   convertToOld,   copyPrivateDataInto,   dispatched,   getAccessControlContext,   getID,   isConsumed,   paramString,   setSource,   toString
Methods from java.util.EventObject:
getSource,   toString
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.awt.event.MouseEvent Detail:
 public int getButton() 
    Returns which, if any, of the mouse buttons has changed state. The returned value is ranged from 0 to the MouseInfo.getNumberOfButtons() value. The returned value includes at least the following constants:
    • {@code NOBUTTON}
    • {@code BUTTON1}
    • {@code BUTTON2}
    • {@code BUTTON3}
    It is allowed to use those constants to compare with the returned button number in the application. For example,
    if (anEvent.getButton() == MouseEvent.BUTTON1) {
    
    In particular, for a mouse with one, two, or three buttons this method may return the following values:
    • 0 ({@code NOBUTTON})
    • 1 ({@code BUTTON1})
    • 2 ({@code BUTTON2})
    • 3 ({@code BUTTON3})
    Button numbers greater then {@code BUTTON3} have no constant identifier. So if a mouse with five buttons is installed, this method may return the following values:
    • 0 ({@code NOBUTTON})
    • 1 ({@code BUTTON1})
    • 2 ({@code BUTTON2})
    • 3 ({@code 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 except {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2}, {@code BUTTON3}.

 public int getClickCount() 
    Returns the number of mouse clicks associated with this event.
 public Point 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.
 public int getModifiersEx() 
    {@inheritDoc}
 public static String getMouseModifiersText(int modifiers) 
    Returns a 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.

 public Point getPoint() 
    Returns the x,y position of the event relative to the source component.
 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. 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.
 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. 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.
 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.

 public String paramString() 
    Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.
 public synchronized  void translatePoint(int x,
    int y) 
    Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.