8389551: Update class docs of MouseEvent by nlisker · Pull Request #2238 · openjdk/jfx

nlisker · 2026-08-01T01:03:59Z

Adds a section for button events and clarifies the existing sections.

I confirm that I make this contribution in accordance with the OpenJDK Interim AI Policy.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Author)

Issue

JDK-8389551: Update class docs of MouseEvent (Enhancement - P4)(⚠️ The fixVersion in this issue is [jfx27] but the fixVersion in .jcheck/conf is jfx28, a new backport will be created when this pr is integrated.)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jfx.git pull/2238/head:pull/2238
$ git checkout pull/2238

Update a local copy of the PR:
$ git checkout pull/2238
$ git pull https://git.openjdk.org/jfx.git pull/2238/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2238

View PR using the GUI difftool:
$ git pr show -t 2238

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jfx/pull/2238.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2026-08-01T01:04:40Z

👋 Welcome back nlisker! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2026-08-01T01:05:55Z

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

nlisker · 2026-08-01T01:12:37Z

Notes to reviewers:

I didn't have a touch screen available for this, so I couldn't verify that the parts that talk about touch screens is correct.
When testing, I couldn't reproduce the behavior described in the last paragraph for entered/exited events, namely that MOUSE_ENTERED_TARGET and MOUSE_ENTERED can be handled by the same event handler, or that consuming one event stops the other. I didn't try too hard to make it work; I went by what the user will probably try to do. I kept it in this version assuming it's correct somehow.
I used the following small tester:

import javafx.application.Application;
import javafx.scene.Node;
import javafx.scene.Scene;
import javafx.scene.input.ClipboardContent;
import javafx.scene.input.Dragboard;
import javafx.scene.input.InputEvent;
import javafx.scene.input.MouseEvent;
import javafx.scene.input.TransferMode;
import javafx.scene.layout.HBox;
import javafx.scene.layout.VBox;
import javafx.scene.paint.Color;
import javafx.scene.shape.Rectangle;
import javafx.stage.Stage;

public class MouseTest extends Application {

    public static void main(String[] args) {
        launch(args);
    }

    @Override
    public void start(@SuppressWarnings("exports") Stage stage) throws Exception {

        var scene = createScene(createSourcePDR(), createSourceMouseFullPDR(), createSourceDnD(), createTarget());
        stage.setScene(scene);
        stage.show();
    }

    private Rectangle createSourcePDR() {
        var source = new Rectangle(50, 50);
        source.setId("PDR");
        source.setFill(Color.YELLOW);
        source.setOnDragDetected(e -> {
            print(source, e);
            e.consume();
        });
        addCommonListeners(source);
        return source;
    }

    private Rectangle createSourceMouseFullPDR() {
        var source = new Rectangle(50, 50);
        source.setId("FullPDR");
        source.setFill(Color.RED);
        source.setOnDragDetected(e -> {
            source.startFullDrag();
            print(source, e);
            e.consume();
        });
        addCommonListeners(source);
        return source;
    }

    private Rectangle createSourceDnD() {
        var source = new Rectangle(50, 50);
        source.setId("DnD");
        source.setFill(Color.GREEN);
        source.setOnDragDetected(e -> {
            Dragboard db = source.startDragAndDrop(TransferMode.ANY);
            var content = new ClipboardContent();
            content.putString("");
            db.setContent(content);
            print(source, e);
            e.consume();
        });
        addCommonListeners(source);
        return source;
    }

    private Rectangle createTarget() {
        var target = new Rectangle(100, 50);
        target.setId("target");
        target.setFill(Color.BLUE);
        target.setOnDragDetected(MouseEvent::consume);
        addCommonListeners(target);
        return target;
    }

    private Scene createScene(Rectangle sourcePDR, Rectangle sourceFullPDR, Rectangle sourceDrag, Rectangle target) {
        var scene = new Scene(new VBox(10, new HBox(sourcePDR, sourceFullPDR, sourceDrag), target), 300, 200);

        scene.setOnMouseEntered(e -> System.out.println(e.getEventType() + " scene"));
        scene.setOnMouseExited(e -> System.out.println(e.getEventType() + " scene"));

        scene.setOnDragDetected(e -> {
            scene.startFullDrag();
            System.out.println(e.getEventType() + " scene");
        });

        scene.setOnDragDone(e -> {
            e.acceptTransferModes(TransferMode.ANY);
            System.out.println(e.getEventType() + " scene");
        });
        scene.setOnMouseDragReleased(e -> System.out.println(e.getEventType() + " scene"));
        scene.setOnMouseDragDone(e -> System.out.println(e.getEventType() + " scene"));
        return scene;
    }

    private static void addCommonListeners(Node node) {
        // MouseEvent
        node.setOnMouseMoved(e -> print(node, e));
        node.setOnMouseDragged(e -> print(node, e));
        node.setOnMouseEntered(e -> print(node, e));
        node.setOnMouseExited(e -> print(node, e));
        node.setOnMousePressed(e -> print(node, e));
        node.setOnMouseReleased(e -> print(node, e));
        node.setOnMouseClicked(e -> print(node, e));
        node.addEventHandler(MouseEvent.MOUSE_ENTERED_TARGET, e -> {
            System.out.print("TARGET_ ");
            print(node, e);
        });

        // MouseDragEvent
        node.setOnMouseDragOver(e -> print(node, e));
        node.setOnMouseDragEntered(e -> print(node, e));
        node.setOnMouseDragExited(e -> print(node, e));
        node.setOnMouseDragReleased(e -> print(node, e));
        node.setOnMouseDragDone(e -> System.out.println(e.getEventType() + " " + node.getId()));

        // DragEvent
        node.setOnDragOver(e -> {
            e.acceptTransferModes(TransferMode.ANY);
            print(node, e);
        });
        node.setOnDragEntered(e -> {
            e.acceptTransferModes(TransferMode.ANY);
            print(node, e);
        });
        node.setOnDragExited(e -> {
            print(node, e);
        });
        node.setOnDragDropped(e -> {
            e.acceptTransferModes(TransferMode.ANY);
            e.setDropCompleted(true);
            print(node, e);
        });
        node.setOnDragDone(e -> {
            e.acceptTransferModes(TransferMode.ANY);
            print(node, e);
        });
    }

    private static void print(Node node, InputEvent e) {
        System.out.println(e.getEventType() + " " + node.getId());
    }
}

nlisker · 2026-08-01T01:14:24Z

/reviewers 2

@andy-goryachev-oracle @kevinrushforth please review. This is a docs-only change that can go into 27.

openjdk · 2026-08-01T01:15:02Z

@nlisker
The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 1 Reviewer, 1 Author).

mlbridge · 2026-08-01T01:18:59Z

Webrevs

andy-goryachev-oracle

The new diagram is a nice addition (I am not sure if "DRAG_DETECTED" node should be a rhombus since it's a decision node (according to https://en.wikipedia.org/wiki/Flowchart )

The textual changes I like much less, mainly because the old one is more useful, in my opinion, since it describes what actually happens.

andy-goryachev-oracle · 2026-08-03T17:50:48Z

+/// [mouseTransparent][javafx.scene.Node#mouseTransparentProperty()] set to `true` do not receive mouse events.
+///
+/// ## Button events
+/// A mouse button can be [pressed][#MOUSE_PRESSED] and [released][#MOUSE_RELEASED]. A button [click][#MOUSE_CLICKED]


it sounds like press-drag-release gesture might produce a MOUSE_CLICKED event. can you clarify?

also, we probably should mention that the MOUSE_CLICKED arrives after the MOUSE_RELEASED, either here or in the MOUSE_CLICKED javadoc.

it sounds like press-drag-release gesture might produce a MOUSE_CLICKED event. can you clarify?

Both simple PDR and full-PDR can produce MOUSE_CLICKED. Do you want me to explicitly state it? In the section about drag events, it's shown that both end with a release event, so it is implied that it produces a click, but I can add that info.

click: "A button click occurs after these happen" -> "may follow MOUSE_RELEASED" to be specific. I recall at some point I thought it was press->click->release.

there is no MOUSE_CLICKED in your diagram, plus I can't figure out how a click can be generated during the drag operation.

I can't figure out how a click can be generated during the drag operation.

Using the test program above, just start a PDR or a full-PDR and release the mouse over the same node. For PDR I get:

MOUSE_PRESSED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR DRAG_DETECTED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_DRAGGED PDR MOUSE_RELEASED PDR MOUSE_CLICKED PDR

For full-PDR I get:

MOUSE_PRESSED FullPDR MOUSE_DRAGGED FullPDR MOUSE_DRAGGED FullPDR MOUSE_DRAGGED FullPDR MOUSE_DRAGGED FullPDR MOUSE_DRAGGED FullPDR DRAG_DETECTED FullPDR MOUSE_DRAGGED FullPDR MOUSE-DRAG_ENTERED FullPDR MOUSE-DRAG_OVER FullPDR MOUSE_DRAGGED FullPDR MOUSE-DRAG_OVER FullPDR MOUSE_DRAGGED FullPDR MOUSE-DRAG_OVER FullPDR MOUSE-DRAG_RELEASED FullPDR MOUSE-DRAG_RELEASED scene MOUSE-DRAG_DONE FullPDR MOUSE-DRAG_DONE scene MOUSE_RELEASED FullPDR MOUSE_CLICKED FullPDR MOUSE-DRAG_EXITED FullPDR

1. "may follow MOUSE_RELEASED"

When does it not?

2. there is no MOUSE_CLICKED in your diagram

I can add it, but the diagram is for drag-related events. After the mouse release event, the important part is if there's an event for ending the drag. A click event is not part of it.

andy-goryachev-oracle · 2026-08-03T19:11:49Z

+///
+/// There are 3 types of drag gestures that can be chosen from within the `DRAG_DETECTED` handler:
+///
+/// 1. Simple press-drag-release (PDR), in which the source (picked) node is the only node involved. It receives all the


"node involved" is much more nebulous than "The whole press-drag-release gesture is delivered to one node ... If a mouse clicked event is generated from these events, it is still delivered to the same node." which actually describes what is happening.

I really prefer the old description of the three types, as it is very clear, unlike the new one.

Can we revert?

I fixed the "involved" wording be removing it - the next sentence is specific ("receives all the events in the PDR gesture").

The sentence "If a mouse clicked event is generated from these events, it is still delivered to the same node." is in the next sentence "...including button events even when they occur over other nodes."

The old description is even lacking as it doesn't say that MOUSE_RELEASED events are also delivered to the node. ~~Interestingly, MOUSE_PRESSED events are not generated, I wonder if this is a bug or intended.~~ (They are delivered)

I think the main issue I have with the new version is that it removed some information that I feel is important.

for example:

The whole press-drag-release gesture is delivered to one node (removed)

and all subsequent mouse events are delivered to that same node until the button is released.

If these nodes need to be involved in the gesture, full press-drag-release gesture has to be activated. (instructs what the app dev is supposed to do)

Also, in the new version:

DRAG_DETECTED handler: what handler? are you referring to some internal entity?

I think the old Dnd section is much more informative and easier to understand.

Please keep in mind that this is just my opinion, let's see what other people think.

I think the main issue I have with the new version is that it removed some information that I feel is important.

for example:

The whole press-drag-release gesture is delivered to one node (removed)

and all subsequent mouse events are delivered to that same node until the button is released.

I can add these, but how is it different than the current "Simple press-drag-release (PDR), in which the source (picked) node receives all the events in the PDR gesture, including click events even when they occur over other nodes."?

Perhaps I should change "all the events in the PDR gesture" to "all the events during the PDR gesture".

"until the button is released" is true for all drag gestures and is specified in the paragraph above: "Dragging ends when a mouse button is released."

If these nodes need to be involved in the gesture, full press-drag-release gesture has to be activated. (instructs what the app dev is supposed to do)

Doesn't "This gesture starts when the startFullDrag method of a node (or a scene) is invoked." tell what the developer what to do even in more detail (how to activate it)?

I can phrase it in a more conditional way, something like: "To start this gesture, the startFullDrag method of a node (or a scene) must be/has to be invoked."

Also, in the new version:

DRAG_DETECTED handler: what handler? are you referring to some internal entity?

The only mention of this in the current docs is "When you start dragging, eventually the DRAG_DETECTED event arrives. In its handler, you can either start a...", which didn't explain what handler, so why is this a new problem?

The new version says: "...at which point a [#DRAG_DETECTED] event is dispatched to the source node", which is both more precise and gives a link to the event.

I can give a link to Node#onDragDetectedProperty(), but all the docs assume that an X event is handled by an onX handler, and this one is no exception.
I can also write "DRAG_DETECTED event handler" if it adds anything.

I think the old Dnd section is much more informative and easier to understand.

Please keep in mind that this is just my opinion, let's see what other people think.

Yes, but you suggested a full revert of the textual section rather than corrections, so I take/took it that something in the explanation is done very badly. One area I need to clarify, which is was hinted to in the old docs but is phrased incorrectly in the new docs, is that the simple PDR starts before the DRAG_DETECTED event is dispatched and continues alongside a full-PDR (but not a DnD) gesture.

I just find the new version much more difficult to read and understand. Maybe it's just me.

I see now that the sentence "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." is incorrect. Nodes that are under the top-most node also receive these events (if they are not consumed). I'll clarify this too.

"node involved" is much more nebulous than "The whole press-drag-release gesture is delivered to one node ... If a mouse clicked event is generated from these events, it is still delivered to the same node." which actually describes what is happening.

The "involved" terminology was used in the original docs:

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.

I'm removed this usage.

nlisker · 2026-08-04T00:00:41Z

The new diagram is a nice addition (I am not sure if "DRAG_DETECTED" node should be a rhombus since it's a decision node (according to https://en.wikipedia.org/wiki/Flowchart )

I didn't follow any convention. If it matters, I can adjust the shapes. I assumed it would be clear after reading that section.

The textual changes I like much less, mainly because the old one is more useful, in my opinion, since it describes what actually happens.

I found the old ones to be confusing at best. Some specifics:

The methods that start the different drag gestures are not written in the description of each of them; they first appear in the summary, which should be... a summary, not add new information.
The summary is long compared to the paragraphs that describe the drag gestures - it's longer than the descriptions of full-PDR and DnD combined. A summary should be short (I turned it into a table).
The paragraph that describes full-PDR doesn't start with talking about full-PDR, it continues with (simple) PDR: "During a simple press-drag-release gesture, the other nodes are not involved and don't get any events." (which repeats "The whole press-drag-release gesture is delivered to one node." from its own paragraph). It's not clear that it's supposed to introduce another gesture type.
The second paragraph also doesn't say that this is the second gesture type, you get to the DnD paragraph and it starts with "The third gesture type"; where was the second?
The DnD paragraph is very terse and doesn't give an example of what it could be used for, unlike the previous paragraphs.

Which lines that describe "what actually happens" are missing? It's probably easier to just add them than just revert.

andy-goryachev-oracle · 2026-08-04T17:50:58Z

+/// `MOUSE_ENTERED`.
+/// 3. During the bubbling phase, its type is switched back to `MOUSE_ENTERED_TARGET`.
+///
+/// If the event is filtered or consumed, it affects both event types.


how? what happens?

this gives very little information.

this gives very little information.

This was the original: "It's still one event just switching types, so if it's filtered or consumed, it affects both event variants."

It gives the same information, only less accurately ("variants" is not an established term).

how? what happens?

For "how?", I added a link to consume(). As for "what happens?", it depends on what change was made.

andy-goryachev-oracle · 2026-08-04T17:58:35Z

+/// This means that a node can receive these events when the mouse enters a node in its scenegraph hierarchy. To
+/// distinguish between these two cases, the event target can be tested on equality with the node.
+///
+/// Since `MOUSE_ENTERED`/`MOUSE_EXITED` are subtypes of `MOUSE_ENTERED_TARGET`/`MOUSE_EXITED_TARGET`, they are also


the "subtype" thing is present in the original doc and is quite confusing: aren't those distinct types?
maybe instead we should just rephrase the whole thing saying the *TARGET events are delivered to parents while the ENTERED/EXITED ones to the target node only?

the original phrase "It's still one event just switching types" actually explains the whole thing better.

the "subtype" thing is present in the original doc and is quite confusing: aren't those distinct types?

All the events are distinct from a proper Java language perspective (no extends), but they hold information about their "event supertype":

EventType<MouseEvent> MOUSE_ENTERED_TARGET = new EventType<>(MouseEvent.ANY, "MOUSE_ENTERED_TARGET"); EventType<MouseEvent> MOUSE_ENTERED = new EventType<>(MouseEvent.MOUSE_ENTERED_TARGET, "MOUSE_ENTERED");

The first argument is superType, so MOUSE_ENTERED is a subtype of MOUSE_ENTERED_TARGET in the event system. Don't get me started on what I think about this design :)

now I see it, thanks!

I wonder if we could link to the EventType(EventType) constructor when we talk about subtypes, something like this:

are {@link EventType#EventType(EventType) subtypes} of

nlisker · 2026-08-11T18:30:24Z

Updated both sections with clarifications and corrections.

I noticed that the recomputeCoordinatesToSource(MouseEvent oldEvent, Object newSource) method does not use oldEvent, which might be a bug. I didn't investigate much.

andy-goryachev-oracle

Nir, I am sorry. I think we need a fresh pair of eyes to give constructive criticism. I am afraid I prefer the old version - perhaps with some clarifications - but the new version does not bring happiness. It could be just me, so perhaps someone else could chime in.

andy-goryachev-oracle · 2026-08-11T21:51:32Z

@@ -25,106 +25,137 @@

 package javafx.scene.input;


this comment applies to mouse_events.svg (I don't know how to annotate the image in github). sorry to say that, but it has many issues.

MOUSE_DRAGGED: remove side line (it's not a fork)

"exit hist. area?" - decision point, so it should have two outcomes (yes and no), 2 lines

DRAG_DETECTED: again, only one line down

rhombus with some kind of check, and 3 outgoing lines: DragAndDrop path, FullDrag path, and one that leads to MOUSE_DRAGGED. I'd think the rhombus should name the criteria and all three outcomes need proper labels.

kevinrushforth · 2026-08-13T22:25:10Z

I can take a look. I also request @arapte to take a look.

Given that there is likely to be a little further discussion, I recommend targeting the JBS issue to jfx28 since it isn't clear whether this will make jfx27 or not.

Initial commit

98aa72f

nlisker marked this pull request as ready for review August 1, 2026 01:12

openjdk Bot added the rfr Ready for review label Aug 1, 2026

andy-goryachev-oracle reviewed Aug 3, 2026

View reviewed changes

Review clarifications

4b6503b

andy-goryachev-oracle reviewed Aug 4, 2026

View reviewed changes

nlisker added 3 commits August 5, 2026 16:04

Remove unused import

ae12050

Update drag gesture section

06326b0

Added clarifications for the Movement section

217d387

andy-goryachev-oracle reviewed Aug 11, 2026

View reviewed changes

kevinrushforth self-requested a review August 13, 2026 22:23

Uh oh!

Conversation

nlisker commented Aug 1, 2026 • edited by openjdk Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewing

Uh oh!

bridgekeeper Bot commented Aug 1, 2026

Uh oh!

openjdk Bot commented Aug 1, 2026

Uh oh!

nlisker commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nlisker commented Aug 1, 2026

Uh oh!

openjdk Bot commented Aug 1, 2026

Uh oh!

mlbridge Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

andy-goryachev-oracle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlisker Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlisker Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlisker commented Aug 4, 2026

Uh oh!

andy-goryachev-oracle Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlisker commented Aug 11, 2026

Uh oh!

andy-goryachev-oracle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinrushforth commented Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

nlisker commented Aug 1, 2026 •

edited by openjdk Bot

Loading

nlisker commented Aug 1, 2026 •

edited

Loading

mlbridge Bot commented Aug 1, 2026 •

edited

Loading

nlisker Aug 4, 2026 •

edited

Loading

nlisker Aug 10, 2026 •

edited

Loading

andy-goryachev-oracle Aug 4, 2026 •

edited

Loading