Re: RFR: 8389551: Update class docs of MouseEvent

[Nir Lisker]

On Sat, 1 Aug 2026 01:03:59 GMT, Nir Lisker <nlis...@openjdk.org> wrote:

> Adds a section for button events and clarifies the existing sections.
> 
> ---------
> - [x] I confirm that I make this contribution in accordance with the [OpenJDK 
> Interim AI Policy](https://openjdk.org/legal/ai).

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.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());
    }
}

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

-------------

PR Comment: https://git.openjdk.org/jfx/pull/2238#issuecomment-5148789449
PR Comment: https://git.openjdk.org/jfx/pull/2238#issuecomment-5148798297