on-traverse-char in top-level-window<%>

Attempts to handle the given keyboard event as a navigation event, such as a Tab key event that moves the keyboard focus. If the event is handled, #t is returned, otherwise #f is returned.

• (send a-top-level-window on-traverse-char event) -> boolean
     event : key-event% object

  The following rules determine, in order, whether and how event is handled:

  • If the window that currently owns the focus specifically handles the event, then #f is returned. The following describes window types and the keyboard events they specifically handle:

    • editor-canvas% -- tab-exit is disabled (see allow-tab-exit): all keyboard events, except alphanumeric key events when the Meta (X) or Alt (Windows) key is pressed; when tab-exit is enabled: all keyboard events except Tab, Enter, Escape, and alphanumeric Meta/Alt events.

    • canvas% -- when tab-focus is disabled (see accept-tab-focus): all keyboard events, except alphanumeric key events when the Meta (X) or Alt (Windows) key is pressed; when tab-focus is enabled: no key events

    • text-field%, 'single style -- arrow key events and alphanumeric key events when the Meta (X) or Alt (Windows) key is not pressed (and all alphanumeric events under Mac OS)

    • text-field%, 'multiple style -- all keyboard events, except alphanumeric key events when the Meta (X) or Alt (Windows) key is pressed

    • choice% -- arrow key events and alphanumeric key events when the Meta (X) or Alt (Windows) key is not pressed

    • list-box% -- arrow key events and alphanumeric key events when the Meta (X) or Alt (Windows) key is not pressed

  • If event is a Tab or arrow key event, the keyboard focus is moved within the window and #t is returned. Across platforms, the types of windows that accept the keyboard focus via navigation may vary, but text-field% windows always accept the focus, and message%, gauge%, and panel% windows never accept the focus.

  • If event is an Space key event and the window that currently owns the focus is a button%, check-box%, or radio-box% object, the event is handled in the same way as a click on the control and #t is returned.

  • If event is an Enter key event and the current top-level window contains a border button, the button's callback is invoked and #t is returned. (The 'border style for a button% object indicates to the user that pressing Enter is the same as clicking the button.) If the window does not contain a border button, #t is returned if the window with the current focus is not a text field or editor canvas.

  • In a dialog, if event is an Escape key event, the event is handled the same as a click on the dialog's close box (i.e., the dialog's can-close? and on-close methods are called, and the dialog is hidden) and #t is returned.

  • If event is an alphanumeric key event and the current top-level window contains a control with a mnemonic matching the key (which is installed via a label that contains ``&''; see get-label for more information), then the keyboard focus is moved to the matching control. Furthermore, if the matching control is a button%, check-box%, or radio-box% button, the keyboard event is handled in the same way as a click on the control.

  • Otherwise, #f is returned.