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 Macin­ |
              tosh 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 num­
              ber 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

              ifies  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 menubut­ |
              ton 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 nor­ |
              mal, 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  out­ |
              side 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 sev­ |
       eral different types of entries, each with different prop­ |
       erties.   Entries  of different types may be combined in a |
       single menu.  Menu entries are not the same as entry  wid­ |
       gets.   In  fact,  menu entries are not even distinct wid­ |
       gets; the entire menu is one widget.

       Menu entries are  displayed  with  up  to  three  separate

       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  sec­
       ond  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  <<MenuSe­ |
       lect>>  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 com­
       mand 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 par­
       ticular global variable (as determined by the -onvalue and

       lected 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 dis­
       played in the background color for the menu.  If  a  -com­
       mand 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 vari­
       able then they are in the same group.  An  indicator  dia­
       mond  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  indica­
       tor'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 construc­
       tion  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 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  com­
       mand.   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, when­ |
       ever the toplevel is in front, this menu's  cascade  items |
       will appear in the menubar across the top of the main mon­ |
       itor. On Windows and Unix, this menu's items will be  dis­ |
       played  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.                                    |

       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 proce­ |
       dure 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 dis­ |
       played. 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 con­ |
       tents 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,  col­ |
       ors, 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 orig­ |
       inal  are  reflected  in the clone. Additionally, any cas­ |
       cades 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 orig­ |
       inal 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.

       ment an indicator of which entry of the  menu  to  operate
       on.  These indicators are called indexes and may be speci­
       fied in any of the following forms:

       number      Specifies the entry numerically, where 0  cor­
                   responds  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 equiv­
                   alent to none.  This form may not be  abbrevi­
                   ated.

       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-coordi­
                   nate 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 pat­
                   tern-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  wid­
       gets:

       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

              cascade, checkbutton, command, radiobutton, or sep­
              arator,  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 dis­
                     playing 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 dis­
                     playing 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 dis­
                     playing  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


              -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 dis­
                     playing  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.

                     Available only for checkbutton and radiobut­
                     ton entries.  Value is a boolean that deter­
                     mines whether or not the indicator should be
                     displayed.

              -label value
                     Specifies a string to display as an  identi­
                     fying  label  in the menu entry.  Not avail­
                     able for separator or tear-off entries.

              -menu value
                     Available only for cascade entries.   Speci­
                     fies 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 dese­
                     lected.

              -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 radiobut­
                     ton 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 radiobut­
                     ton  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 fore­
                     ground option for the  menu  and  the  back­
                     ground  option  from  the entry or the menu.
                     The active state is typically used when  the

                     the entry is displayed using the activeFore­
                     ground  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 radiobut­
                     ton 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 dese­
                     lect 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  newPath­ |
              Name.  This  clone  is a menu in its own right, but |

              original menu and vice versa. cloneType can be nor­ |
              mal, 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  path­
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ­
              ing the one named option (this list will be identi­
              cal  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  indi­
              vidual  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 com­
              mand.  If options are specified, options are  modi­
              fied  as  indicated  in the command and the command
              returns an empty string.  If no options are  speci­
              fied, returns a list describing the current options
              for entry index (see Tk_ConfigureInfo for  informa­
              tion 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

              menu.  The type, option, and value  arguments  have
              the  same interpretation as for the add widget com­
              mand.  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  sec­
              tions  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 com­
              mand.  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 speci­
              fied, 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 subcom­ |
              mand does not work on Windows and the Macintosh, as |

              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 sub­
              menus, 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 vari­
              able.   Use  the  tk_optionMenu procedure to create
              option menubuttons and their 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 under­
              lined 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

              menubutton (which by default is the first one  cre­
              ated) 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 bind­
       ings 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

       menu, widget


Man(1) output converted with man2html