menu(n)			     Ck Built-In Commands		       menu(n)



______________________________________________________________________________

NAME
       menu - Create and manipulate menu widgets

SYNOPSIS
       menu pathName ?options?

STANDARD OPTIONS
       activeAttributes		     background	    disabledForegroundunderlineForeground
       activeBackground		     border	    foreground
       activeForeground		     disabledAttributestakeFocus
       attributes     disabledBackground	    underlineAttributes

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

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

	      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.

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

	      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. On color terminals
	      this defaults to red, on monochrome terminals to white.
_________________________________________________________________


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  com-
       mand  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 a column.  There exist several different types of entries,
       each with different properties.	Entries of different types may be com-
       bined  in  a  single menu.  Menu entries are not the same as entry wid-
       gets. 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.	If  the	  -accelerator
       option  is  specified  for an entry then a second textual field is dis-
       played 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  indica-
       tor.   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 input focus is over the  entry.   If  a  mouse  button  is
       pressed	over the entry then the entry is invoked.  The effect of invo-
       cation 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 other 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.


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 com-
       mand  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 dese-
       lected 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 indi-
       cator'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 or menu entry.	 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  tog-
       gling 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	deter-
       mined  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	 back-
       ground color for the menu or menu entry.	 If a -command option is spec-
       ified 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 asso-
       ciated  menu  just  to  the right 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.
       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.

       If a -command option is specified for a cascade entry then it is evalu-
       ated as a Tcl command whenever the entry is invoked.


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 indica-
       tor 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, com-
	      mand, radiobutton, or separator, or a unique abbreviation of one
	      of the above.  If additional arguments are present, they specify
	      any of the following options:

	      -activeattributes value
		     Specifies video attributes to  use	 for  displaying  this
		     entry  when it is active.	If this option is specified as
		     an empty string (the default), then the  activeAttributes
		     option  for the overall menu is used.  This option is not
		     available for separator entries.

	      -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.  This option is not
		     available for separator 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 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 separa-
		     tor entries.

	      -attributes value
		     Specifies video attributes 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 attributes option for the
		     overall menu is used.  This option is not	available  for
		     separator 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 entries.

	      -command value
		     For command, checkbutton, and radiobutton entries, speci-
		     fies  a  Tcl  command  to	execute when the menu entry is
		     invoked.  For cascade entries, specifies a Tcl command to
		     execute when the entry is activated (i.e. just before its
		     submenu is posted).  Not available for separator 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 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 entries.

	      -menu value
		     Available only for cascade entries.  Specifies  the  path
		     name of the submenu associated with this entry.  The sub-
		     menu 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 deter-
		     mines the indicator color.

	      -state value
		     Specifies one of three states  for	 the  entry:   normal,
		     active,  or  disabled.  In normal state the entry is dis-
		     played using the attributes, foreground,  and  background
		     options  for the entry or for the menu.  The active state
		     is typically used when the input focus is in  the	entry.
		     In	  active  state	 the  entry  is	 displayed  using  the
		     activeAttributes, activeForeground, and  activeBackground
		     options  for  the	entry or for the menu.	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  dis-
		     abledAttributes,  disabledForeground,  and	 disabledBack-
		     ground options for the menu.  This option is  not	avail-
		     able 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.  This
		     option is not available for separator entries.

	      -underlineAttributes value
		     Specifies video attributes	 to  use  for  displaying  the
		     underlined character in this entry when it is in the nor-
		     mal state (neither active nor disabled).  If this	option
		     is	 specified  as an empty string (the default), then the
		     underlineAttributes option for the overall menu is	 used.
		     This option is not available for separator entries.

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

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

	      -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 radiobut-
		     ton 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 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 avail-
	      able options for pathName. 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	inclu-
	      sive.  If index2 is omitted then it defaults to index1.

       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  config-
	      ure 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.

       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 visi-
	      ble  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 com-
	      mand, 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.

       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.

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


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

       Pulldown Menus
	      This  is the most common case.  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  sub-
	      menu  must  be  a child of the menu that refers to it.  Once you
	      have done this, the default bindings will allow  users  to  tra-
	      verse  and invoke the tree of menus via its menubutton;  see the
	      menubutton manual entry for details.

       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  ck_optionMenu  procedure to create
	      option menubuttons and their menus.


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

       [1]    When button 1 is pressed on a menu, the active entry (if any) is
	      invoked.	The menu also unposts.

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

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

       [4]    The Escape key aborts  a	menu  selection	 in  progress  without
	      invoking any entry. It also unposts the menu.

       [5]    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.

       [6]    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:  Ck assumes that the lowest menubutton (which by  default
	      is the first one created) is on the left.

       [7]    The  Right key moves to the next menu to the right.  If the cur-
	      rent 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 indi-
       vidual widgets or by redefining the class bindings.


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


KEYWORDS
       menu, widget



Ck				      8.0			       menu(n)
