JavaFX 24 · javafx.scene.input.MouseEvent · APIdia, the JavaDoc alternative

When a mouse event occurs, the top-most node under cursor is picked and the event is delivered to it through capturing and bubbling phases described at EventDispatcher.

The mouse (pointer's) location is available relative to several coordinate systems: x,y - relative to the origin of the MouseEvent's node, sceneX,sceneY - relative to to the origin of the Scene that contains the node, screenX,screenY - relative to origin of the screen that contains the mouse pointer.

Dragging gestures

There are three types of dragging gestures. They are all initiated by a mouse press event and terminated as a result of a mouse released event, the source node decides which gesture will take place.

The simple press-drag-release gesture is the default. It's best used to allow changing the size of a shape, dragging it around and so on. The whole press-drag-release gesture is delivered to one node. When a mouse button is pressed, the top-most node is picked and all subsequent mouse events are delivered to that same node until the button is released. If a mouse clicked event is generated from these events, it is still delivered to the same node.

During a simple press-drag-release gesture, the other nodes are not involved and don't get any events. If these nodes need to be involved in the gesture, full press-drag-release gesture has to be activated. This gesture is best used for connecting nodes by "wires", dragging nodes to other nodes etc. This gesture type is more closely described at MouseDragEvent which contains the events delivered to the gesture targets.

The third gesture type is the platform-supported drag-and-drop gesture. It serves best to transfer data and works also between (not necessarily FX) applications. This gesture type is more closely described at DragEvent.

In summary, simple press-drag-release gestures are activated automatically when a mouse button is pressed and delivers all MouseEvents to the gesture source. When you start dragging, eventually the DRAG_DETECTED event arrives. In its handler, you can either start a full press-drag-release gesture by calling the startFullDrag method on a node or scene - the MouseDragEvents start to be delivered to gesture targets, or you can start drag and drop gesture by calling startDragAndDrop method on a node or scene - the system switches into the drag and drop mode and DragEvents start to be delivered instead of MouseEvents. If you don't call any of those methods, the simple press-drag-release gesture continues.

Note that dragging a finger over touch screen produces mouse dragging events, but also scroll gesture events. If it means a conflict in an application (the physical dragging action is handled by two different handlers), the isSynthesized() method may be used to detect the problem and make the dragging handlers behave accordingly.

Mouse enter/exit handling

When the mouse enters a node, the node gets a MOUSE_ENTERED event, when it leaves, it gets a MOUSE_EXITED event. These events are delivered only to the entered/exited node and seemingly don't go through the capturing/bubbling phases. This is the most common use-case.

When capturing or bubbling is desired, there are MOUSE_ENTERED_TARGET/MOUSE_EXITED_TARGET events. These events go through capturing/bubbling phases normally. This means that a parent may receive the MOUSE_ENTERED_TARGET event when the mouse entered either the parent itself or some of its children. To distinguish between these two cases, the event target can be tested on equality with the node.

These two types are closely connected: MOUSE_ENTERED/MOUSE_EXITED are subtypes of MOUSE_ENTERED_TARGET/MOUSE_EXITED_TARGET. During capturing phase, MOUSE_ENTERED_TARGET is delivered to the parents. When the event is delivered to the event target (the node that has actually been entered), its type is switched to MOUSE_ENTERED. Then the type is switched back to MOUSE_ENTERED_TARGET for the bubbling phase. It's still one event just switching types, so if it's filtered or consumed, it affects both event variants. Thanks to the subtype-relationship, a MOUSE_ENTERED_TARGET event handler will receive the MOUSE_ENTERED event on target.

Notes

For triggering context menus see the ContextMenuEvent.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	MouseEvent.Flags These properties need to live in a separate object shared among all the copied events to make sure that the values are propagated to the original event.

Field Summary

Modifier and Type	Field and Description
private final boolean	altDown Whether or not the Alt modifier is down on this event.
public static final EventType<MouseEvent>	ANY Hides javafx.scene.input.InputEvent.ANY. Common supertype for all mouse event types.
private final boolean	backButtonDown `true` if back button (button 4) is currently pressed.
private final MouseButton	button Which, if any, of the mouse buttons is responsible for this event.
private final int	clickCount Number of mouse clicks associated with this event.
private final boolean	controlDown Whether or not the Control modifier is down on this event.
public static final EventType<MouseEvent>	DRAG_DETECTED This event is delivered to a node that is identified as a source of a dragging gesture.
private final MouseEvent.Flags	flags
private final boolean	forwardButtonDown `true` if forward button (button 5) is currently pressed.
private final boolean	metaDown Whether or not the Meta modifier is down on this event.
private final boolean	middleButtonDown `true` if middle button (button 2) is currently pressed.
public static final EventType<MouseEvent>	MOUSE_CLICKED This event occurs when a mouse button has been clicked (pressed and released on the same node).
public static final EventType<MouseEvent>	MOUSE_DRAGGED This event occurs when the mouse moves with a pressed button.
public static final EventType<MouseEvent>	MOUSE_ENTERED This event occurs when the mouse enters a node.
public static final EventType<MouseEvent>	MOUSE_ENTERED_TARGET This event occurs when the mouse enters a node.
public static final EventType<MouseEvent>	MOUSE_EXITED This event occurs when the mouse exits a node.
public static final EventType<MouseEvent>	MOUSE_EXITED_TARGET This event occurs when the mouse exits a node.
public static final EventType<MouseEvent>	MOUSE_MOVED This event occurs when the mouse moves within a node and no buttons are pressed.
public static final EventType<MouseEvent>	MOUSE_PRESSED This event occurs when a mouse button is pressed.
public static final EventType<MouseEvent>	MOUSE_RELEASED This event occurs when a mouse button is released.
private PickResult	pickResult Information about the pick if the picked `Node` is a `Shape3D` node and its pickOnBounds is false.
private final boolean	popupTrigger Whether or not this mouse event is the popup menu trigger event for the platform.
private final boolean	primaryButtonDown `true` if primary button (button 1, usually the left) is currently pressed.
private final double	sceneX Horizontal x position of the event relative to the origin of the `Scene` that contains the MouseEvent's node.
private final double	sceneY Vertical y position of the event relative to the origin of the `Scene` that contains the MouseEvent's node.
private final double	screenX Absolute horizontal x position of the event.
private final double	screenY Absolute vertical y position of the event.
private final boolean	secondaryButtonDown `true` if secondary button (button 3, usually the right) is currently pressed.
private static final long	serialVersionUID Hides javafx.scene.input.InputEvent.serialVersionUID.
private final boolean	shiftDown Whether or not the Shift modifier is down on this event.
private final boolean	stillSincePress Whether the mouse cursor left the hysteresis region since the previous press.
private final boolean	synthesized
private transient double	x Horizontal x position of the event relative to the origin of the MouseEvent's node.
private transient double	y Vertical y position of the event relative to the origin of the MouseEvent's node.
private transient double	z Depth z position of the event relative to the origin of the MouseEvent's node.

Constructor Summary

Access	Constructor and Description
public	MouseEvent(EventType<? extends MouseEvent> The type of the event. eventType, double The x with respect to the scene. x, double The y with respect to the scene. y, double The x coordinate relative to screen. screenX, double The y coordinate relative to screen. screenY, MouseButton the mouse button used button, int number of click counts clickCount, boolean true if shift modifier was pressed. shiftDown, boolean true if control modifier was pressed. controlDown, boolean true if alt modifier was pressed. altDown, boolean true if meta modifier was pressed. metaDown, boolean true if primary button was pressed. primaryButtonDown, boolean true if middle button was pressed. middleButtonDown, boolean true if secondary button was pressed. secondaryButtonDown, boolean if this event was synthesized synthesized, boolean whether this event denotes a popup trigger for current platform popupTrigger, boolean see `isStillSincePress()` stillSincePress, PickResult pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates pickResult) Constructs new MouseEvent event with null source and target.
public	MouseEvent(EventType<? extends MouseEvent> The type of the event. eventType, double The x with respect to the scene. x, double The y with respect to the scene. y, double The x coordinate relative to screen. screenX, double The y coordinate relative to screen. screenY, MouseButton the mouse button used button, int number of click counts clickCount, boolean true if shift modifier was pressed. shiftDown, boolean true if control modifier was pressed. controlDown, boolean true if alt modifier was pressed. altDown, boolean true if meta modifier was pressed. metaDown, boolean true if primary button was pressed. primaryButtonDown, boolean true if middle button was pressed. middleButtonDown, boolean true if secondary button was pressed. secondaryButtonDown, boolean true if back button was pressed. backButtonDown, boolean true if forward button was pressed forwardButtonDown, boolean if this event was synthesized synthesized, boolean whether this event denotes a popup trigger for current platform popupTrigger, boolean see `isStillSincePress()` stillSincePress, PickResult pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates pickResult) Constructs new MouseEvent event with null source and target.
public	MouseEvent(Object the source of the event. Can be null. source, EventTarget the target of the event. Can be null. target, EventType<? extends MouseEvent> The type of the event. eventType, double The x with respect to the source. Should be in scene coordinates if source == null or source is not a Node. x, double The y with respect to the source. Should be in scene coordinates if source == null or source is not a Node. y, double The x coordinate relative to screen. screenX, double The y coordinate relative to screen. screenY, MouseButton the mouse button used button, int number of click counts clickCount, boolean true if shift modifier was pressed. shiftDown, boolean true if control modifier was pressed. controlDown, boolean true if alt modifier was pressed. altDown, boolean true if meta modifier was pressed. metaDown, boolean true if primary button was pressed. primaryButtonDown, boolean true if middle button was pressed. middleButtonDown, boolean true if secondary button was pressed. secondaryButtonDown, boolean if this event was synthesized synthesized, boolean whether this event denotes a popup trigger for current platform popupTrigger, boolean see `isStillSincePress()` stillSincePress, PickResult pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates and target pickResult) Constructs new MouseEvent event.
public	MouseEvent(Object the source of the event. Can be null. source, EventTarget the target of the event. Can be null. target, EventType<? extends MouseEvent> The type of the event. eventType, double The x with respect to the source. Should be in scene coordinates if source == null or source is not a Node. x, double The y with respect to the source. Should be in scene coordinates if source == null or source is not a Node. y, double The x coordinate relative to screen. screenX, double The y coordinate relative to screen. screenY, MouseButton the mouse button used button, int number of click counts clickCount, boolean true if shift modifier was pressed. shiftDown, boolean true if control modifier was pressed. controlDown, boolean true if alt modifier was pressed. altDown, boolean true if meta modifier was pressed. metaDown, boolean true if primary button was pressed. primaryButtonDown, boolean true if middle button was pressed. middleButtonDown, boolean true if secondary button was pressed. secondaryButtonDown, boolean true if the back button was pressed backButtonDown, boolean true if the forward button was pressed forwardButtonDown, boolean if this event was synthesized synthesized, boolean whether this event denotes a popup trigger for current platform popupTrigger, boolean see `isStillSincePress()` stillSincePress, PickResult pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates and target pickResult) Constructs new MouseEvent event.

Method Summary

Modifier and Type	Method and Description
public MouseEvent	Returns: copy of this event for a different source and target copyFor(Object New event source newSource, EventTarget New event target newTarget) Overrides javafx.event.Event.copyFor. Copies this event for a different source and target.
public MouseEvent	Returns: the event copy with the fields substituted copyFor(Object the new source of the copied event newSource, EventTarget the new target of the copied event newTarget, EventType<? extends MouseEvent> the new eventType eventType) Creates a copy of the given event with the given fields substituted.
public static MouseDragEvent	Returns: new MouseDragEvent that was created from MouseEvent copyForMouseDragEvent(MouseEvent the mouse event to copy e, Object the new source of the copied event source, EventTarget the new target of the copied event target, EventType<MouseDragEvent> the new MouseDragEvent type type, Object the new source of the gesture gestureSource, PickResult pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates pickResult) Creates a copy of this mouse event of MouseDragEvent type
public final MouseButton	Returns: mouse button whose state change caused this event getButton() Which, if any, of the mouse buttons is responsible for this event.
public final int	Returns: number of mouse clicks associated with this event getClickCount() Returns number of mouse clicks associated with this event.
public EventType<? extends MouseEvent>	getEventType() Overrides javafx.scene.input.InputEvent.getEventType. Gets the event type of this event.
public final PickResult	Returns: new PickResult object that contains information about the pick getPickResult() Returns information about the pick.
public final double	Returns: horizontal position of the event relative to the origin of the `Scene` that contains the MouseEvent's source getSceneX() Returns horizontal position of the event relative to the origin of the `Scene` that contains the MouseEvent's source.
public final double	Returns: vertical position of the event relative to the origin of the `Scene` that contains the MouseEvent's source getSceneY() Returns vertical position of the event relative to the origin of the `Scene` that contains the MouseEvent's source.
public final double	Returns: absolute horizontal position of the event getScreenX() Returns absolute horizontal position of the event.
public final double	Returns: absolute vertical position of the event getScreenY() Returns absolute vertical position of the event.
public final double	Returns: horizontal position of the event relative to the origin of the MouseEvent's source. getX() Horizontal position of the event relative to the origin of the MouseEvent's source.
public final double	Returns: vertical position of the event relative to the origin of the MouseEvent's source. getY() Vertical position of the event relative to the origin of the MouseEvent's source.
public final double	Returns: depth position of the event relative to the origin of the MouseEvent's source. getZ() Depth position of the event relative to the origin of the MouseEvent's source.
public final boolean	Returns: true if the Alt modifier is down on this event isAltDown() Whether or not the Alt modifier is down on this event.
public final boolean	Returns: `true` if back button (button 4) is currently pressed isBackButtonDown() Returns `true` if back button (button 4) is currently pressed.
public final boolean	Returns: true if the Control modifier is down on this event isControlDown() Whether or not the Control modifier is down on this event.
public boolean	Returns: true if the `DRAG_DETECTED` event will follow isDragDetect() Determines whether this event will be followed by `DRAG_DETECTED` event.
public final boolean	Returns: `true` if forward button (button 5) is currently pressed isForwardButtonDown() Returns `true` if forward button (button 5) is currently pressed.
public final boolean	Returns: true if the Meta modifier is down on this event isMetaDown() Whether or not the Meta modifier is down on this event.
public final boolean	Returns: `true` if middle button (button 2) is currently pressed isMiddleButtonDown() Returns `true` if middle button (button 2) is currently pressed.
public final boolean	Returns: `true` if this mouse event is the popup menu trigger event for the platform isPopupTrigger() Returns `true` if this mouse event is the popup menu trigger event for the platform.
public final boolean	Returns: `true` if primary button (button 1, usually the left) is currently pressed isPrimaryButtonDown() Returns `true` if primary button (button 1, usually the left) is currently pressed.
public final boolean	Returns: `true` if secondary button (button 3, usually the right) is currently pressed isSecondaryButtonDown() Returns `true` if secondary button (button 3, usually the right) is currently pressed.
public final boolean	Returns: true if the Shift modifier is down on this event isShiftDown() Whether or not the Shift modifier is down on this event.
public final boolean	Returns: `true` if the shortcut modifier is down, `false` otherwise isShortcutDown() Returns whether or not the host platform common shortcut modifier is down on this event.
public final boolean	Returns: true if there were no significant mouse movements (out of system hysteresis area) since the last pressed event that occurred before this event. isStillSincePress() Indicates whether the mouse cursor stayed in the system-provided hysteresis area since last pressed event that occurred before this event.
public boolean	Returns: true if this event is synthesized from using a touch screen isSynthesized() Indicates whether this event is synthesized from using a touch screen instead of usual mouse event source devices like mouse or track pad.
private void	readObject(ObjectInputStream in) Hides javafx.event.Event.readObject.
pack-priv void	recomputeCoordinatesToSource(MouseEvent oldEvent, Object Source object to compute coordinates for newSource) Fills the given event by this event's coordinates recomputed to the given source object
public void	setDragDetect(boolean Whether `DRAG_DETECTED` event will follow dragDetect) Augments drag detection behavior.
public String	Returns: a string representation of this `MouseEvent` object. toString() Overrides java.util.EventObject.toString. Returns a string representation of this `MouseEvent` object.