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

              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, fol-
              lowed 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
       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  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
       -variable options for the entry);  when the entry is dese-
       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   which only one entry mual  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

              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, fol-
              lowed 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
       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  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
       -variable options for the entry);  when the entry is dese-
       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   which only one entry mual  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

              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, fol-
              lowed 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
       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  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
       -variable options for the entry);  when the entry is dese-
       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   which only one entry mual  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

              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, fol-
              lowed 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
       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  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
       -variable options for the entry);  when the entry is dese-
       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   which only one entry mual  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

              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, fol-
              lowed 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
       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  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
       -variable options for the entry);  when the entry is dese-
       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  radiobutt