Module java.desktop
Package 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
所有已实现的接口:
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，则鼠标移动事件不会被分派到组件。相反，鼠标移动事件将被分派到首个启用鼠标移动事件的祖先。

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

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

每个已注册以接收“感兴趣”鼠标事件的MouseListener或MouseAdapter对象都会收到一个MouseEvent对象，该对象包含鼠标事件。

每个已注册以接收鼠标移动事件的MouseMotionListener或MouseMotionAdapter对象都会收到一个MouseEvent对象，该对象包含鼠标移动事件。

当鼠标按钮被点击时，事件将被生成并发送到已注册的MouseListener。可以使用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
参见:

  • Field Details

    • 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
      参见：

  • Constructor Details

    • MouseEvent

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

      创建无效事件（例如使用旧的_MASKS之一，或者修饰符/按钮值不匹配）会导致未指定的行为。形式为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
      button - 指示哪个鼠标按钮的状态发生了变化的整数。对此参数应用以下规则：
      • 如果Java通过禁用了对扩展鼠标按钮的支持，则只允许使用标准按钮创建MouseEvent对象：NOBUTTON、BUTTON1、BUTTON2和BUTTON3。
      • 如果Java通过启用了对扩展鼠标按钮的支持，则允许使用标准按钮创建MouseEvent对象。如果Java通过启用了对扩展鼠标按钮的支持，则除了标准按钮外，还可以使用从4开始到MouseInfo.getNumberOfButtons()的范围内的按钮创建MouseEvent对象，如果鼠标有超过三个按钮。
      抛出：
      IllegalArgumentException - 如果button小于零
      IllegalArgumentException - 如果source为null
      IllegalArgumentException - 如果button大于BUTTON3且Java通过禁用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果button大于当前按钮数量且Java通过启用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果传递了无效的button值
      IllegalArgumentException - 如果source为null
      自：
      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
      抛出:
      IllegalArgumentException - 如果source为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)
      使用指定的源组件、类型、时间、修饰符、坐标、绝对坐标、点击计数、popupTrigger 标志和按钮编号构造一个MouseEvent对象。

      创建无效事件（例如使用旧的_MASKs中的一个以上，或者不匹配的修饰符/按钮值）会导致未指定的行为。即使将不一致的相对和绝对坐标值传递给构造函数，鼠标事件实例仍会被创建，不会抛出异常。如果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
      button - 一个指示哪个鼠标按钮改变状态的整数。对此参数应用以下规则：
      • 如果Java禁用了对扩展鼠标按钮的支持，则只允许使用标准按钮：NOBUTTON、BUTTON1、BUTTON2和BUTTON3创建MouseEvent对象。
      • 如果Java启用了对扩展鼠标按钮的支持，则允许使用标准按钮创建MouseEvent对象。如果Java启用了对扩展鼠标按钮的支持，则除了标准按钮外，还可以使用从4到MouseInfo.getNumberOfButtons()的范围内的按钮创建MouseEvent对象，如果鼠标有超过三个按钮。
      抛出:
      IllegalArgumentException - 如果button小于零
      IllegalArgumentException - 如果source为null
      IllegalArgumentException - 如果button大于BUTTON3且Java禁用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果button大于当前按钮数量且Java启用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果传递了无效的button值
      IllegalArgumentException - 如果source为null
      自:
      1.6
      参见:

  • Method Details

    • 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禁用了对扩展鼠标按钮的支持，则AWT事件子系统不会为扩展鼠标按钮产生鼠标事件。因此，不应该期望此方法返回除NOBUTTON、BUTTON1、BUTTON2、BUTTON3之外的任何内容。

      返回:
      如果Java启用了对扩展鼠标按钮的支持，则返回0到MouseInfo.getNumberOfButtons()之间的一个值。该范围包括NOBUTTON、BUTTON1、BUTTON2、BUTTON3；
      NOBUTTON、BUTTON1、BUTTON2或BUTTON3如果Java禁用了对扩展鼠标按钮的支持
      自：
      1.4
      参见：

    • isPopupTrigger

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

      注意：不同系统上的弹出菜单触发方式不同。因此，为了正确的跨平台功能，应该在mousePressed和mouseReleased中都检查isPopupTrigger。

      返回:
      布尔值，如果此事件是此平台的弹出菜单触发器，则为true

    • 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 - 描述事件期间按下的修改键和鼠标按钮的修饰键掩码
      返回:
      描述事件期间按下的修改键和鼠标按钮组合的字符串文本描述
      自：
      1.4
      参见：

    • paramString

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