12.12.2 Input Focus Events

Selected by:

:focus-change.

:focus-in and :focus-out events are generated when the input focus changes. All :focus-out events caused by a window :unmap are generated after any :unmap-notify event, but the ordering of :focus-out with respect to generated :enter-notify, :leave-notify, :visibility-notify, and :expose events is not constrained.

window, event-window

Type window. For :focus-in, the new input focus window. For :focus-out, the previous input focus window.

mode

Type (member :normal :while-grabbed :grab :ungrab). Events generated by set-input-focus when the keyboard is not grabbed have mode :normal. Events generated by set-input-focus when the keyboard is grabbed have mode :while-grabbed. Events generated when a keyboard grab activates have mode :grab, and events generated when a keyboard grab deactivates have mode :ungrab.

kind

Type (member :ancestor :virtual :inferior :nonlinear :nonlinear-virtual :pointer :pointer-root :none). When the focus moves from window A to window B, and A is an inferior of B, with the pointer in window P:

• :focus-out with kind :ancestor is generated on A
• :focus-out with kind :virtual is generated on each window between A and B exclusive (in that order)
• :focus-in with kind :inferior is generated on B
• If P is an inferior of B, but P is not A or an inferior of A or an ancestor of A, :focus-in with kind :pointer is generated on each window below B down to and including P (in order)

When the focus moves from window A to window B, and B is an inferior of A, with the pointer in window P:

• If P is an inferior of A, but P is not A or an inferior of B or an ancestor of B, :focus-out with kind :pointer is generated on each window from P up to but not including A (in order)
• :focus-out with kind :inferior is generated on A
• :focus-in with kind :virtual is generated on each window between A and B exclusive (in that order)
• :focus-in with kind :ancestor is generated on B

When the focus moves from window A to window B, with window C being their least common ancestor, and with the pointer in window P:

• If P is an inferior of A, :focus-out with kind :pointer is generated on each window from P up to but not including A (in order)
• :focus-out with kind :nonlinear is generated on A
• :focus-out with kind :nonlinear-virtual is generated on each window between A and C exclusive (in that order)
• :focus-in with kind :nonlinear-virtual is generated on each window between C and B exclusive (in that order)
• :focus-in with kind :nonlinear is generated on B
• If P is an inferior of B, :focus-in with kind :pointer is generated on each window below B down to and including P (in order)

When the focus moves from window A to window B, on different screens, with the pointer in window P:

• If P is an inferior of A, :focus-out with kind :pointer is generated on each window from P up to but not including A (in order)
• :focus-out with kind :nonlinear is generated on A
• If A is not a root window, :focus-out with kind :nonlinear-virtual is generated on each window above A up to and including its root (in order)
• If B is not a root window, :focus-in with kind :nonlinear-virtual is generated on each window from B's root down to but not including B (in order)
• :focus-in with kind :nonlinear is generated on B
• If P is an inferior of B, :focus-in with kind :pointer is generated on each window below B down to and including P (in order)

When the focus moves from window A to :pointer-root (or :none), with the pointer in window P:

• If P is an inferior of A, :focus-out with kind :pointer is generated on each window from P up to but not including A (in order)
• :focus-out with kind :nonlinear is generated on A
• If A is not a root window, :focus-out with kind :nonlinear-virtual is generated on each window above A up to and including its root (in order)
• :focus-in with kind :pointer-root (or :none) is generated on all root windows
• If the new focus is :pointer-root, :focus-in with kind :pointer is generated on each window from P's root down to and including P (in order)

When the focus moves from :pointer-root (or :none ) to window A, with the pointer in window P:

• If the old focus is :pointer-root, :focus-out with kind :pointer is generated on each window from P up to and including P's root (in order)
• :focus-out with kind :pointer-root (or :none) is generated on all root windows
• If A is not a root window, :focus-in with kind :nonlinear-virtual is generated on each window from A's root down to but not including A (in order)
• :focus-in with kind :nonlinear is generated on A
• If P is an inferior of A, :focus-in with kind :pointer is generated on each window below A down to and including P (in order)

When the focus moves from :pointer-root to :none (or vice versa), with the pointer in window P:

• If the old focus is :pointer-root, :focus-out with kind :pointer is generated on each window from P up to and including P's root (in order)
• :focus-out with kind :pointer-root (or :none) is generated on all root windows
• :focus-in with kind :none (or :pointer-root) is generated on all root windows
• If the new focus is :pointer-root, :focus-in with kind :pointer is generated on each window from P's root down to and including P (in order)

When a keyboard grab activates (but before generating any actual :key-press event that activates the grab), with G the grab-window for the grab and F the current focus, then :focus-in and :focus-out events with mode :grab are generated (as for :normal above) as if the focus were to change from F to G.

When a keyboard grab deactivates (but after generating any actual :key-release event that deactivates the grab), with G the grab-window for the grab and F the current focus, then :focus-in and :focus-out events with mode :ungrab are generated (as for :normal above) as if the focus were to change from G to F.