NAME
       tk_menuBar, tk_bindForTraversal - Support for menu bars

SYNOPSIS
       tk_menuBar frame ?menu menu ...?

       tk_bindForTraversal arg arg ...


DESCRIPTION
       These  two  commands  are  Tcl procedures in the Tk script
       library.  They provide support for menu bars.  A menu  bar
       is a frame that contains a collection of menu buttons that
       work together, so that the user can scan from one menu  to
       another  with  the  mouse:  if the mouse button is pressed
       over one menubutton (causing it to post its menu) and  the
       mouse  is  moved  over another menubutton in the same menu
       bar without releasing the mouse button, then the  menu  of
       the  first  menubutton is unposted and the menu of the new
       menubutton is posted instead.  Menus in  a  menu  bar  can
       also be accessed using keyboard traversal (i.e.  by typing
       keystrokes instead of using the mouse).  In order  for  an
       application  to  use  these  procedures,  it must do three
       things, which are described in the paragraphs below.

       First, each application must call  tk_menuBar  to  provide
       information  about  the menubar.  The frame argument gives
       the path name of the frame that contains all of  the  menu
       buttons, and the menu arguments give path names for all of
       the menu buttons associated with the menu  bar.   Normally
       frame  is the parent of each of the menu's.  This need not
       be the case, but frame must be an ancestor of each of  the
       menu's in order for grabs to work correctly when the mouse
       is used to pull down menus.  The order of the  menu  argu-
       ments determines the traversal order for the menu buttons.
       If tk_menuBar is called without  any  menu  arguments,  it
       returns  a  list  containing  the current menu buttons for
       frame, or an empty string if frame isn't currently set  up
       as a menu bar.  If tk_menuBar is called with a single menu
       argument consisting of an empty string, any menubar infor-
       mation for frame is removed;  from now on the menu buttons
       will function independently  without  keyboard  traversal.
       Only  one  menu  bar  may be defined at a time within each
       top-level window.

       The second thing an application must do 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 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.  If you have no other
       place to set the focus, set  it  to  the  menubar  widget:
       tk_menuBar creates bindings for its frame argument to sup-
       port menu traversal.

       The Tk startup scripts configure all the Tk widget classes
       with bindings to support menu traversal, so menu traversal
       will be possible regardless of which widget has the focus.
       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.


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  charac-
              ters  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 traver-
              sal.

       [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 cir-
              cularly 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, menu, menu bar, post
