Java Doc for MouseEvent.java in  » 6.0-JDK-Core » AWT » java » awt » event » Java Source Code / Java DocumentationJava Source Code and Java Documentation

For example, if a MouseListener has been added to a component, or enableEvents(AWTEvent.MOUSE_EVENT_MASK) has been invoked, then all the events defined by MouseListener are dispatched to the component. On the other hand, if a MouseMotionListener has not been added and enableEvents has not been invoked with AWTEvent.MOUSE_MOTION_EVENT_MASK , then mouse motion events are not dispatched to the component. Instead the mouse motion events are dispatched to the first ancestors that has enabled mouse motion events.

This low-level event is generated by a component object for:

• Mouse Events
  • a mouse button is pressed
  • a mouse button is released
  • a mouse button is clicked (pressed and released)
  • the mouse cursor enters the unobscured part of component's geometry
  • the mouse cursor exits the unobscured part of component's geometry
• Mouse Motion Events
  • the mouse is moved
  • the mouse is dragged

A MouseEvent object is passed to every MouseListener or MouseAdapter object which is registered to receive the "interesting" mouse events using the component's addMouseListener method. (MouseAdapter objects implement the MouseListener interface.) Each such listener object gets a MouseEvent containing the mouse event.

A MouseEvent object is also passed to every MouseMotionListener or MouseMotionAdapter object which is registered to receive mouse motion events using the component's addMouseMotionListener method. (MouseMotionAdapter objects implement the MouseMotionListener interface.) Each such listener object gets a MouseEvent containing the mouse motion event.

When a mouse button is clicked, events are generated and sent to the registered MouseListeners. The state of modal keys can be retrieved using InputEvent.getModifiers and InputEvent.getModifiersEx . The button mask returned by InputEvent.getModifiers reflects only the button that changed state, not the current state of all buttons. (Note: Due to overlap in the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK, this is not always true for mouse events involving modifier keys). To get the state of all buttons and modifier keys, use InputEvent.getModifiersEx . The button which has changed state is returned by MouseEvent.getButton

For example, if the first mouse button is pressed, events are sent in the following order:

 id              modifiers    button           
 MOUSE_PRESSED:  BUTTON1_MASK BUTTON1
 MOUSE_RELEASED: BUTTON1_MASK BUTTON1
 MOUSE_CLICKED:  BUTTON1_MASK BUTTON1
 

For example, if the user presses button 1 followed by button 2, and then releases them in the same order, the following sequence of events is generated:

 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
 

MOUSE_DRAGGED events are delivered to the Component in which the mouse button was pressed until the mouse button is released (regardless of whether the mouse position is within the bounds of the Component). Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation. In a multi-screen environment mouse drag events are delivered to the Component even if the mouse position is outside the bounds of the GraphicsConfiguration associated with that Component. However, the reported position for mouse drag events in this case may differ from the actual mouse position:

• In a multi-screen environment without a virtual device:
  The reported coordinates for mouse drag events are clipped to fit within the bounds of the GraphicsConfiguration associated with the Component.
• In a multi-screen environment with a virtual device:
  The reported coordinates for mouse drag events are clipped to fit within the bounds of the virtual device associated with the Component.

Note that passing in an invalid id results in unspecified behavior.

Note that passing in an invalid id results in unspecified behavior. An invocation of the form MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger) behaves in exactly the same way as the invocation MouseEvent.MouseEvent(Component,int,long,int,int,int,int,int,int,boolean,int) MouseEvent (source, id, when, modifiers, x, y, xAbs, yAbs, clickCount, popupTrigger, MouseEvent.NOBUTTON) where xAbs and yAbs defines as source's location on screen plus relative coordinates x and y. xAbs and yAbs are set to zero if the source is not showing. This method throws an IllegalArgumentException if source is null.
Parameters:
  source - the Component that originated the event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long int that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event (e.g.

Note that passing in an invalid id results in unspecified behavior.

Note: Popup menus are triggered differently on different systems.

Note that passing in an invalid id results in unspecified behavior. Creating an invalid event (such as by using more than one of the old _MASKs, or modifier/button values which don't match) results in unspecified behavior. An invocation of the form MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger, button) behaves in exactly the same way as the invocation MouseEvent.MouseEvent(Component,int,long,int,int,int,int,int,int,boolean,int) MouseEvent (source, id, when, modifiers, x, y, xAbs, yAbs, clickCount, popupTrigger, button) where xAbs and yAbs defines as source's location on screen plus relative coordinates x and y. xAbs and yAbs are set to zero if the source is not showing. This method throws an IllegalArgumentException if source is null.
Parameters:
  source - the Component that originated the event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long int that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event (e.g. shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event. Use of the extended modifiers ispreferred.
Parameters:
  x - the horizontal x coordinate for the mouse location
Parameters:
  y - the vertical y coordinate for the mouse location
Parameters:
  clickCount - the number of mouse clicks associated with event
Parameters:
  popupTrigger - a boolean, true if this event is a trigger for apopup menu
Parameters:
  button - which of the mouse buttons has changed state.NOBUTTON,BUTTON1,BUTTON2 orBUTTON3.
throws:
  IllegalArgumentException - if an invalid button value is passed in
throws:
  IllegalArgumentException - if source is null
since:
   1.4

Note that passing in an invalid id results in unspecified behavior. An invocation of the form MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger) behaves in exactly the same way as the invocation MouseEvent.MouseEvent(Component,int,long,int,int,int,int,int,int,boolean,int) MouseEvent (source, id, when, modifiers, x, y, xAbs, yAbs, clickCount, popupTrigger, MouseEvent.NOBUTTON) where xAbs and yAbs defines as source's location on screen plus relative coordinates x and y. xAbs and yAbs are set to zero if the source is not showing. This method throws an IllegalArgumentException if source is null.
Parameters:
  source - the Component that originated the event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long int that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event (e.g. shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event. Use of the extended modifiers ispreferred.
Parameters:
  x - the horizontal x coordinate for the mouse location
Parameters:
  y - the vertical y coordinate for the mouse location
Parameters:
  clickCount - the number of mouse clicks associated with event
Parameters:
  popupTrigger - a boolean, true if this event is a trigger for apopup menu
throws:
  IllegalArgumentException - if source is null

Note that passing in an invalid id results in unspecified behavior. Creating an invalid event (such as by using more than one of the old _MASKs, or modifier/button values which don't match) results in unspecified behavior. Even if inconsistent values for relative and absolute coordinates are passed to the constructor, the mouse event instance is still created and no exception is thrown. This method throws an IllegalArgumentException if source is null.
Parameters:
  source - the Component that originated the event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long int that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event (e.g. shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event. Use of the extended modifiers ispreferred.
Parameters:
  x - the horizontal x coordinate for the mouse location
Parameters:
  y - the vertical y coordinate for the mouse location
Parameters:
  xAbs - the absolute horizontal x coordinate for the mouse location
Parameters:
  yAbs - the absolute vertical y coordinate for the mouse location
Parameters:
  clickCount - the number of mouse clicks associated with event
Parameters:
  popupTrigger - a boolean, true if this event is a trigger for apopup menu
Parameters:
  button - which of the mouse buttons has changed state.NOBUTTON,BUTTON1,BUTTON2 orBUTTON3.
throws:
  IllegalArgumentException - if an invalid button value is passed in
throws:
  IllegalArgumentException - if source is null
since:
   1.6

Note that InputEvent.ALT_MASK and InputEvent.BUTTON2_MASK have the same value, so the string "Alt" is returned for both modifiers. Likewise, InputEvent.META_MASK and InputEvent.BUTTON3_MASK have the same value, so the string "Meta" is returned for both modifiers.
Parameters:
  modifiers - a modifier mask describing the modifier keys and mouse buttons that were down during the event string a text description of the combination of modifierkeys and mouse buttons that were down during the event
See Also:   InputEvent.getModifiersExText(int)
since:
   1.4

Note: Popup menus are triggered differently on different systems. Therefore, isPopupTrigger should be checked in both mousePressed and mouseReleased for proper cross-platform functionality. boolean, true if this event is the popup menu triggerfor this platform