RFR: 8343956: Focus delegation API

[Michael Strauß]

On Sat, 9 Nov 2024 01:28:53 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

> Implementation of [focus delegation](https://gist.github.com/mstr2/44d94f0bd5b5c030e26a47103063aa29).

Dispatching an event in the presence of focus delegation is slightly different, because it requires cooperation of the `Node` that is the event target. Previously, we would dispatch an event like this:

EventUtil.fireEvent(EventTarget, Event);


With focus delegation, we need to know what the final delegate will be, and we dispatch the event like this:

EventUtil.fireEvent(EventTarget firstTarget, EventTarget finalDelegate, Event event);


Of course, this is internal code that can only be called within the `Node` class (as only `Node` knows its final delegate). But we need a way for users to correctly dispatch an event without knowing `Node` internals. [JDK-8303209](https://bugs.openjdk.org/browse/JDK-8303209) comes in handy here, so I've pulled that proposal into this feature.

Old code like `Event.fireEvent(EventTarget, Event)` is simply redefined to call `EventTarget.dispatchEvent(Event)`, ensuring that the overridden implementation `Node.dispatchEvent(Event)` is called. This ensures that events are always fired correctly.

Note that it is not enough to manually construct an event dispatch chain with `EventTarget.buildEventDispatchChain(EventDispatchChain)`, and call `EventDispatchChain.dispatchEvent(Event)` on it. This skips the very important step of setting the correct delegation target. I've added documentation to the existing method, clarifying that it should not be used by application developers. There is no reason to use it in any case, since we now have the `EventTarget.dispatchEvent(Event)` method instead.

This PR is now ready for review. We should finish the discussion of whether we want to have this feature in JavaFX. If we decide to go ahead, it is not required to migrate all controls to use focus delegation at the same time. This PR includes the `Spinner` control as an example, and more controls can be migrated step by step.

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

PR Comment: https://git.openjdk.org/jfx/pull/1632#issuecomment-3043468451
PR Comment: https://git.openjdk.org/jfx/pull/1632#issuecomment-3043469192