NAME
       menu - Create and manipulate menu widgets

SYNOPSIS
       menu pathName ?options?

STANDARD OPTIONS
       -activebackground              -background     -disabledforeground-relief
       -activeborderwidth             -borderwidth    -font-takefocus
       -activeforeground              -cursor         -foreground

       See  the  options manual entry for details on the standard
       options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-postcommand
       Database Name:  postCommand
       Database Class: Command

              If this option is specified then it provides a  Tcl
              command  to  execute  each time the menu is posted.
              The command is invoked by the post  widget  command
              before  posting  the  menu.  Note  that  in  8.0 on
              Macintosh and  Windows,  all  commands  in  a  menu
              systems are executed before any are posted. This is
              due to the limitations in the individual platforms'
              menu managers.

       Command-Line Name:-selectcolor
       Database Name:  selectColor
       Database Class: Background

              For  menu  entries  that are check buttons or radio
              buttons, this option specifies the color to display
              in  the  indicator  when  the check button or radio
              button is selected.

       Command-Line Name:-tearoff
       Database Name:  tearOff
       Database Class: TearOff

              This option must have a proper boolean value, which
              specifies  whether or not the menu should include a
              tear-off entry at the top.  If so, it will exist as
              entry  0  of  the  menu  and the other entries will
              number starting at 1.  The  default  menu  bindings
              arrange  for the menu to be torn off when the tear-
              off entry is invoked.

       Command-Line Name:-tearoffcommand
       Database Name:  tearOffCommand
       Database Class: TearOffCommand

              If this option  has  a  non-empty  value,  then  it
              specifies a Tcl command to invoke whenever the menu
              is torn off.  The actual command  will  consist  of
              the  value  of  this  option,  followed by a space,
              followed by the name of the menu  window,  followed
              by a space, followed by the name of the name of the
              torn off menu window.  For example, if the option's
              is  ``a  b''  and menu .x.y is torn off to create a
              new menu .x.tearoff1, then the command ``a  b  .x.y
              .x.tearoff1'' will be invoked.

       Command-Line Name:-title
       Database Name:  title
       Database Class: Title

              The string will be used to title the window created
              when this menu is torn off. If the title  is  NULL,
              then   the  window  will  have  the  title  of  the
              menubutton or the text of  the  cascade  item  from
              which this menu was invoked.

       Command-Line Name:-type
       Database Name:  type
       Database Class: Type

              This  option  can  be  one  of menubar, tearoff, or
              normal, and is set when the menu is created.  While
              the  string  returned by the configuration database
              will change if this option is  changed,  this  does
              not affect the menu widget's behavior. This is used
              by the cloning mechanism and is  not  normally  set
              outside of the Tk library.


INTRODUCTION
       The  menu command creates a new top-level window (given by
       the pathName argument) and makes it into  a  menu  widget.
       Additional  options,  described above, may be specified on
       the command line or in the option  database  to  configure
       aspects of the menu such as its colors and font.  The menu
       command returns its pathName argument.  At the  time  this
       command  is  invoked,  there must not exist a window named
       pathName, but pathName's parent must exist.

       A menu is a widget that displays a collection of  one-line
       entries  arranged  in  one  or  more columns.  There exist
       several different types of entries,  each  with  different
       properties.  Entries of different types may be combined in
       a single menu.  Menu entries are not  the  same  as  entry
       widgets.   In  fact,  menu  entries  are not even distinct
       widgets; the entire menu is one widget.

       Menu entries are  displayed  with  up  to  three  separate
       fields.   The  main field is a label in the form of a text
       string, a bitmap, or an image, controlled by  the  -label,
       -bitmap,  and  -image  options  for  the  entry.   If  the
       -accelerator option is  specified  for  an  entry  then  a
       second  textual  field  is  displayed  to the right of the
       label.  The accelerator typically  describes  a  keystroke
       sequence that may be typed in the application to cause the
       same result as invoking the menu entry.  The  third  field
       is  an  indicator.   The  indicator  is  present  only for
       checkbutton or radiobutton entries.  It indicates  whether
       the entry is selected or not, and is displayed to the left
       of the entry's string.

       In normal use, an entry becomes  active  (displays  itself
       differently) whenever the mouse pointer is over the entry.
       If a mouse button is released  over  the  entry  then  the
       entry  is  invoked.  The effect of invocation is different
       for each type of entry; these effects are described  below
       in the sections on individual entries.

       Entries  may  be  disabled,  which causes their labels and
       accelerators to be  displayed  with  dimmer  colors.   The
       default  menu  bindings will not allow a disabled entry to
       be activated or invoked.   Disabled  entries  may  be  re-
       enabled,  at  which  point it becomes possible to activate
       and invoke them again.

       Whenever   a   menu's   active   entry   is   changed,   a
       <<MenuSelect>>  virtual  event  is  send  to the menu. The
       active item can then be queried  from  the  menu,  and  an
       action  can  be  taken,  such as setting context-sensitive
       help text for the entry.


COMMAND ENTRIES
       The most common kind of menu entry  is  a  command  entry,
       which  behaves  much like a button widget.  When a command
       entry is invoked, a Tcl  command  is  executed.   The  Tcl
       command is specified with the -command option.


SEPARATOR ENTRIES
       A  separator is an entry that is displayed as a horizontal
       dividing line.   A  separator  may  not  be  activated  or
       invoked,  and  it  has  no behavior other than its display
       appearance.


CHECKBUTTON ENTRIES
       A checkbutton menu entry behaves much like  a  checkbutton
       widget.   When  it  is  invoked  it toggles back and forth
       between the selected  and  deselected  states.   When  the
       entry  is  selected,  a  particular  value  is stored in a
       particular global variable (as determined by the  -onvalue
       and  -variable  options for the entry);  when the entry is
       deselected another  value  (determined  by  the  -offvalue
       option)  is  stored  in the global variable.  An indicator
       box is displayed to the left of the label in a checkbutton
       entry.   If  the  entry  is  selected then the indicator's
       center is displayed in the color given by the -selectcolor
       option  for the entry; otherwise the indicator's center is
       displayed in the background color  for  the  menu.   If  a
       -command option is specified for a checkbutton entry, then
       its value is evaluated as a  Tcl  command  each  time  the
       entry is invoked;  this happens after toggling the entry's
       selected state.


RADIOBUTTON ENTRIES
       A radiobutton menu entry behaves much like  a  radiobutton
       widget.   Radiobutton  entries  are organized in groups of
       which only one entry may be selected at a time.   Whenever
       a particular entry becomes selected it stores a particular
       value into a particular global variable (as determined  by
       the  -value  and  -variable  options for the entry).  This
       action causes any previously-selected entry  in  the  same
       group  to  deselect  itself.   Once  an  entry  has become
       selected, any change to the  entry's  associated  variable
       will  cause  the  entry  to  deselect itself.  Grouping of
       radiobutton entries  is  determined  by  their  associated
       variables:   if  two  entries  have  the  same  associated
       variable then they are in the same  group.   An  indicator
       diamond  is  displayed  to  the  left of the label in each
       radiobutton entry.  If the  entry  is  selected  then  the
       indicator's  center is displayed in the color given by the
       -selectcolor  option  for   the   entry;   otherwise   the
       indicator's  center  is  displayed in the background color
       for the menu.  If a -command option  is  specified  for  a
       radiobutton  entry,  then  its value is evaluated as a Tcl
       command each time the  entry  is  invoked;   this  happens
       after selecting the entry.


CASCADE ENTRIES
       A cascade entry is one with an associated menu (determined
       by  the  -menu  option).   Cascade   entries   allow   the
       construction  of  cascading menus.  The postcascade widget
       command can be used to post and unpost the associated menu
       just  next  to  of the cascade entry.  The associated menu
       must be a child of the menu containing the  cascade  entry
       (this  is  needed  in  order  for  menu  traversal to work
       correctly).

       A cascade entry posts its associated menu  by  invoking  a
       Tcl command of the form
              menu post x y
       where  menu is the path name of the associated menu, and x
       and y are the root-window coordinates of  the  upper-right
       corner  of  the  cascade  entry.  On Unix, the lower-level
       menu is unposted by executing a Tcl command with the form
              menu unpost
       where menu is the name of the associated menu.   On  other
       platforms,  the  platform's  native  code  takes  care  of
       unposting the menu.

       If a -command option is specified for a cascade entry then
       it  is  evaluated  as  a Tcl command whenever the entry is
       invoked. This is not supported on Windows.


TEAR-OFF ENTRIES
       A tear-off entry appears at the top of the menu if enabled
       with  the  tearOff  option.   It  is  not  like other menu
       entries in that it cannot be created with the  add  widget
       command  and  cannot  be  deleted  with  the delete widget
       command.  When a tear-off entry is created it appears as a
       dashed  line  at  the  top of the menu.  Under the default
       bindings, invoking the tear-off entry  causes  a  torn-off
       copy to be made of the menu and all of its submenus.


MENUBARS
       Any  menu  can  be  set as a menubar for a toplevel window
       (see toplevel  command  for  syntax).  On  the  Macintosh,
       whenever  the  toplevel  is  in front, this menu's cascade
       items will appear in the menubar across  the  top  of  the
       main  monitor. On Windows and Unix, this menu's items will
       be displayed in a menubar accross the top of  the  window.
       These   menus  will  behave  according  to  the  interface
       guidelines of their platforms. For every  menu  set  as  a
       menubar,  a clone menu is made. See the CLONES section for
       more information.

       As noted, menubars may  behave  differently  on  different
       platforms.   One  example of this concerns the handling of
       checkbuttons and radiobuttons within the menu.   While  it
       is  permitted to put these menu elements on menubars, they
       may not be drawn with indicators on some platforms, due to
       system restrictions.



SPECIAL MENUS IN MENUBARS
       Certain  menus in a menubar will be treated specially.  On
       the Macintosh, access to the special Apple and Help  menus
       is provided. On Windows, access to the Windows System menu
       in each window is provided. On X Windows, a special right-
       justified help menu is provided. In all cases, these menus
       must be created with the command name of the menubar  menu
       concatenated with the special name. So for a menubar named
       .menubar, on the Macintosh, the  special  menus  would  be
       .menubar.apple  and .menubar.help; on Windows, the special
       menu would be .menubar.system; on X Windows, the help menu
       would be .menubar.help.

       When  Tk  sees an Apple menu on the Macintosh, that menu's
       contents make up the first items of the Apple menu on  the
       screen  whenever  the  window containing the menubar is in
       front. The menu is the first one that the  user  sees  and
       has  a title which is an Apple logo.  After all of the Tk-
       defined items, the menu will have a separator, followed by
       all  of  the  items in the user's Apple Menu Items folder.
       Since  the  System  uses  a  different   menu   definition
       procedure  for  the Apple menu than Tk uses for its menus,
       and the system APIs do not  fully  support  everything  Tk
       tries  to  do,  the  menu  item  will  only  have its text
       displayed. No font attributes, images, bitmaps, or  colors
       will be displayed. In addition, a menu with a tearoff item
       will have the tearoff item displayed as "(TearOff)".

       When Tk see a Help  menu  on  the  Macintosh,  the  menu's
       contents  are  appended  to  the standard help menu on the
       right of the user's menubar whenever the user's menubar is
       in  front.  The  first  items  in the menu are provided by
       Apple. Similar to the Apple  Menu,  cusomization  in  this
       menu is limited to what the system provides.

       When  Tk  sees  a  System  menu  on Windows, its items are
       appended to the system menu that the menubar  is  attached
       to. This menu has an icon representing a spacebar, and can
       be invoked with the mouse or by typing Alt+Spacebar.   Due
       to  limitations  in  the  Windows  API,  any font changes,
       colors, images, bitmaps, or tearoff images will not appear
       in the system menu.

       When Tk see a Help menu on X Windows, the menu is moved to
       be last in the menubar and is right justified.


CLONES
       When a menu is set as a menubar for a toplevel window,  or
       when a menu is torn off, a clone of the menu is made. This
       clone is a menu widget in its own right, but it is a child
       of  the  original.  Changes  in  the  configuration of the
       original are reflected in  the  clone.  Additionally,  any
       cascades  that are pointed to are also cloned so that menu
       traversal will  work  right.  Clones  are  destroyed  when
       either  the  tearoff  or  menubar  goes  away, or when the
       original menu is destroyed.


WIDGET COMMAND
       The menu command creates a new Tcl command whose  name  is
       pathName.   This  command  may  be  used to invoke various
       operations on the widget.  It has  the  following  general
       form:
              pathName option ?arg arg ...?
       Option  and  the  args determine the exact behavior of the
       command.

       Many of the  widget  commands  for  a  menu  take  as  one
       argument  an  indicator  of  which  entry  of  the menu to
       operate on.  These indicators are called indexes  and  may
       be specified in any of the following forms:

       number      Specifies   the  entry  numerically,  where  0
                   corresponds to the top-most entry of the menu,
                   1 to the entry below it, and so on.

       active      Indicates  the entry that is currently active.
                   If no  entry  is  active  then  this  form  is
                   equivalent  to  none.   This  form  may not be
                   abbreviated.

       end         Indicates the bottommost entry  in  the  menu.
                   If  there are no entries in the menu then this
                   form is equivalent to none.  This form may not
                   be abbreviated.

       last        Same as end.

       none        Indicates  ``no  entry at all'';  this is used
                   most commonly  with  the  activate  option  to
                   deactivate  all  the  entries in the menu.  In
                   most cases the specification  of  none  causes
                   nothing to happen in the widget command.  This
                   form may not be abbreviated.

       @number     In this  form,  number  is  treated  as  a  y-
                   coordinate  in  the  menu's window;  the entry
                   closest to that  y-coordinate  is  used.   For
                   example,  ``@0''  indicates the top-most entry
                   in the window.

       pattern     If the index doesn't satisfy one of the  above
                   forms  then  this  form  is  used.  Pattern is
                   pattern-matched  against  the  label  of  each
                   entry in the menu, in order from the top down,
                   until a matching entry is found.  The rules of
                   Tcl_StringMatch are used.

       The  following  widget  commands  are  possible  for  menu
       widgets:

       pathName activate index
              Change the state of the entry indicated by index to
              active  and  redisplay  it using its active colors.
              Any previously-active  entry  is  deactivated.   If
              index  is  specified  as  none, or if the specified
              entry is disabled, then the menu ends  up  with  no
              active entry.  Returns an empty string.

       pathName add type ?option value option value ...?
              Add a new entry to the bottom of the menu.  The new
              entry's type is given by type and must  be  one  of
              cascade,   checkbutton,  command,  radiobutton,  or
              separator, or a unique abbreviation of one  of  the
              above.   If  additional arguments are present, they
              specify any of the following options:

              -activebackground value
                     Specifies a  background  color  to  use  for
                     displaying this entry when it is active.  If
                     this option is specified as an empty  string
                     (the  default),  then  the  activeBackground
                     option for the overall menu is used.  If the
                     tk_strictMotif  variable  has  been  set  to
                     request strict Motif compliance,  then  this
                     option is ignored and the -background option
                     is used in its place.  This  option  is  not
                     available for separator or tear-off entries.

              -activeforeground value
                     Specifies a  foreground  color  to  use  for
                     displaying this entry when it is active.  If
                     this option is specified as an empty  string
                     (the  default),  then  the  activeForeground
                     option for the overall menu is  used.   This
                     option  is  not  available  for separator or
                     tear-off entries.

              -accelerator value
                     Specifies a string to display at  the  right
                     side  of the menu entry.  Normally describes
                     an accelerator keystroke sequence  that  may
                     be  typed to invoke the same function as the
                     menu entry.  This option  is  not  available
                     for separator or tear-off entries.

              -background value
                     Specifies  a  background  color  to  use for
                     displaying this entry  when  it  is  in  the
                     normal  state (neither active nor disabled).
                     If this option  is  specified  as  an  empty
                     string  (the  default),  then the background
                     option for the overall menu is  used.   This
                     option  is  not  available  for separator or
                     tear-off entries.

              -bitmap value
                     Specifies a bitmap to display  in  the  menu
                     instead  of  a  textual label, in any of the
                     forms accepted by Tk_GetBitmap.  This option
                     overrides the -label option but may be reset
                     to an empty string to enable a textual label
                     to  be  displayed.   If  a -image option has
                     been specified, it overrides -bitmap.   This
                     option  is  not  available  for separator or
                     tear-off entries.

              -columnbreak value
                     When this option is zero, the appears  below
                     the previous entry. When this option is one,
                     the menu appears at the top of a new  column
                     in the menu.

              -command value
                     Specifies  a Tcl command to execute when the
                     menu entry is invoked.   Not  available  for
                     separator or tear-off entries.

              -font value
                     Specifies  the  font to use when drawing the
                     label or accelerator string in  this  entry.
                     If  this  option  is  specified  as an empty
                     string (the default) then  the  font  option
                     for  the  overall menu is used.  This option
                     is not available for separator  or  tear-off
                     entries.

              -foreground value
                     Specifies  a  foreground  color  to  use for
                     displaying this entry  when  it  is  in  the
                     normal  state (neither active nor disabled).
                     If this option  is  specified  as  an  empty
                     string  (the  default),  then the foreground
                     option for the overall menu is  used.   This
                     option  is  not  available  for separator or
                     tear-off entries.

              -hidemargin value
                     Specifies  whether  the   standard   margins
                     should be drawn for this menu entry. This is
                     useful when creating palette with images  in
                     them,    i.e.,   color   palettes,   pattern
                     palettes, etc. 1 indicates that  the  margin
                     for  the  entry  is hidden; 0 means that the
                     margin is used.

              -image value
                     Specifies an image to display  in  the  menu
                     instead of a text string or bitmap The image
                     must have  been  created  by  some  previous
                     invocation  of  image  create.   This option
                     overrides the -label and -bitmap options but
                     may  be reset to an empty string to enable a
                     textual or bitmap  label  to  be  displayed.
                     This  option  is not available for separator
                     or tear-off entries.

              -indicatoron value
                     Available   only   for    checkbutton    and
                     radiobutton  entries.   Value  is  a boolean
                     that determines whether or not the indicator
                     should be displayed.

              -label value
                     Specifies   a   string   to  display  as  an
                     identifying label in the  menu  entry.   Not
                     available for separator or tear-off entries.

              -menu value
                     Available   only   for   cascade    entries.
                     Specifies  the  path  name  of  the  submenu
                     associated with  this  entry.   The  submenu
                     must be a child of the menu.

              -offvalue value
                     Available   only  for  checkbutton  entries.
                     Specifies the value to store in the  entry's
                     associated   variable   when  the  entry  is
                     deselected.

              -onvalue value
                     Available  only  for  checkbutton   entries.
                     Specifies  the value to store in the entry's
                     associated  variable  when  the   entry   is
                     selected.

              -selectcolor value
                     Available    only    for   checkbutton   and
                     radiobutton entries.  Specifies the color to
                     display  in  the indicator when the entry is
                     selected.  If the value is an  empty  string
                     (the  default)  then  the selectColor option
                     for the menu determines the indicator color.

              -selectimage value
                     Available    only    for   checkbutton   and
                     radiobutton entries.  Specifies an image  to
                     display in the entry (in place of the -image
                     option) when it is selected.  Value  is  the
                     name  of  an  image,  which  must  have been
                     created by some previous invocation of image
                     create.   This  option is ignored unless the
                     -image option has been specified.

              -state value
                     Specifies one of three states for the entry:
                     normal,  active,  or  disabled.   In  normal
                     state  the  entry  is  displayed  using  the
                     foreground  option  for  the  menu  and  the
                     background option  from  the  entry  or  the
                     menu.   The  active  state is typically used
                     when the pointer  is  over  the  entry.   In
                     active  state  the  entry is displayed using
                     the activeForeground  option  for  the  menu
                     along  with the activebackground option from
                     the entry.  Disabled state  means  that  the
                     entry  should  be  insensitive:  the default
                     bindings will refuse to activate  or  invoke
                     the  entry.   In  this  state  the  entry is
                     displayed       according       to       the
                     disabledForeground  option  for the menu and
                     the background option from the entry.   This
                     option   is   not  available  for  separator
                     entries.

              -underline value
                     Specifies the integer index of  a  character
                     to  underline  in the entry.  This option is
                     also queried by  the  default  bindings  and
                     used  to  implement  keyboard  traversal.  0
                     corresponds to the first  character  of  the
                     text  displayed  in the entry, 1 to the next
                     character, and so on.  If a bitmap or  image
                     is  displayed  in the entry then this option
                     is ignored.  This option  is  not  available
                     for separator or tear-off entries.

              -value value
                     Available   only  for  radiobutton  entries.
                     Specifies the value to store in the  entry's
                     associated   variable   when  the  entry  is
                     selected.  If an empty string is  specified,
                     then  the -label option for the entry as the
                     value to store in the variable.

              -variable value
                     Available   only   for    checkbutton    and
                     radiobutton  entries.  Specifies the name of
                     a global value to  set  when  the  entry  is
                     selected.    For   checkbutton  entries  the
                     variable is  also  set  when  the  entry  is
                     deselected.     For   radiobutton   entries,
                     changing the variable causes the  currently-
                     selected entry to deselect itself.

              The add widget command returns an empty string.

       pathName cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values accepted by the menu command.

       pathName clone newPathname ?cloneType?
              Makes   a   clone   of   the   current  menu  named
              newPathName. This clone is a menu in its own right,
              but  any changes to the clone are propogated to the
              original menu and  vice  versa.  cloneType  can  be
              normal, menubar, or tearoff. Should not normally be
              called outside of the Tk library.  See  the  CLONES
              section for more information.

       pathName configure ?option? ?value option value ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing   all   of  the  available  options  for
              pathName (see Tk_ConfigureInfo for  information  on
              the  format  of this list).  If option is specified
              with no value, then  the  command  returns  a  list
              describing  the one named option (this list will be
              identical to the corresponding sublist of the value
              returned  if  no  option  is specified).  If one or
              more option-value pairs  are  specified,  then  the
              command modifies the given widget option(s) to have
              the given  value(s);   in  this  case  the  command
              returns  an  empty  string.  Option may have any of
              the values accepted by the menu command.

       pathName delete index1 ?index2?
              Delete all of the menu entries between  index1  and
              index2  inclusive.   If  index2  is omitted then it
              defaults to index1.  Attempts to delete a  tear-off
              menu  entry are ignored (instead, you should change
              the tearOff option to remove the tear-off entry).

       pathName entrycget index option
              Returns the current value of a configuration option
              for  the entry given by index.  Option may have any
              of the values accepted by the add widget command.

       pathName entryconfigure index ?options?
              This command is similar to the  configure  command,
              except  that  it  applies  to  the  options  for an
              individual entry, whereas configure applies to  the
              options  for the menu as a whole.  Options may have
              any of  the  values  accepted  by  the  add  widget
              command.   If  options  are  specified, options are
              modified  as  indicated  in  the  command  and  the
              command returns an empty string.  If no options are
              specified, returns a list  describing  the  current
              options  for  entry index (see Tk_ConfigureInfo for
              information on the format of this list).

       pathName index index
              Returns the numerical index corresponding to index,
              or none if index was specified as none.

       pathName insert index type ?option value option value ...?
              Same as the  add  widget  command  except  that  it
              inserts  the  new entry just before the entry given
              by index, instead of appending to the  end  of  the
              menu.   The  type, option, and value arguments have
              the same  interpretation  as  for  the  add  widget
              command.   It  is  not  possible to insert new menu
              entries before the tear-off entry, if the menu  has
              one.

       pathName invoke index
              Invoke  the  action  of  the  menu  entry.  See the
              sections  on  the  individual  entries  above   for
              details  on  what  happens.   If  the menu entry is
              disabled then nothing happens.  If the entry has  a
              command  associated with it then the result of that
              command is returned as the  result  of  the  invoke
              widget  command.   Otherwise the result is an empty
              string.  Note:  invoking  a  menu  entry  does  not
              automatically   unpost   the   menu;   the  default
              bindings normally take care of this before invoking
              the invoke widget command.

       pathName post x y
              Arrange  for the menu to be displayed on the screen
              at the root-window coordinates given by  x  and  y.
              These  coordinates  are  adjusted  if  necessary to
              guarantee that the entire menu is  visible  on  the
              screen.   This  command  normally  returns an empty
              string.   If  the  postCommand  option   has   been
              specified,  then  its  value  is  executed as a Tcl
              script before posting the menu and  the  result  of
              that  script  is returned as the result of the post
              widget  command.   If  an   error   returns   while
              executing  the  command, then the error is returned
              without posting the menu.

       pathName postcascade index
              Posts the submenu associated with the cascade entry
              given  by  index, and unposts any previously posted
              submenu.  If index doesn't correspond to a  cascade
              entry, or if pathName isn't posted, the command has
              no effect except to  unpost  any  currently  posted
              submenu.

       pathName type index
              Returns  the type of the menu entry given by index.
              This is the type argument passed to the add  widget
              command when the entry was created, such as command
              or separator, or tearoff for a tear-off entry.

       pathName unpost
              Unmap the window so that it is no longer displayed.
              If  a  lower-level  cascaded menu is posted, unpost
              that  menu.   Returns   an   empty   string.   This
              subcommand   does  not  work  on  Windows  and  the
              Macintosh, as those platforms have their own way of
              unposting menus.

       pathName yposition index
              Returns  a  decimal  string giving the y-coordinate
              within the menu window of the topmost pixel in  the
              entry specified by index.


MENU CONFIGURATIONS
       The  default bindings support four different ways of using
       menus:

       Pulldown Menus in Menubar
              This is the most command case. You  create  a  menu
              widget  that will become the menu bar. You then add
              cascade entries to this menu, specifying  the  pull
              down  menus  you  wish to use in your menu bar. You
              then create all of the  pulldowns.  Once  you  have
              done  this, specify the menu using the -menu option
              of the toplevel's widget command. See the  toplevel
              manual entry for details.

       Pulldown Menus in Menu Buttons
              This  is  the  compatable way to do menu bars.  You
              create one menubutton  widget  for  each  top-level
              menu,   and  typically  you  arrange  a  series  of
              menubuttons in a row in a menubar window.  You also
              create   the   top-level  menus  and  any  cascaded
              submenus, and tie them together with -menu  options
              in  menubuttons and cascade menu entries.  The top-
              level menu must be a child of the  menubutton,  and
              each  submenu  must  be  a  child  of the menu that
              refers to it.  Once you have done this, the default
              bindings  will  allow  users to traverse and invoke
              the tree of menus  via  its  menubutton;   see  the
              menubutton manual entry for details.

       Popup Menus
              Popup  menus  typically post in response to a mouse
              button press or keystroke.  You  create  the  popup
              menus  and any cascaded submenus, then you call the
              tk_popup procedure at the appropriate time to  post
              the top-level menu.

       Option Menus
              An  option  menu  consists  of a menubutton with an
              associated menu that allows you to  select  one  of
              several  values.  The current value is displayed in
              the menubutton and  is  also  stored  in  a  global
              variable.    Use  the  tk_optionMenu  procedure  to
              create option menubuttons and their menus.

       Torn-off Menus
              You create a torn-off menu by invoking the tear-off
              entry  at the top of an existing menu.  The default
              bindings will create a new menu that is a  copy  of
              the  original  menu and leave it permanently posted
              as a top-level window.  The torn-off  menu  behaves
              just the same as the original menu.


DEFAULT BINDINGS
       Tk  automatically  creates  class  bindings for menus that
       give them the following default behavior:

       [1]    When the mouse enters a menu, the entry  underneath
              the  mouse  cursor  activates;   as the mouse moves
              around the menu, the active entry changes to  track
              the mouse.

       [2]    When  the mouse leaves a menu all of the entries in
              the menu deactivate, except  in  the  special  case
              where  the  mouse  moves  from a menu to a cascaded
              submenu.

       [3]    When a button is released over a menu,  the  active
              entry  (if  any) is invoked.  The menu also unposts
              unless it is a torn-off menu.

       [4]    The Space and Return keys invoke the  active  entry
              and unpost the menu.

       [5]    If  any  of  the  entries  in  a  menu have letters
              underlined  with  with  -underline   option,   then
              pressing  one  of  the  underlined  letters (or its
              upper-case or lower-case equivalent)  invokes  that
              entry and unposts the menu.

       [6]    The  Escape key aborts a menu selection in progress
              without invoking any entry.  It  also  unposts  the
              menu unless it is a torn-off menu.

       [7]    The  Up  and  Down keys activate the next higher or
              lower entry in the menu.  When one end of the  menu
              is  reached,  the  active entry wraps around to the
              other end.

       [8]    The Left key moves to the next menu  to  the  left.
              If the current menu is a cascaded submenu, then the
              submenu is unposted  and  the  current  menu  entry
              becomes  the  cascade  entry in the parent.  If the
              current menu is a  top-level  menu  posted  from  a
              menubutton, then the current menubutton is unposted
              and the next menubutton  to  the  left  is  posted.
              Otherwise  the  key  has no effect.  The left-right
              order  of  menubuttons  is  determined   by   their
              stacking   order:    Tk  assumes  that  the  lowest
              menubutton (which  by  default  is  the  first  one
              created) is on the left.

       [9]    The  Right key moves to the next menu to the right.
              If the current entry is a cascade entry,  then  the
              submenu  is  posted  and  the   current  menu entry
              becomes the first entry in the submenu.  Otherwise,
              if  the  current menu was posted from a menubutton,
              then the current menubutton  is  unposted  and  the
              next menubutton to the right is posted.

       Disabled  menu  entries  are  non-responsive:   they don't
       activate  and  they  ignore  mouse  button   presses   and
       releases.

       The  behavior  of  menus  can  be  changed by defining new
       bindings for individual widgets or by redefining the class
       bindings.


BUGS
       At present it isn't possible to use the option database to
       specify values for the options to individual entries.


KEYWORDS
