Installs §75's Tab traversal on root, and returns the unsubscriber.
Listens for keydown on root — the bubble phase, so it hears both the
keystrokes delivered to a focused descendant and the ones delivered to root
itself when nothing is focused (see keyboardFocusTarget). Tab moves
the focus forward, Shift-Tab backward, and both call
SceneKeyEvent.preventDefault() on the way out so the host's own focus ring
does not move at the same time.
Everything else is ignored and left to propagate: this listener claims Tab
and nothing else. Auto-repeat is honoured (holding Tab keeps walking, as
everywhere else); a Tab chorded with Alt, Control, or Meta is not ours and is
passed through untouched.
Leaving the tree with wrap: false (corrected 2026-08-07)
The option's note used to promise that the traversal "blurs at each end
and lets the keystroke through with its platform default intact, so the focus
leaves the widget tree" — which described one keystroke and delivered
something else. With the documented wiring (keyboardFocusTarget falls back
to the root when nothing is focused) the next Tab arrived at the root with
nothing focused, was read as "enter the tree", and put the focus straight back
on the first widget with preventDefault() on top. The focus left for exactly
one keystroke and the host never got one.
What happens now: the keystroke that steps off the end blurs and passes
through (the host moves its own focus ring), and the next Tab is passed
through as well — the traversal remembers that it just let go, so it does not
treat "nothing focused" as an invitation to re-enter. The keystroke after
that re-enters at the near end, which is what a user tabbing back into an
embedded panel means. Two keystrokes leave, the third returns; nothing in
that sequence suppresses a host default the traversal did not act on.
The exit memory is deliberately one-shot and per-installation: anything that
moves the focus back into the tree — a click, a programmatic focus(), the
re-entering Tab itself — makes the next Tab an ordinary step again.
Nothing here writes a transform, and nothing here activates anything — a
focused Button reads its own Enter and Space.
Installs §75's Tab traversal on
root, and returns the unsubscriber.Listens for
keydownonroot— the bubble phase, so it hears both the keystrokes delivered to a focused descendant and the ones delivered torootitself when nothing is focused (see keyboardFocusTarget). Tab moves the focus forward, Shift-Tab backward, and both callSceneKeyEvent.preventDefault()on the way out so the host's own focus ring does not move at the same time.Everything else is ignored and left to propagate: this listener claims Tab and nothing else. Auto-repeat is honoured (holding Tab keeps walking, as everywhere else); a Tab chorded with Alt, Control, or Meta is not ours and is passed through untouched.
Leaving the tree with
wrap: false(corrected 2026-08-07)The option's note used to promise that the traversal "blurs at each end and lets the keystroke through with its platform default intact, so the focus leaves the widget tree" — which described one keystroke and delivered something else. With the documented wiring (
keyboardFocusTargetfalls back to the root when nothing is focused) the next Tab arrived at the root with nothing focused, was read as "enter the tree", and put the focus straight back on the first widget withpreventDefault()on top. The focus left for exactly one keystroke and the host never got one.What happens now: the keystroke that steps off the end blurs and passes through (the host moves its own focus ring), and the next Tab is passed through as well — the traversal remembers that it just let go, so it does not treat "nothing focused" as an invitation to re-enter. The keystroke after that re-enters at the near end, which is what a user tabbing back into an embedded panel means. Two keystrokes leave, the third returns; nothing in that sequence suppresses a host default the traversal did not act on.
The exit memory is deliberately one-shot and per-installation: anything that moves the focus back into the tree — a click, a programmatic
focus(), the re-entering Tab itself — makes the next Tab an ordinary step again.Nothing here writes a transform, and nothing here activates anything — a focused
Buttonreads its own Enter and Space.