模块  java.desktop
软件包  java.awt.event

Class MouseEvent

  • 实现的所有接口
    Serializable
    已知直接子类：
    MenuDragMouseEvent ， MouseWheelEvent 
    public 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未添加和enableEvents未被调用与AWTEvent.MOUSE_MOTION_EVENT_MASK ，然后鼠标移动事件不分派给该组件。 而是将鼠标运动事件分派给已启用鼠标运动事件的第一个祖先。

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

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

    将MouseEvent对象传递给每个MouseListener或MouseAdapter对象，该对象已注册为使用组件的addMouseListener方法接收“有趣”鼠标事件。 （ MouseAdapter对象实现了MouseListener接口。）每个此类侦听器对象都获得包含鼠标事件的MouseEvent 。

    还会将MouseEvent对象传递给每个MouseMotionListener或MouseMotionAdapter对象，该对象已注册为使用组件的addMouseMotionListener方法接收鼠标移动事件。 （ MouseMotionAdapter对象实现了MouseMotionListener接口。）每个这样的侦听器对象都获得包含鼠标移动事件的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被首先释放， MOUSE_RELEASED / MOUSE_CLICKED对为BUTTON2_MASK首先到达，然后由该对为BUTTON1_MASK 。

    一些额外的鼠标按钮被添加到扩展标准组由下列常数表示按钮： BUTTON1 ， BUTTON2 ，和BUTTON3 。 额外按钮没有指定BUTTONx常量，并且其按钮掩码没有指定BUTTONx_DOWN_MASK常量。 然而，从4开始的序数可以用作按钮号（按钮ID）。 通过getMaskForButton(button)方法获得的值可以用作按钮掩模。

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

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

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

    从以下版本开始：
    1.1
    另请参见：
    MouseAdapter ， MouseListener ， MouseMotionAdapter ， MouseMotionListener ， MouseWheelListener ， Tutorial: Writing a Mouse Listener ， Tutorial: Writing a Mouse Motion Listener ， Serialized Form

    • 字段详细信息

      • 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鼠标按钮时会发生此MouseEvent 。
        另请参见：
        常数字段值

      • MOUSE_RELEASED

        public static final int MOUSE_RELEASED
        “鼠标发布”事件。 MouseEvent鼠标按钮时会发生此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设置为零。 此方法抛出IllegalArgumentException如果source为null 。

        参数
        source - 起源 Component事件的 Component
        id - 指示事件类型的整数。 有关允许值的信息，请参阅MouseEvent的类说明
        when - 一个长整数，给出事件发生的时间。 建议不要传递负值或零值
        modifiers - 一个修饰符掩码，描述在事件期间关闭的修改键和鼠标按钮（例如，shift，ctrl，alt和meta）。 只允许使用扩展修饰符作为此参数的值（有关扩展修饰符的说明，请参阅InputEvent.getModifiersEx()类）。 不建议传递负参数。 零值表示没有传递修饰符
        x - 鼠标位置的水平x坐标。 允许传递负值
        y - 鼠标位置的垂直y坐标。 允许传递负值
        clickCount - 与事件关联的鼠标单击次数。 不建议传递负值
        popupTrigger - 如果此事件是弹出菜单的触发器，则该布尔值等于 true
        button - 一个整数，指示哪个鼠标按钮已更改其状态。 以下规则适用于此参数：
        • 如果扩展的鼠标按钮的支持是disabled在Java则允许创建MouseEvent个与标准按钮对象： NOBUTTON ， BUTTON1 ， BUTTON2和BUTTON3 。
        • 如果Java支持扩展鼠标按钮为enabled ，则允许使用标准按钮创建MouseEvent对象。 如果Java支持扩展鼠标按钮是enabled ，那么除了标准按钮之外，如果鼠标有三个以上按钮， MouseEvent可以使用从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
        另请参见：
        EventObject.getSource() ， AWTEvent.getID() ， InputEvent.getWhen() ， InputEvent.getModifiers() ， getX() ， getY() ， getClickCount() ， isPopupTrigger() ， getButton()

      • 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设置为零。 此方法抛出IllegalArgumentException如果source为null 。
        参数
        source - 起源 Component事件的 Component
        id - 指示事件类型的整数。 有关允许值的信息，请参阅MouseEvent的类说明
        when - 一个长整数，表示事件发生的时间。 建议不要传递负值或零值
        modifiers - 一个修饰符掩码，描述在事件期间关闭的修改键和鼠标按钮（例如，shift，ctrl，alt和meta）。 只允许扩展修饰符用作此参数的值（有关扩展修饰符的说明，请参阅InputEvent.getModifiersEx()类）。 不建议传递负参数。 零值表示没有传递修饰符
        x - 鼠标位置的水平x坐标。 允许传递负值
        y - 鼠标位置的垂直y坐标。 允许传递负值
        clickCount - 与事件关联的鼠标单击次数。 不建议传递负值
        popupTrigger - 如果此事件是弹出菜单的触发器，则等于 true的布尔值
        异常
        IllegalArgumentException - 如果 source为空
        另请参见：
        EventObject.getSource() ， AWTEvent.getID() ， InputEvent.getWhen() ， InputEvent.getModifiers() ， getX() ， getY() ， getClickCount() ， isPopupTrigger()

      • 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或不匹配的修饰符/按钮值）会导致未指定的行为。 即使将相对和绝对坐标的不一致值传递给构造函数，仍会创建鼠标事件实例，并且不会抛出异常。 此方法抛出IllegalArgumentException如果source为null 。

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

    • 方法详细信息

      • getLocationOnScreen

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

      • getXOnScreen

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

      • getYOnScreen

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

      • 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
        • 五

        注意：如果Java支持扩展鼠标按钮为disabled ，则AWT事件子系统不会为扩展鼠标按钮生成鼠标事件。 因此，它并不期望该方法返回任何东西，除了NOBUTTON ， BUTTON1 ， BUTTON2 ， BUTTON3 。

        结果
        如果Java支持扩展鼠标按钮为enabled ，则值为0到MouseInfo.getNumberOfButtons()之一 。 该范围包括NOBUTTON ， BUTTON1 ， BUTTON2 ， BUTTON3 ;
        NOBUTTON ， BUTTON1 ， BUTTON2或BUTTON3如果针对扩展鼠标按键支持是disabled被Java
        从以下版本开始：
        1.4
        另请参见：
        Toolkit.areExtraMouseButtonsEnabled() ， MouseInfo.getNumberOfButtons() ， MouseEvent(Component, int, long, int, int, int, int, int, int, boolean, int) ， InputEvent.getMaskForButton(int)

      • isPopupTrigger

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

        注意 ：弹出菜单在不同系统上的触发方式不同。 因此， isPopupTrigger应能在两个检查mousePressed和mouseReleased进行适当的跨平台功能。

        结果
        boolean，如果此事件是此平台的弹出菜单触发器，则为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
        另请参见：
        InputEvent.getModifiersExText(int)

      • paramString

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