Class MouseEvent

java.lang.Object
java.util.EventObject
javafx.event.Event
javafx.scene.input.InputEvent
javafx.scene.input.MouseEvent
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
MouseDragEvent
public class MouseEvent extends InputEvent
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

Since:
JavaFX 2.0
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final EventType<MouseEvent>
    ANY
    Common supertype for all mouse event types.
    static final EventType<MouseEvent>
    DRAG_DETECTED
    This event is delivered to a node that is identified as a source of a dragging gesture.
    static final EventType<MouseEvent>
    MOUSE_CLICKED
    This event occurs when a mouse button has been clicked (pressed and released on the same node).
    static final EventType<MouseEvent>
    MOUSE_DRAGGED
    This event occurs when the mouse moves with a pressed button.
    static final EventType<MouseEvent>
    MOUSE_ENTERED
    This event occurs when the mouse enters a node.
    static final EventType<MouseEvent>
    MOUSE_ENTERED_TARGET
    This event occurs when the mouse enters a node.
    static final EventType<MouseEvent>
    MOUSE_EXITED
    This event occurs when the mouse exits a node.
    static final EventType<MouseEvent>
    MOUSE_EXITED_TARGET
    This event occurs when the mouse exits a node.
    static final EventType<MouseEvent>
    MOUSE_MOVED
    This event occurs when the mouse moves within a node and no buttons are pressed.
    static final EventType<MouseEvent>
    MOUSE_PRESSED
    This event occurs when a mouse button is pressed.
    static final EventType<MouseEvent>
    MOUSE_RELEASED
    This event occurs when a mouse button is released.

    Fields declared in class javafx.event.Event

    consumed, eventType, NULL_SOURCE_TARGET, target

    Fields declared in class java.util.EventObject

    source

  • Constructor Summary

    Constructors
    Constructor
    Description
    MouseEvent(Object source, EventTarget target, EventType<? extends MouseEvent> eventType, double x, double y, double screenX, double screenY, MouseButton button, int clickCount, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown, boolean backButtonDown, boolean forwardButtonDown, boolean synthesized, boolean popupTrigger, boolean stillSincePress, PickResult pickResult)
    Constructs new MouseEvent event.
    MouseEvent(Object source, EventTarget target, EventType<? extends MouseEvent> eventType, double x, double y, double screenX, double screenY, MouseButton button, int clickCount, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown, boolean synthesized, boolean popupTrigger, boolean stillSincePress, PickResult pickResult)
    Constructs new MouseEvent event.
    MouseEvent(EventType<? extends MouseEvent> eventType, double x, double y, double screenX, double screenY, MouseButton button, int clickCount, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown, boolean backButtonDown, boolean forwardButtonDown, boolean synthesized, boolean popupTrigger, boolean stillSincePress, PickResult pickResult)
    Constructs new MouseEvent event with null source and target.
    MouseEvent(EventType<? extends MouseEvent> eventType, double x, double y, double screenX, double screenY, MouseButton button, int clickCount, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown, boolean synthesized, boolean popupTrigger, boolean stillSincePress, PickResult pickResult)
    Constructs new MouseEvent event with null source and target.

  • Method Summary

    Modifier and Type
    Method
    Description
    MouseEvent
    copyFor(Object newSource, EventTarget newTarget)
    Copies this event for a different source and target.
    MouseEvent
    copyFor(Object newSource, EventTarget newTarget, EventType<? extends MouseEvent> eventType)
    Creates a copy of the given event with the given fields substituted.
    static MouseDragEvent
    copyForMouseDragEvent(MouseEvent e, Object source, EventTarget target, EventType<MouseDragEvent> type, Object gestureSource, PickResult pickResult)
    Creates a copy of this mouse event of MouseDragEvent type
    final MouseButton
    getButton()
    Which, if any, of the mouse buttons is responsible for this event.
    final int
    getClickCount()
    Returns number of mouse clicks associated with this event.
    EventType<? extends MouseEvent>
    getEventType()
    Gets the event type of this event.
    final PickResult
    getPickResult()
    Returns information about the pick.
    final double
    getSceneX()
    Returns horizontal position of the event relative to the origin of the Scene that contains the MouseEvent's source.
    final double
    getSceneY()
    Returns vertical position of the event relative to the origin of the Scene that contains the MouseEvent's source.
    final double
    getScreenX()
    Returns absolute horizontal position of the event.
    final double
    getScreenY()
    Returns absolute vertical position of the event.
    final double
    getX()
    Horizontal position of the event relative to the origin of the MouseEvent's source.
    final double
    getY()
    Vertical position of the event relative to the origin of the MouseEvent's source.
    final double
    getZ()
    Depth position of the event relative to the origin of the MouseEvent's source.
    final boolean
    isAltDown()
    Whether or not the Alt modifier is down on this event.
    final boolean
    isBackButtonDown()
    Returns true if back button (button 4) is currently pressed.
    final boolean
    isControlDown()
    Whether or not the Control modifier is down on this event.
    boolean
    isDragDetect()
    Determines whether this event will be followed by DRAG_DETECTED event.
    final boolean
    isForwardButtonDown()
    Returns true if forward button (button 5) is currently pressed.
    final boolean
    isMetaDown()
    Whether or not the Meta modifier is down on this event.
    final boolean
    isMiddleButtonDown()
    Returns true if middle button (button 2) is currently pressed.
    final boolean
    isPopupTrigger()
    Returns true if this mouse event is the popup menu trigger event for the platform.
    final boolean
    isPrimaryButtonDown()
    Returns true if primary button (button 1, usually the left) is currently pressed.
    final boolean