Module  java.desktop
软件包  java.awt.event

Class MouseEvent

  • All Implemented Interfaces:
    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
        用于鼠标事件的ids范围中的第一个数字。
        另请参见：
        Constant Field Values

      • MOUSE_LAST

        public static final int MOUSE_LAST
        用于鼠标事件的ids范围中的最后一个数字。
        另请参见：
        Constant Field Values

      • MOUSE_CLICKED

        public static final int MOUSE_CLICKED
        “鼠标点击”事件。 当按下并释放鼠标按钮时，会发生MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_PRESSED

        public static final int MOUSE_PRESSED
        “鼠标按下”事件。 当按下鼠标按钮时，会发生MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_RELEASED

        public static final int MOUSE_RELEASED
        “鼠标释放”事件。 当鼠标按钮MouseEvent时，会发生MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_MOVED

        public static final int MOUSE_MOVED
        “鼠标移动”事件。 当鼠标位置发生变化时，会发生MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_ENTERED

        public static final int MOUSE_ENTERED
        “鼠标进入”事件。 当鼠标光标进入组件几何的视野MouseEvent时，会发生此MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_EXITED

        public static final int MOUSE_EXITED
        “鼠标退出”事件。 当鼠标光标退出组件几何的视野MouseEvent时，会发生此MouseEvent 。
        另请参见：
        Constant Field Values

      • MOUSE_DRAGGED

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

      • MOUSE_WHEEL

        public static final int MOUSE_WHEEL
        “鼠标滚轮”事件。 这是唯一的MouseWheelEvent 。 当装有轮子的鼠标轮旋转时，会发生这种情况。
        从以下版本开始：
        1.4
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • MouseEvent

        public MouseEvent​(Component source,
                  int id,
                  long when,
                  int modifiers,
                  int x,
                  int y,
                  int clickCount,
                  boolean popupTrigger,
                  int button)
        构造具有指定的源组件，类型，时间，修饰符，坐标，点击计数，弹出触发器标志和按钮编号的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和yAb定义为屏幕上的源位置加上相对坐标x和y。 如果源未显示，则xAbs和yAb设置为零。 此方法抛出IllegalArgumentException如果source为null 。

        参数
        source - 发起事件的 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，并且对扩展鼠标按钮的支持是 enabled由Java
        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)
        构造一个具有指定源组件，类型，修饰符，坐标，点击数和弹出触发标志的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和yAb设置为零。 此方法抛出IllegalArgumentException如果source为null 。
        参数
        source - 发起事件的 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)
        构造具有指定源组件，类型，时间，修饰符，坐标，绝对坐标，点击计数，弹出触发标志和按钮编号的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，并且对扩展鼠标按钮的支持是 disabled由Java
        IllegalArgumentException - 如果 button大于 current number of buttons，并且对于扩展鼠标按钮的支持是 enabled由Java
        IllegalArgumentException - 如果传递无效的 button值
        IllegalArgumentException - 如果 source为空
        从以下版本开始：
        1.6
        另请参见：
        EventObject.getSource() ， AWTEvent.getID() ， InputEvent.getWhen() ， InputEvent.getModifiers() ， getX() ， getY() ， getXOnScreen() ， getYOnScreen() ， getClickCount() ， isPopupTrigger() ， getButton() ， button ， Toolkit.areExtraMouseButtonsEnabled() ， MouseInfo.getNumberOfButtons() ， InputEvent.getMaskForButton(int)

    • 方法详细信息

      • getLocationOnScreen

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

      • getXOnScreen

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

      • getYOnScreen

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

      • getModifiersEx

        public int getModifiersEx​()
        返回此事件的扩展修饰符掩码。

        扩展修饰符是以_DOWN_MASK后缀结尾的修饰符，如ALT_DOWN_MASK，BUTTON1_DOWN_MASK等。

        扩展修饰符表示所有模态键的状态，如ALT，CTRL，META和事件发生后的鼠标按钮。

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

          MOUSE_PRESSED:  BUTTON1_DOWN_MASK
    MOUSE_PRESSED:  BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK
    MOUSE_RELEASED: BUTTON2_DOWN_MASK
    MOUSE_CLICKED:  BUTTON2_DOWN_MASK
    MOUSE_RELEASED:
    MOUSE_CLICKED:

        不建议使用==比较此方法的返回值，因为将来可以添加新的修饰符。 例如，检查SHIFT和BUTTON1是否正常，但是CTRL已经起作用的适当方法可以通过以下代码来证明： 

          int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
    int offmask = CTRL_DOWN_MASK;
    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
        ...
    }
        即使添加了新的修饰符，上述代码也可以正常工作。
        重写：
        getModifiersEx在 InputEvent
        结果
        此事件的扩展修饰符掩码

      • getX

        public int getX​()
        返回事件相对于源组件的水平x位置。
        结果
        x表示相对于组件的水平位置的整数

      • getY

        public int getY​()
        返回事件相对于源组件的垂直y位置。
        结果
        y表示相对于组件的垂直位置的整数

      • getPoint

        public Point getPoint​()
        返回事件相对于源组件的x，y位置。
        结果
        一个 Point对象，包含相对于源组件的x和y坐标

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

        结果
        从0到MouseInfo.getNumberOfButtons()的值之一，如果通过Java支持扩展鼠标按键是enabled 。 该范围包括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
        结果
        a string identifying the event and its attributes