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

  `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`.
  Since:
    1.1
  See Also:
    `MouseAdapter`, `MouseListener`, `MouseMotionAdapter`, `MouseMotionListener`, `MouseWheelListener`, Tutorial: Writing a Mouse Listener, Tutorial: Writing a Mouse Motion Listener, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BUTTON1` Indicates mouse button #1; used by `getButton()`.
    `static int` | `BUTTON2` Indicates mouse button #2; used by `getButton()`.
    `static int` | `BUTTON3` Indicates mouse button #3; used by `getButton()`.
    `static int` | `MOUSE_CLICKED` The "mouse clicked" event.
    `static int` | `MOUSE_DRAGGED` The "mouse dragged" event.
    `static int` | `MOUSE_ENTERED` The "mouse entered" event.
    `static int` | `MOUSE_EXITED` The "mouse exited" event.
    `static int` | `MOUSE_FIRST` The first number in the range of ids used for mouse events.
    `static int` | `MOUSE_LAST` The last number in the range of ids used for mouse events.
    `static int` | `MOUSE_MOVED` The "mouse moved" event.
    `static int` | `MOUSE_PRESSED` The "mouse pressed" event.
    `static int` | `MOUSE_RELEASED` The "mouse released" event.
    `static int` | `MOUSE_WHEEL` The "mouse wheel" event.
    `static int` | `NOBUTTON` Indicates no mouse buttons; used by `getButton()`.

    - ### 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

    Constructors
    Constructor and Description
    `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.
    `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.
    `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.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getButton()` Returns which, if any, of the mouse buttons has changed state.
    `int` | `getClickCount()` Returns the number of mouse clicks associated with this event.
    `Point` | `getLocationOnScreen()` Returns the absolute x, y position of the event.
    `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".
    `Point` | `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` | `getXOnScreen()` 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` | `getYOnScreen()` Returns the absolute vertical y position of the event.
    `boolean` | `isPopupTrigger()` Returns whether or not this mouse event is the popup menu trigger event for the platform.
    `String` | `paramString()` Returns a parameter string identifying this event.
    `void` | `translatePoint(int x, int y)` Translates the event's coordinates to a new position by adding specified `x` (horizontal) and `y` (vertical) 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

      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

  - ### Constructor Detail

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

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

    - #### 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 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

  - ### Method Detail

    - #### getLocationOnScreen

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

    - #### 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:
        `GraphicsConfiguration`

    - #### 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:
        `GraphicsConfiguration`

    - #### 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` or `BUTTON3`.
      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` 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.

      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` in class `ComponentEvent`
      Returns:
        a string identifying the event and its attributes

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

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.