Package jmri.util.swing

Class JmriMouseEvent

java.lang.Object

jmri.util.swing.JmriMouseEvent

public class JmriMouseEvent
extends Object

Adaptor for MouseEvent. This class is used to fix some issues with MouseEvent on Windows.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	BUTTON1	Indicates mouse button #1; used by getButton().
static final int	BUTTON2	Indicates mouse button #2; used by getButton().
static final int	BUTTON3	Indicates mouse button #3; used by getButton().
static final int	MOUSE_CLICKED	The "mouse clicked" event.
static final int	MOUSE_DRAGGED	The "mouse dragged" event.
static final int	MOUSE_ENTERED	The "mouse entered" event.
static final int	MOUSE_EXITED	The "mouse exited" event.
static final int	MOUSE_MOVED	The "mouse moved" event.
static final int	MOUSE_PRESSED	The "mouse pressed" event.
static final int	MOUSE_RELEASED	The "mouse released" event.
static final int	MOUSE_WHEEL	The "mouse wheel" event.
static final int	NOBUTTON	Indicates no mouse buttons; used by getButton().

Constructor Summary

Constructors

Constructor	Description
JmriMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)
JmriMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
JmriMouseEvent(MouseEvent event)

Method Summary

Modifier and Type	Method	Description
void	consume()	Consumes this event so that it will not be processed in the default manner by the source which originated it.
int	getButton()	Returns which, if any, of the mouse buttons has changed state.
int	getClickCount()	Returns the number of mouse clicks associated with this event.
Component	getComponent()	Returns the originator of the event.
int	getID()	Returns the event type.
Point	getLocationOnScreen()	Returns the absolute x, y position of the event.
int	getModifiers()	Deprecated. It is recommended that extended modifier keys and getModifiersEx() be used instead
int	getModifiersEx()	Returns the extended modifier mask for this event.
static String	getMouseModifiersText(int modifiers)	Returns a String instance describing the modifier keys and mouse buttons that were down during the event, such as "Shift", or "Ctrl+Shift".
Point	getPoint()	Returns the x,y position of the event relative to the source component.
Object	getSource()	The object on which the Event initially occurred.
long	getWhen()	Returns the difference in milliseconds between the timestamp of when this event occurred and midnight, January 1, 1970 UTC.
int	getX()	Returns the horizontal x position of the event relative to the source component.
int	getXOnScreen()	Returns the absolute horizontal x position of the event.
int	getY()	Returns the vertical y position of the event relative to the source component.
int	getYOnScreen()	Returns the absolute vertical y position of the event.
boolean	isAltDown()	Returns whether or not the Alt modifier is down on this event.
boolean	isAltGraphDown()	Returns whether or not the AltGraph modifier is down on this event.
boolean	isControlDown()	Returns whether or not the Control modifier is down on this event.
boolean	isMetaDown()	Returns whether or not the Meta modifier is down on this event.
boolean	isPopupTrigger()	Returns whether or not this mouse event is the popup menu trigger event for the platform.
boolean	isShiftDown()	Returns whether or not the Shift modifier is down on this event.
String	paramString()	Returns a parameter string identifying this event.
void	translatePoint(int x, int y)	Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MOUSE_CLICKED

public static final int MOUSE_CLICKED

The "mouse clicked" event. This MouseEvent occurs when a mouse button is pressed and released.

See Also:

• Constant Field Values

MOUSE_PRESSED

public static final int MOUSE_PRESSED

The "mouse pressed" event. This MouseEvent occurs when a mouse button is pushed down.

See Also:

• Constant Field Values

MOUSE_RELEASED

public static final int MOUSE_RELEASED

The "mouse released" event. This MouseEvent occurs when a mouse button is let up.

See Also:

• Constant Field Values

MOUSE_MOVED

public static final int MOUSE_MOVED

The "mouse moved" event. This MouseEvent occurs when the mouse position changes.

See Also:

• Constant Field Values

MOUSE_ENTERED

public static final int MOUSE_ENTERED

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

See Also:

• Constant Field Values

MOUSE_EXITED

public static final int MOUSE_EXITED

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

See Also:

• Constant Field Values

MOUSE_DRAGGED

public static final int MOUSE_DRAGGED

The "mouse dragged" event. This MouseEvent occurs when the mouse position changes while a mouse button is pressed.

See Also:

• Constant Field Values

MOUSE_WHEEL

public static final int 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

See Also:

• Constant Field Values

NOBUTTON

public static final int NOBUTTON

Indicates no mouse buttons; used by getButton().

Since:

1.4

See Also:

• Constant Field Values

BUTTON1

public static final int BUTTON1

Indicates mouse button #1; used by getButton().

Since:

1.4

See Also:

• Constant Field Values

BUTTON2

public static final int BUTTON2

Indicates mouse button #2; used by getButton().

Since:

1.4

See Also:

• Constant Field Values

BUTTON3

public static final int BUTTON3

Indicates mouse button #3; used by getButton().

Since:

1.4

See Also:

• Constant Field Values

Constructor Details

JmriMouseEvent

public JmriMouseEvent(MouseEvent event)

JmriMouseEvent

public JmriMouseEvent(Component source,
 int id,
 long when,
 int modifiers,
 int x,
 int y,
 int clickCount,
 boolean popupTrigger)

JmriMouseEvent

public JmriMouseEvent(Component source,
 int id,
 long when,
 int modifiers,
 int x,
 int y,
 int clickCount,
 boolean popupTrigger,
 int button)

Method Details

getID

public int getID()

Returns the event type.

Returns:

the event's type id

getLocationOnScreen

public Point getLocationOnScreen()

Returns the absolute x, y position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, these coordinates are relative to the virtual coordinate system. Otherwise, these coordinates are relative to the coordinate system associated with the Component's GraphicsConfiguration.

Returns:

a Point object containing the absolute x and y coordinates.

Since:

1.6

See Also:

• GraphicsConfiguration

getXOnScreen

public int getXOnScreen()

Returns the absolute horizontal x position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, this coordinate is relative to the virtual coordinate system. Otherwise, this coordinate is relative to the coordinate system associated with the Component's GraphicsConfiguration.

Returns:

x an integer indicating absolute horizontal position.

Since:

1.6

See Also:

• GraphicsConfiguration

getYOnScreen

public int getYOnScreen()

Returns the absolute vertical y position of the event. In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, this coordinate is relative to the virtual coordinate system. Otherwise, this coordinate is relative to the coordinate system associated with the Component's GraphicsConfiguration.

Returns:

y an integer indicating absolute vertical position.

Since:

1.6

See Also:

• GraphicsConfiguration

getX

public int getX()

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

Returns:

x an integer indicating horizontal position relative to the component

getY

public int getY()

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

Returns:

y an integer indicating vertical position relative to the component

getPoint

public Point getPoint()

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

translatePoint

public void translatePoint(int x,
 int y)

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

getClickCount

public int getClickCount()

Returns the number of mouse clicks associated with this event.

Returns:

integer value for the number of clicks

getButton

public int getButton()

Returns which, if any, of the mouse buttons has changed state. The returned value is ranged from 0 to the MouseInfo.getNumberOfButtons() value. The returned value includes at least the following constants:

• NOBUTTON
• BUTTON1
• BUTTON2
• BUTTON3

It is allowed to use those constants to compare with the returned button number in the application. For example,

 if (anEvent.getButton() == JmriMouseEvent.BUTTON1) {
 

In particular, for a mouse with one, two, or three buttons this method may return the following values:

• 0 (NOBUTTON)
• 1 (BUTTON1)
• 2 (BUTTON2)
• 3 (BUTTON3)

Button numbers greater than BUTTON3 have no constant identifier. So if a mouse with five buttons is installed, this method may return the following values:

• 0 (NOBUTTON)
• 1 (BUTTON1)
• 2 (BUTTON2)
• 3 (BUTTON3)
• 4
• 5

Note: If support for extended mouse buttons is disabled by Java then the AWT event subsystem does not produce mouse events for the extended mouse buttons. So it is not expected that this method returns anything except NOBUTTON, BUTTON1, BUTTON2, BUTTON3.

Returns:

one of the values from 0 to MouseInfo.getNumberOfButtons() if support for the extended mouse buttons is enabled by Java. That range includes NOBUTTON, BUTTON1, BUTTON2, BUTTON3;
NOBUTTON, BUTTON1, BUTTON2 or BUTTON3 if support for the extended mouse buttons is disabled by Java

Since:

1.4

See Also:

• Toolkit.areExtraMouseButtonsEnabled()
• MouseInfo.getNumberOfButtons()
• MouseEvent(Component, int, long, int, int, int, int, int, int, boolean, int)
• InputEvent.getMaskForButton(int)

isPopupTrigger

public boolean isPopupTrigger()

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

getMouseModifiersText

public static String getMouseModifiersText(int modifiers)

Returns a String instance describing the modifier keys and mouse buttons that were down during the event, such as "Shift", or "Ctrl+Shift". These strings can be localized by changing the awt.properties file.

Note that the InputEvent.ALT_MASK and InputEvent.BUTTON2_MASK have equal values, so the "Alt" string is returned for both modifiers. Likewise, the InputEvent.META_MASK and InputEvent.BUTTON3_MASK have equal values, so the "Meta" string is returned for both modifiers.

Note that passing negative parameter is incorrect, and will cause the returning an unspecified string. Zero parameter means that no modifiers were passed and will cause the returning an empty string.

Parameters:

modifiers - A modifier mask describing the modifier keys and mouse buttons that were down during the event

Returns:

string string text description of the combination of modifier keys and mouse buttons that were down during the event

Since:

1.4

See Also:

• InputEvent.getModifiersExText(int)

paramString

public String paramString()

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

isShiftDown

public boolean isShiftDown()

Returns whether or not the Shift modifier is down on this event.

Returns:

whether or not the Shift modifier is down on this event

isControlDown

public boolean isControlDown()

Returns whether or not the Control modifier is down on this event.

Returns:

whether or not the Control modifier is down on this event

isMetaDown

public boolean isMetaDown()

Returns whether or not the Meta modifier is down on this event. The meta key was until Java 8 the right mouse button on Windows. On Java 9 on Windows 10, there is no more meta key. Note that this method is called both on mouse button events and mouse move events, and therefore "event.getButton() == JmriMouseEvent.BUTTON3" doesn't work. As of Java 11, the meta key process has changed. The getModifiersEx() value will vary when button 3 is used, depending on the mouse event. mousePressed :: 4096 (button 3) mouseDragged :: 4096 mouseReleased :: 256 (meta) mouseClicked :: 256 The meta value is simulated by Java for Linux and Windows based on button 3 being active.

Returns:

whether or not the Meta modifier is down on this event

isAltDown

public boolean isAltDown()

Returns whether or not the Alt modifier is down on this event.

Returns:

whether or not the Alt modifier is down on this event

isAltGraphDown

public boolean isAltGraphDown()

Returns whether or not the AltGraph modifier is down on this event.

Returns:

whether or not the AltGraph modifier is down on this event

getWhen

public long getWhen()

Returns the difference in milliseconds between the timestamp of when this event occurred and midnight, January 1, 1970 UTC.

Returns:

the difference in milliseconds between the timestamp and midnight, January 1, 1970 UTC

getModifiers

@Deprecated(since="9")
public int getModifiers()

Deprecated.

It is recommended that extended modifier keys and getModifiersEx() be used instead

Returns the modifier mask for this event.

Returns:

the modifier mask for this event

getModifiersEx

public int getModifiersEx()

Returns the extended modifier mask for this event.

Extended modifiers are the modifiers that ends with the _DOWN_MASK suffix, such as ALT_DOWN_MASK, BUTTON1_DOWN_MASK, and others.

Extended modifiers represent the state of all modal keys, such as ALT, CTRL, META, and the mouse buttons just after the event occurred.

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:

    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:
 

It is not recommended to compare the return value of this method using == because new modifiers can be added in the future. For example, the appropriate way to check that SHIFT and BUTTON1 are down, but CTRL is up is demonstrated by the following code:

    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
    int offmask = CTRL_DOWN_MASK;
    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
        ...
    }
 

The above code will work even if new modifiers are added.

Returns:

the extended modifier mask for this event

Since:

1.4

getComponent

public Component getComponent()

Returns the originator of the event.

Returns:

the Component object that originated the event, or null if the object is not a Component.

getSource

public Object getSource()

The object on which the Event initially occurred.

Returns:

the object on which the Event initially occurred

consume

public void consume()

Consumes this event so that it will not be processed in the default manner by the source which originated it.