模块 java.desktop
包 java.awt.event

类 MouseEvent

java.lang.Object
java.util.EventObject
java.awt.AWTEvent
java.awt.event.ComponentEvent
java.awt.event.InputEvent
java.awt.event.MouseEvent
所有已实现的接口：
Serializable
已知子类：
MenuDragMouseEvent , MouseWheelEvent
public non-sealed class MouseEvent extends InputEvent
指示组件中发生鼠标操作的事件。当且仅当操作发生时鼠标光标位于组件边界未被遮挡的部分上方时，才认为鼠标操作发生在特定组件中。对于轻量级组件，例如 Swing 的组件，只有在组件上启用了鼠标事件类型后，才会将鼠标事件分派给组件。通过将适当的基于鼠标的 EventListener 添加到组件（MouseListener 或 MouseMotionListener ），或通过使用适当的掩码参数（AWTEvent.MOUSE_EVENT_MASK 或 AWTEvent.MOUSE_MOTION_EVENT_MASK ）调用 Component.enableEvents(long) 来启用鼠标事件类型。如果组件上没有启用鼠标事件类型，则相应的鼠标事件将派发给启用了鼠标事件类型的第一个祖先。

例如，如果 MouseListener 已添加到组件，或 enableEvents(AWTEvent.MOUSE_EVENT_MASK) 已被调用，则 MouseListener 定义的所有事件都将分派到该组件。另一方面，如果尚未添加 MouseMotionListener 且未使用 AWTEvent.MOUSE_MOTION_EVENT_MASK 调用 enableEvents，则不会将鼠标移动事件分派到组件。相反，鼠标运动事件被分派给启用鼠标运动事件的第一个祖先。

此低级事件由组件对象生成，用于：

  • 鼠标事件
    • 按下鼠标按钮
    • 释放鼠标按钮
    • 单击鼠标按钮（按下并释放）
    • 鼠标光标进入组件几何图形未被遮挡的部分
    • 鼠标光标退出组件几何图形的未被遮挡的部分
  • 鼠标运动事件
    • 鼠标被移动
    • 鼠标被拖动

MouseEvent 对象被传递给每个 MouseListener 或 MouseAdapter 对象，这些对象被注册为使用组件的 addMouseListener 方法接收“有趣的”鼠标事件。 （MouseAdapter 对象实现了 MouseListener 接口。）每个这样的监听器对象都会得到一个包含鼠标事件的 MouseEvent。

MouseEvent 对象也被传递给每个 MouseMotionListener 或 MouseMotionAdapter 对象，这些对象被注册为使用组件的 addMouseMotionListener 方法接收鼠标运动事件。 （MouseMotionAdapter 对象实现了 MouseMotionListener 接口。）每个这样的监听器对象都会得到一个包含鼠标移动事件的 MouseEvent。

单击鼠标按钮时，将生成事件并将其发送到已注册的MouseListeners。可以使用 InputEvent.getModifiers() 和 InputEvent.getModifiersEx() 检索模态键的状态。 InputEvent.getModifiers() 返回的按钮掩码仅反映更改状态的按钮，而不是所有按钮的当前状态。 （注意：由于 ALT_MASK/BUTTON2_MASK 和 META_MASK/BUTTON3_MASK 的值重叠，对于涉及修改键的鼠标事件并不总是如此）。要获取所有按钮和修改键的状态，请使用 InputEvent.getModifiersEx() 。状态改变的按钮由 getButton() 返回

例如，如果按下第一个鼠标按钮，事件将按以下顺序发送：


  id       modifiers  button
  MOUSE_PRESSED: BUTTON1_MASK BUTTON1
  MOUSE_RELEASED: BUTTON1_MASK BUTTON1
  MOUSE_CLICKED: BUTTON1_MASK BUTTON1
当按下多个鼠标按钮时，每次按下、释放和单击都会产生一个单独的事件。

例如，如果用户按下按钮 1其次是按钮 2, 然后按相同的顺序释放它们，生成以下事件序列：


  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
如果按钮 2首先发布，BUTTON2_MASK 的 MOUSE_RELEASED /MOUSE_CLICKED 对首先到达，然后是 BUTTON1_MASK 的对。

添加了一些额外的鼠标按钮以扩展由以下常量表示的标准按钮集：BUTTON1、BUTTON2 和 BUTTON3。额外的按钮没有分配 BUTTONx 常量，它们的按钮掩码也没有分配 BUTTONx_DOWN_MASK 常量。然而，从 4 开始的序数可以用作按钮编号（按钮 ID）。通过 getMaskForButton(button) 方法获得的值可用作按钮掩码。

MOUSE_DRAGGED 事件被传递到 Component，其中鼠标按钮被按下，直到鼠标按钮被释放（无论鼠标位置是否在 Component 的范围内）。由于依赖于平台的拖放实现，MOUSE_DRAGGED 事件可能不会在本机拖放操作期间传递。在多屏幕环境中，即使鼠标位置超出与 Component 相关联的 GraphicsConfiguration 的边界，鼠标拖动事件也会传送到 Component 。但是，在这种情况下报告的鼠标拖动事件位置可能与实际鼠标位置不同：

  • 在没有虚拟设备的多屏环境中：
    报告的鼠标拖动事件坐标被裁剪以适应与 Component 关联的 GraphicsConfiguration 的范围。
  • 在具有虚拟设备的多屏环境中：
    报告的鼠标拖动事件坐标被裁剪以适应与 Component 关联的虚拟设备的范围。

如果任何特定 MouseEvent 实例的 id 参数不在从 MOUSE_FIRST 到 MOUSE_LAST -1 的范围内（MOUSE_WHEEL 是不可接受的），将导致未指定的行为。

自从：
1.1
参见：

  • 字段详细信息

    • MOUSE_FIRST

      public static final int MOUSE_FIRST
      用于鼠标事件的 ID 范围内的第一个数字。
      参见：

    • MOUSE_LAST

      public static final int MOUSE_LAST
      用于鼠标事件的 ID 范围内的最后一个数字。
      参见：

    • MOUSE_CLICKED

      public static final int MOUSE_CLICKED
      “鼠标点击”事件。此MouseEvent在按下并释放鼠标按钮时发生。
      参见：

    • MOUSE_PRESSED

      public static final int MOUSE_PRESSED
      “鼠标按下”事件。按下鼠标按钮时会发生此 MouseEvent。
      参见：

    • MOUSE_RELEASED

      public static final int MOUSE_RELEASED
      “松开鼠标”事件。松开鼠标按钮时会发生此 MouseEvent。
      参见：

    • MOUSE_MOVED

      public static final int MOUSE_MOVED
      “鼠标移动”事件。 MouseEvent 发生在鼠标位置改变时。
      参见：

    • MOUSE_ENTERED

      public static final int MOUSE_ENTERED
      “鼠标进入”事件。当鼠标光标进入组件几何图形的未遮挡部分时，会发生此 MouseEvent。
      参见：

    • MOUSE_EXITED

      public static final int MOUSE_EXITED
      “鼠标退出”事件。 MouseEvent 当鼠标光标退出组件几何图形的未遮挡部分时发生。
      参见：

    • MOUSE_DRAGGED

      public static final int MOUSE_DRAGGED
      “鼠标拖动”事件。当按下鼠标按钮时鼠标位置发生变化时，会发生此 MouseEvent。
      参见：

    • MOUSE_WHEEL

      public static final int MOUSE_WHEEL
      “鼠标滚轮”事件。这是唯一的 MouseWheelEvent 。当配备滚轮的鼠标旋转其滚轮时，就会发生这种情况。
      自从：
      1.4
      参见：

    • NOBUTTON

      public static final int NOBUTTON
      表示没有鼠标按钮；由 getButton() 使用。
      自从：
      1.4
      参见：

    • BUTTON1

      public static final int BUTTON1
      表示鼠标按钮 #1；由 getButton() 使用。
      自从：
      1.4
      参见：

    • BUTTON2

      public static final int BUTTON2
      表示鼠标按钮#2；由 getButton() 使用。
      自从：
      1.4
      参见：

    • BUTTON3

      public static final int BUTTON3
      表示鼠标按钮 #3；由 getButton() 使用。
      自从：
      1.4
      参见：

  • 构造方法详细信息

    • MouseEvent

      public MouseEvent(Component  source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
      使用指定的源组件、类型、时间、修饰符、坐标、点击次数、popupTrigger 标志和按钮编号构造一个 MouseEvent 对象。

      创建无效事件（例如使用多个旧 _MASK，或不匹配的修饰符/按钮值）会导致未指定的行为。 MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger, button) 形式的调用与调用 MouseEvent(source, id, when, modifiers, x, y, xAbs, yAbs, clickCount, popupTrigger, button) 的行为完全相同，其中 xAbs 和 yAbs 定义为源在屏幕上的位置加上相对坐标 x 和 y。如果源未显示，xAbs 和 yAbs 将设置为零。如果 source 是 null，此方法将抛出 IllegalArgumentException。

      参数：
      source - 发起事件的 Component
      id - 表示事件类型的整数。有关允许值的信息，请参阅 MouseEvent 的类描述
      when - 一个长整数，表示事件发生的时间。不建议传递负值或零值
      modifiers - 修饰符掩码，描述在事件期间按下的修饰键和鼠标按钮（例如，shift、ctrl、alt 和 meta）。只允许扩展修饰符用作此参数的值（有关扩展修饰符的说明，请参阅 InputEvent.getModifiersEx() 类）。不建议传递负参数。零值意味着没有传递修饰符
      x - 鼠标位置的水平 x 坐标。允许传递负值
      y - 鼠标位置的垂直 y 坐标。允许传递负值
      clickCount - 与事件关联的鼠标点击次数。不建议传递负值
      popupTrigger - 如果此事件是弹出菜单的触发器，则等于 true 的boolean
      button - 一个整数，指示哪个鼠标按钮已更改其状态。以下规则适用于此参数：
      • 如果 Java 对扩展鼠标按钮的支持是 disabled ，则只允许使用标准按钮创建 MouseEvent 对象：NOBUTTON、BUTTON1、BUTTON2 和 BUTTON3。
      • 如果 Java enabled 支持扩展鼠标按钮，则允许使用标准按钮创建 MouseEvent 对象。如果 Java 对扩展鼠标按钮的支持是 enabled ，那么除了标准按钮之外，如果鼠标具有三个以上的按钮，则可以使用从 4 到 MouseInfo.getNumberOfButtons() 范围内的按钮创建 MouseEvent 对象。
      抛出：
      IllegalArgumentException - 如果 button 小于零
      IllegalArgumentException - 如果 source 为空
      IllegalArgumentException - 如果 button 大于 BUTTON3 并且对扩展鼠标按钮的支持是 Java 的 disabled
      IllegalArgumentException - 如果 button 大于 current number of buttons 并且对扩展鼠标按钮的支持是 Java 的 enabled
      IllegalArgumentException - 如果传入了无效的 button 值
      IllegalArgumentException - 如果 source 为空
      自从：
      1.4
      参见：

    • MouseEvent

      public MouseEvent(Component  source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
      使用指定的源组件、类型、修饰符、坐标、点击次数和 popupTrigger 标志构造一个 MouseEvent 对象。 MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger) 形式的调用与调用 MouseEvent(source, id, when, modifiers, x, y, xAbs, yAbs, clickCount, popupTrigger, MouseEvent.NOBUTTON) 的行为完全相同，其中 xAbs 和 yAbs 定义为源在屏幕上的位置加上相对坐标 x 和 y。如果源未显示，xAbs 和 yAbs 将设置为零。如果 source 是 null，此方法将抛出 IllegalArgumentException。
      参数：
      source - 发起事件的 Component
      id - 表示事件类型的整数。有关允许值的信息，请参阅 MouseEvent 的类描述
      when - 一个长整数，表示事件发生的时间。不建议传递负值或零值
      modifiers - 修饰符掩码，描述在事件期间按下的修饰键和鼠标按钮（例如，shift、ctrl、alt 和 meta）。只允许扩展修饰符用作此参数的值（有关扩展修饰符的说明，请参阅 InputEvent.getModifiersEx() 类）。不建议传递负参数。零值意味着没有传递修饰符
      x - 鼠标位置的水平 x 坐标。允许传递负值
      y - 鼠标位置的垂直 y 坐标。允许传递负值
      clickCount - 与事件关联的鼠标点击次数。不建议传递负值
      popupTrigger - 如果此事件是弹出菜单的触发器，则等于 true 的boolean
      抛出：
      IllegalArgumentException - 如果 source 为空
      参见：

    • 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)
      使用指定的源组件、类型、时间、修饰符、坐标、绝对坐标、点击次数、popupTrigger 标志和按钮编号构造一个 MouseEvent 对象。

      创建无效事件（例如使用多个旧 _MASK，或不匹配的修饰符/按钮值）会导致未指定的行为。即使将不一致的相对坐标值和绝对坐标值传递给构造函数，仍会创建鼠标事件实例并且不会抛出异常。如果 source 是 null，此方法将抛出 IllegalArgumentException。

      参数：
      source - 发起事件的 Component
      id - 表示事件类型的整数。有关允许值的信息，请参阅 MouseEvent 的类描述
      when - 一个长整数，表示事件发生的时间。不建议传递负值或零值
      modifiers - 修饰符掩码，描述在事件期间按下的修饰键和鼠标按钮（例如，shift、ctrl、alt 和 meta）。只允许扩展修饰符用作此参数的值（有关扩展修饰符的说明，请参阅 InputEvent.getModifiersEx() 类）。不建议传递负参数。零值意味着没有传递修饰符
      x - 鼠标位置的水平 x 坐标。允许传递负值
      y - 鼠标位置的垂直 y 坐标。允许传递负值
      xAbs - 鼠标位置的绝对水平x坐标 允许传递负值
      yAbs - 鼠标位置的绝对垂直y坐标 允许传递负值
      clickCount - 与事件关联的鼠标点击次数。不建议传递负值
      popupTrigger - 如果此事件是弹出菜单的触发器，则等于 true 的boolean
      button - 一个整数，指示哪个鼠标按钮已更改其状态。以下规则适用于此参数：
      • 如果 Java 对扩展鼠标按钮的支持是 disabled ，则只允许使用标准按钮创建 MouseEvent 对象：NOBUTTON、BUTTON1、BUTTON2 和 BUTTON3。
      • 如果 Java enabled 支持扩展鼠标按钮，则允许使用标准按钮创建 MouseEvent 对象。如果 Java 对扩展鼠标按钮的支持是 enabled ，那么除了标准按钮之外，如果鼠标具有三个以上的按钮，则可以使用从 4 到 MouseInfo.getNumberOfButtons() 范围内的按钮创建 MouseEvent 对象。
      抛出：
      IllegalArgumentException - 如果 button 小于零
      IllegalArgumentException - 如果 source 为空
      IllegalArgumentException - 如果 button 大于 BUTTON3 并且对扩展鼠标按钮的支持是 Java 的 disabled
      IllegalArgumentException - 如果 button 大于 current number of buttons 并且对扩展鼠标按钮的支持是 Java 的 enabled
      IllegalArgumentException - 如果传入了无效的 button 值
      IllegalArgumentException - 如果 source 为空
      自从：
      1.6
      参见：

  • 方法详情

    • getLocationOnScreen

      public Point  getLocationOnScreen()
      返回事件的绝对 x、y 位置。在桌面区域可以跨越多个物理屏幕设备的虚拟设备多屏环境中，这些坐标是相对于虚拟坐标系的。否则，这些坐标是相对于与组件的 GraphicsConfiguration 关联的坐标系的。
      返回：
      包含绝对 x 和 y 坐标的 Point 对象。
      自从：
      1.6
      参见：

    • getXOnScreen

      public int getXOnScreen()
      返回事件的绝对水平 x 位置。在桌面区域可以跨越多个物理屏幕设备的虚拟设备多屏环境中，该坐标是相对于虚拟坐标系的。否则，此坐标相对于与组件的 GraphicsConfiguration 关联的坐标系。
      返回：
      x 表示绝对水平位置的整数。
      自从：
      1.6
      参见：

    • getYOnScreen

      public int getYOnScreen()
      返回事件的绝对垂直 y 位置。在桌面区域可以跨越多个物理屏幕设备的虚拟设备多屏环境中，该坐标是相对于虚拟坐标系的。否则，此坐标相对于与组件的 GraphicsConfiguration 关联的坐标系。
      返回：
      y 表示绝对垂直位置的整数。
      自从：
      1.6
      参见：

    • getX

      public int getX()
      返回事件相对于源组件的水平 x 位置。
      返回：
      x 一个整数，指示相对于组件的水平位置

    • getY

      public int getY()
      返回事件相对于源组件的垂直 y 位置。
      返回：
      y 一个整数，指示相对于组件的垂直位置

    • getPoint

      public Point  getPoint()
      返回事件相对于源组件的 x,y 位置。
      返回：
      包含相对于源组件的 x 和 y 坐标的 Point 对象

    • translatePoint

      public void translatePoint(int x, int y)
      通过添加指定的 x（水平）和 y（垂直）偏移量将事件的坐标转换到新位置。
      参数：
      x - 添加到当前 x 坐标位置的水平 x 值
      y - 要添加到当前 y 坐标位置的垂直 y 值

    • getClickCount

      public int getClickCount()
      返回与此事件关联的鼠标点击次数。
      返回：
      点击次数的整数值

    • getButton

      public int getButton()
      返回哪个鼠标按钮（如果有）已更改状态。返回值范围从 0 到 MouseInfo.getNumberOfButtons() 值。返回值至少包括以下常量：
      • NOBUTTON
      • BUTTON1
      • BUTTON2
      • BUTTON3
      允许使用这些常量与应用程序中返回的按钮编号进行比较。例如， 
       if (anEvent.getButton() == MouseEvent.BUTTON1) {
      特别是，对于具有一个、两个或三个按钮的鼠标，此方法可能会返回以下值：
      • 0 (NOBUTTON )
      • 1 (BUTTON1)
      • 2 (BUTTON2 )
      • 3 (BUTTON3 )
      大于 BUTTON3 的按钮编号没有常量标识符。因此，如果安装了带有五个按钮的鼠标，此方法可能会返回以下值：
      • 0 (NOBUTTON )
      • 1 (BUTTON1)
      • 2 (BUTTON2 )
      • 3 (BUTTON3 )
      • 4
      • 5

      注意：如果 Java disabled 支持扩展鼠标按钮，则 AWT 事件子系统不会为扩展鼠标按钮生成鼠标事件。因此，预计此方法不会返回除 NOBUTTON、BUTTON1、BUTTON2、BUTTON3 之外的任何内容。

      返回：
      从 0 到 MouseInfo.getNumberOfButtons() 的值之一，如果对扩展鼠标按钮的支持是 Java 的 enabled 。该范围包括 NOBUTTON、BUTTON1、BUTTON2、BUTTON3；
      NOBUTTON , BUTTON1 , BUTTON2 或 BUTTON3 如果 Java 对扩展鼠标按钮的支持是 disabled
      自从：
      1.4
      参见：

    • isPopupTrigger

      public boolean isPopupTrigger()
      返回此鼠标事件是否为平台的弹出菜单触发事件。

      笔记：弹出菜单在不同系统上的触发方式不同。因此，应在 mousePressed 和 mouseReleased 中检查 isPopupTrigger 以获得正确的跨平台功能。

      返回：
      boolean，如果此事件是此平台的弹出菜单触发器，则为真

    • getMouseModifiersText

      public static String  getMouseModifiersText(int modifiers)
      返回一个 String 实例，描述事件期间按下的修改键和鼠标按钮，例如“Shift”或“Ctrl+Shift”。这些字符串可以通过更改 awt.properties 文件进行本地化。

      请注意，InputEvent.ALT_MASK 和 InputEvent.BUTTON2_MASK 具有相等的值，因此为两个修饰符返回“Alt”字符串。同样，InputEvent.META_MASK 和 InputEvent.BUTTON3_MASK 具有相等的值，因此为两个修饰符返回“Meta”字符串。

      请注意，传递负参数是不正确的，并且会导致返回未指定的字符串。零参数意味着没有传递任何修饰符，将导致返回一个空字符串。

      参数：
      modifiers - 修改器掩码，描述事件期间按下的修改键和鼠标按钮
      返回：
      string string 事件期间按下的修改键和鼠标按钮组合的文本描述
      自从：
      1.4
      参见：

    • paramString

      public String  paramString()
      返回标识此事件的参数字符串。此方法对于事件记录和调试很有用。
      重写：
      paramString 在类 ComponentEvent 中
      返回：
      标识事件及其属性的字符串