Класс MouseEvent

public non-sealed class MouseEvent extends InputEvent

Событие, указывающее на то, что в компоненте произошло действие мыши. Действие мыши считается произошедшим в определённом компоненте только в том случае, если курсор мыши находится над незатенённой частью границ компонента в момент действия. Для лёгких компонентов, таких как компоненты Swing, события мыши передаются компоненту только в том случае, если тип события мыши включен в компоненте. Тип события мыши включается путём добавления соответствующих событий, связанных с мышью, в компонент (MouseListener или MouseMotionListener), или вызова Component.enableEvents(long) с соответствующим параметром маски (AWTEvent.MOUSE_EVENT_MASK или AWTEvent.MOUSE_MOTION_EVENT_MASK). Если тип события мыши не включен в компоненте, соответствующие события мыши передаются первому предку, в котором тип события мыши включен.

Например, если в компонент добавлен 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, могут использоваться в качестве номеров кнопок (идентификаторов кнопок). Значения, полученные методом getMaskForButton(button), могут использоваться как маски кнопок.

События MOUSE_DRAGGED передаются в Component, в котором кнопка мыши была нажата до тех пор, пока кнопка мыши не будет отпущена (независимо от того, находится ли положение мыши в пределах границ Component). Из-за платформенно-зависимых реализаций Drag&Drop, события MOUSE_DRAGGED могут не передаваться во время выполнения операции Drag&Drop. В многоэкранной среде события перетаскивания мыши передаются в Component, даже если положение мыши находится за пределами границ GraphicsConfiguration, связанных с этим Component. Однако, сообщаемое положение для событий перетаскивания мыши в этом случае может отличаться от фактического положения мыши:

• В многоэкранной среде без виртуального устройства:
  Сообщаемые координаты для событий перетаскивания мыши обрезаются, чтобы поместиться в пределах границ GraphicsConfiguration связанных с Component.
• В многоэкранной среде с виртуальным устройством:
  Сообщаемые координаты для событий перетаскивания мыши обрезаются, чтобы поместиться в пределах границ виртуального устройства, связанного с Component.

Неопределённое поведение будет вызвано, если параметр id любого конкретного экземпляра MouseEvent не находится в диапазоне от MOUSE_FIRST до MOUSE_LAST-1 (MOUSE_WHEEL неприемлемо).