tk_menus — User Commands

NAME

tk_menus, tk_bindForTraversal − Enable keyboard menu traversal

SYNOPSIS

tk_menus toplevel ?menu menu ...? tk_bindForTraversal arg arg ...

DESCRIPTION

These two commands are Tcl procedures provided as part of the Tk script library. They provide the top-level interface for Tk’s support for keyboard traversal of menus. These procedures need not be used by applications that prefer not to have keyboard traversal of menus or wish to implement it in some other fashion. In order for an application to use this facility, it must do three things, which are described in the paragraphs below.

First, each application must call tk_menus to identify the menu buttons associated with each top-level window that contains menus. The toplevel argument gives the path name of a top-level window and the menu arguments give path names for all of the menu buttons in that top-level window. The order of the menu arguments determines the traversal order for the menu buttons. If tk_menus is called without any menu arguments, it returns the current menu list for toplevel, or an empty string if there is no menu list. If tk_menus is called with a single menu argument consisting of an empty string, menu traversal will be disabled for toplevel.

The second thing an application must do to use menu traversal is to identify the traversal characters for menu buttons and menu entries. This is done by underlining those characters using the −underline options for the widgets. The menu traversal system uses this information to traverse the menus under keyboard control (see below).

The third thing that an application must do to use menu traversal is to make sure that the input focus is always in a window that has been configured to support menu traversal. If the input focus is none then input characters will be discarded and no menu traversal will be possible. By default, the Tk startup scripts configure all the Tk widget classes to support menu traversal (they call the tk_bindForTraversal procedure described below).

If your application defines new classes of widgets that support the input focus, then you should call tk_bindForTraversal for each of these classes. Tk_bindForTraversal takes any number of arguments, each of which is a widget path name or widget class name. It sets up bindings for all the named widgets and classes so that the menu traversal system will be invoked when appropriate keystrokes are typed in those widgets or classes.

Typically, applications will also call tk_bindForTraversal on their main window (“.”) and set the input focus to that window whenever it doesn’t make sense for it to be anywhere else. This guarantees that menu traversal will be possible even when there is no other input focus.

MENU TRAVERSAL BINDINGS

Once an application has made the three arrangements described above, menu traversal will be available. At any given time, the only menus available for traversal are those associated with the top-level window containing the input focus. Menu traversal is initiated by one of the following actions:

[1]If <F10> is typed, then the first menu button in the list for the top-level window is posted and the first entry within that menu is selected.

[2]If <Alt-key> is pressed, then the menu button that has key as its underlined character is posted and the first entry within that menu is selected. The comparison between key and the underlined characters ignores case differences. If no menu button matches key then the keystroke has no effect.

[3]Clicking mouse button 1 on a menu button posts that menu and selects its first entry.

Once a menu has been posted, the input focus is switched to that menu and the following actions are possible:

[1]Typing <ESC> or clicking mouse button 1 outside the menu button or its menu will abort the menu traversal.

[2]If <Alt-key> is pressed, then the entry in the posted menu whose underlined character is key is invoked. This causes the menu to be unposted, the entry’s action to be taken, and the menu traversal to end. The comparison between key and underlined characters ignores case differences. If no menu entry matches key then the keystroke is ignored.

[3]The arrow keys may be used to move among entries and menus. The left and right arrow keys move circularly among the available menus and the up and down arrow keys move circularly among the entries in the current menu.

[4]If <Return> is pressed, the selected entry in the posted menu is invoked, which causes the menu to be unposted, the entry’s action to be taken, and the menu traversal to end.

When a menu traversal completes, the input focus reverts to the window that contained it when the traversal started.

KEYWORDS

keyboard traversal, menus, post