java::awt::event::MouseEvent Class Reference

Inheritance diagram for java::awt::event::MouseEvent:

Inheritance graph
java::awt::event::MouseWheelEventjava::awt::event::InputEventjava::awt::event::ComponentEventjava::awt::AWTEventjava::util::EventObjectjava::lang::Object
[legend]
Collaboration diagram for java::awt::event::MouseEvent:

Collaboration graph
java::awt::event::InputEventjava::awt::event::ComponentEventjava::awt::AWTEventjava::util::EventObjectjava::lang::Objectjava::lang::ObjectRefjava::lang::Interfacejava::lang::Syncjava::lang::Comparablejava::lang::ScopeAdapterjava::lang::Lock
[legend]

List of all members.


Detailed Description

An event which indicates that a mouse action occurred in a component.

A mouse action is considered to occur in a particular component if and only if the mouse cursor is over the unobscured part of the component's bounds when the action happens. Component bounds can be obscurred by the visible component's children or by a menu or by a top-level window. This event is used both for mouse events (click, enter, exit) and mouse motion events (moves and drags).

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

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
 
When multiple mouse buttons are pressed, each press, release, and click results in a separate event.

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
 
If button 2 is released first, the MOUSE_RELEASED/MOUSE_CLICKED pair for BUTTON2_MASK arrives first, followed by the pair for BUTTON1_MASK.

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:

Author:
Carl Quinn 1.45, 01/23/03
See also:
MouseAdapter

MouseListener

MouseMotionAdapter

MouseMotionListener

MouseWheelListener

Tutorial: Writing a Mouse Listener

Tutorial: Writing a Mouse Motion Listener

Reference: The Java Class Libraries (update file)

Since:
1.1

Public Types

enum  MOUSE_EVENT_ID {
  MOUSE_FIRST = 500, MOUSE_CLICKED = MOUSE_FIRST, MOUSE_PRESSED, MOUSE_RELEASED,
  MOUSE_ENTERED, MOUSE_EXITED, MOUSE_MOTION_FIRST, MOUSE_MOVED = MOUSE_MOTION_FIRST,
  MOUSE_DRAGGED, MOUSE_MOTION_LAST = MOUSE_DRAGGED, MOUSE_WHEEL_FIRST, MOUSE_WHEEL = MOUSE_WHEEL_FIRST,
  MOUSE_WHEEL_LAST = MOUSE_WHEEL, MOUSE_LAST = MOUSE_WHEEL
}
enum  MOUSE_EVENT_BUTTON { NOBUTTON = 0, BUTTON1, BUTTON2, BUTTON3 }

Public Member Functions

 MouseEvent ()
 MouseEvent (const Ref< Component > &source, jint id, jlong when, jint modifiers, jint x, jint y, jint clickCount=0, jboolean popupTrigger=false, jint button=NOBUTTON)
 Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.
virtual void consume ()
 Consumes this event, if this event can be consumed.
virtual jint getX () const
 Returns the horizontal x position of the event relative to the source component.
virtual jint getY () const
 Returns the vertical y position of the event relative to the source component.
virtual Point getPoint () const
 Returns the x,y position of the event relative to the source component.
virtual void translatePoint (jint x, jint y)
 Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.
virtual jint getClickCount () const
 Returns the number of mouse clicks associated with this event.
virtual jint getButton () const
 Returns which, if any, of the mouse buttons has changed state.
virtual jboolean isPopupTrigger () const
 Returns whether or not this mouse event is the popup menu trigger event for the platform.
virtual String paramString () const
 Returns a parameter string identifying this event.

Protected Attributes

jint x
 The mouse event's x coordinate.
jint y
 The mouse event's y coordinate.
jint clickCount
 Indicates the number of quick consecutive clicks of a mouse button.
jboolean popupTrigger
 A property used to indicate whether a Popup Menu should appear with a certain gestures.
jint button
 Indicates which, if any, of the mouse buttons has changed state.
Sync sync

Member Enumeration Documentation

enum java::awt::event::MouseEvent::MOUSE_EVENT_ID

Enumerator:
MOUSE_FIRST  The first number in the range of ids used for mouse events.
MOUSE_CLICKED  The "mouse clicked" event.

This MouseEvent occurs when a mouse button is pressed and released.

MOUSE_PRESSED  The "mouse pressed" event.

This MouseEvent occurs when a mouse button is pushed down.

MOUSE_RELEASED  The "mouse released" event.

This MouseEvent occurs when a mouse button is let up.

MOUSE_ENTERED  The "mouse entered" event.

This MouseEvent occurs when the mouse cursor enters the unobscured part of component's geometry.

MOUSE_EXITED  The "mouse exited" event.

This MouseEvent occurs when the mouse cursor exits the unobscured part of component's geometry.

MOUSE_MOTION_FIRST  The first number in the range of ids used for mouse motion events.
MOUSE_MOVED  The "mouse moved" event.

This MouseEvent occurs when the mouse position changes.

MOUSE_DRAGGED  The "mouse dragged" event.

This MouseEvent occurs when the mouse position changes while a mouse button is pressed.

MOUSE_MOTION_LAST  The last number in the range of ids used for mouse motion events.
MOUSE_WHEEL_FIRST  The first number in the range of ids used for mouse wheel events.
MOUSE_WHEEL  The "mouse wheel" event.

This is the only MouseWheelEvent. It occurs when a mouse equipped with a wheel has its wheel rotated.

Since:
1.4
MOUSE_WHEEL_LAST  The last number in the range of ids used for mouse wheel events.
MOUSE_LAST  The last number in the range of ids used for mouse events.

enum java::awt::event::MouseEvent::MOUSE_EVENT_BUTTON

Enumerator:
NOBUTTON  Indicates no mouse buttons; used by getButton.

Since:
1.4
BUTTON1  Indicates mouse button #1; used by getButton.

Since:
1.4
BUTTON2  Indicates mouse button #2; used by getButton.

Since:
1.4
BUTTON3  Indicates mouse button #3; used by getButton.

Since:
1.4


Constructor & Destructor Documentation

java::awt::event::MouseEvent::MouseEvent (  ) 

java::awt::event::MouseEvent::MouseEvent ( const Ref< Component > &  source,
jint  id,
jlong  when,
jint  modifiers,
jint  x,
jint  y,
jint  clickCount = 0,
jboolean  popupTrigger = false,
jint  button = NOBUTTON 
)

Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.

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

Parameters:
source the Component that originated the event
id the integer that identifies the event
when a long int that gives the time the event occurred
modifiers the modifier keys down during event (e.g. shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.
x the horizontal x coordinate for the mouse location
y the vertical y coordinate for the mouse location
clickCount the number of mouse clicks associated with event
popupTrigger a boolean, true if this event is a trigger for a popup menu
button which of the mouse buttons has changed state. NOBUTTON, BUTTON1, BUTTON2 or BUTTON3.
Exceptions:
IllegalArgumentException if if an invalid button value is passed in.
Since:
1.4


Member Function Documentation

virtual void java::awt::event::MouseEvent::consume (  )  [virtual]

Consumes this event, if this event can be consumed.

Only low-level, system events can be consumed

Reimplemented from java::awt::event::InputEvent.

virtual jint java::awt::event::MouseEvent::getX (  )  const [virtual]

Returns the horizontal x position of the event relative to the source component.

Returns:
x an integer indicating horizontal position relative to the component

virtual jint java::awt::event::MouseEvent::getY (  )  const [virtual]

Returns the vertical y position of the event relative to the source component.

Returns:
y an integer indicating vertical position relative to the component

virtual Point java::awt::event::MouseEvent::getPoint (  )  const [virtual]

Returns the x,y position of the event relative to the source component.

Returns:
a Point object containing the x and y coordinates relative to the source component

virtual void java::awt::event::MouseEvent::translatePoint ( jint  x,
jint  y 
) [virtual]

Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.

Parameters:
x the horizontal x value to add to the current x coordinate position
y the vertical y value to add to the current y coordinate position

virtual jint java::awt::event::MouseEvent::getClickCount (  )  const [virtual]

Returns the number of mouse clicks associated with this event.

Returns:
integer value for the number of clicks

virtual jint java::awt::event::MouseEvent::getButton (  )  const [virtual]

Returns which, if any, of the mouse buttons has changed state.

Returns:
one of the following constants: NOBUTTON, BUTTON1, BUTTON2 or BUTTON3.
Since:
1.4

virtual jboolean java::awt::event::MouseEvent::isPopupTrigger (  )  const [virtual]

Returns whether or not this mouse event is the popup menu trigger event for the platform.

Note: Popup menus are triggered differently on different systems. Therefore, isPopupTrigger should be checked in both mousePressed and mouseReleased for proper cross-platform functionality.

Returns:
boolean, true if this event is the popup menu trigger for this platform

virtual String java::awt::event::MouseEvent::paramString (  )  const [virtual]

Returns a parameter string identifying this event.

This method is useful for event-logging and for debugging.

Returns:
a string identifying the event and its attributes

Reimplemented from java::awt::event::ComponentEvent.

Reimplemented in java::awt::event::MouseWheelEvent.


Member Data Documentation

jint java::awt::event::MouseEvent::x [protected]

The mouse event's x coordinate.

The x value is relative to the component that fired the event.

See also:
getX()

jint java::awt::event::MouseEvent::y [protected]

The mouse event's y coordinate.

The y value is relative to the component that fired the event.

See also:
getY()

jint java::awt::event::MouseEvent::clickCount [protected]

Indicates the number of quick consecutive clicks of a mouse button.

clickCount will be valid for only three mouse events :
MOUSE_CLICKED, MOUSE_PRESSED and MOUSE_RELEASED. For the above, the clickCount will be at least 1. For all other events the count will be 0.

See also:
getClickCount().

jboolean java::awt::event::MouseEvent::popupTrigger [protected]

A property used to indicate whether a Popup Menu should appear with a certain gestures.

If popupTrigger = false, no popup menu should appear. If it is true then a popup menu should appear.

See also:
java.awt.PopupMenu

isPopupTrigger()

jint java::awt::event::MouseEvent::button [protected]

Indicates which, if any, of the mouse buttons has changed state.

The only legal values are the following constants: NOBUTTON, BUTTON1, BUTTON2 or BUTTON3.

See also:
getButton().

Sync java::awt::event::MouseEvent::sync [protected]


The documentation for this class was generated from the following file:
Generated on Fri May 16 11:56:18 2008 for CrossPlatformJavaLikeC++API by  doxygen 1.5.3