Summary

Establishes a public API for focus traversal within a JavaFX application.

Problem

While focus traversal is currently implemented in JavaFX, there is no public API to access it. The lack of public API makes it impossible for a custom skin or custom control to support focus traversal in the specific direction.

Solution

The focus traversal is provided adding a single method to the Node class:

public final boolean requestFocusTraversal(TraversalDirection direction)

where TraversalDirection enumerates the search direction relative to the current node [1].

Typically, controls do not need to handle focus traversal keys explicitly, relying instead on the built-in traversal logic, unless:

• the traversal is conditional upon the state of the control
• the key used to traverse is used in a non-traversal capacity (one example is the tab key in the context of a text editor)

The following example illustrates the use of new API in the context of a text editor conditionally handling of the tab key:

    Node from = ...
    KeyEvent ev = ...
    if (!ev.isAltDown() && !ev.isControlDown() && !ev.isMetaDown() && !ev.isShiftDown() && !ev.isShortcutDown()) {
        switch (ev.getCode()) {
        case TAB:
            if (isEditable()) {
                insertTab();
            } else {
                from.requestFocusTraversal(TraversalDirection.NEXT);
            }
            ev.consume();
            break;
        }
    }

Specification

modules/javafx.graphics/src/main/java/javafx/scene/Node.java:

+    /**
+     * Requests to move the focus from this {@code Node} in the specified direction.
+     * The {@code Node} serves as a reference point and does not have to be focused or focusable.
+     * A successful traversal results in a new {@code Node} being focused.
+     * <p>
+     * This method is expected to be called in response to a {@code KeyEvent}; therefore the {@code Node}
+     * receiving focus will have the {@link #focusVisibleProperty() focusVisible} property set.
+     *
+     * @param direction the direction of focus traversal, non-null
+     * @return {@code true} if traversal was successful
+     * @since 24
+     */
+    public final boolean requestFocusTraversal(TraversalDirection direction)

modules/javafx.graphics/src/main/java/javafx/scene/TraversalDirection.java:

+/**
+ * Specifies the direction of focus traversal.
+ *
+ * @since 24
+ * @see Node#requestFocusTraversal(TraversalDirection)
+ */
+public enum TraversalDirection {
+    /** Indicates a focus change to the node below the currently focused node. */
+    DOWN,
+    /** Indicates a focus change to the node to the left of the currently focused node. */
+    LEFT,
+    /** Indicates a focus change to the next focusable node. */
+    NEXT,
+    /** Indicates a focus change to the previous focusable node. */
+    PREVIOUS,
+    /** Indicates a focus change to the node to the right of the currently focused node. */
+    RIGHT,
+    /** Indicates a focus change to the node above the currently focused node. */
+    UP;
+}

REFERENCES

JavaFX JEP: https://github.com/andy-goryachev-oracle/Test/blob/main/doc/FocusTraversal/FocusTraversal-v3.md