NAME

       menubar - Create and manipulate menubar menu widgets


SYNOPSIS

       menubar pathName ?options?


INHERITANCE

       itk::Widget <- menubar


STANDARD OPTIONS

       activeBackground               borderWidth     highlightBackgroundpadY
       activeBorderWidth              cursor          highligthThicknessrelief
       activeForeground               disabledForegroundhighlightColorwrapLength
       anchor          font           justify
       background      foreground     padX

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


WIDGET-SPECIFIC OPTIONS

       Name:           helpVariable
       Class:          HelpVariable
       Command-Line Switch:           -helpvariable

              Specifies the global variable  to  update  whenever
              the  mouse  is  in  motion  over a menu entry. This
              global variable is updated with the  current  value
              of  the  active menu entry's helpStr. Other widgets
              can "watch" this variable with the  trace  command,
              or as is the case with entry or label widgets, they
              can set their textVariable to the same global vari­
              able.  This allows for a simple implementation of a
              help status bar. Whenever the mouse leaves  a  menu
              entry,  the helpVariable is set to the empty string
              {}. The mainwindow(1) associates its helpstatus and
              its menubar in this fashion.

       Name:           menuButtons
       Class:          MenuButtons
       Command-Line Switch:           -menubuttons

              The  menuButton  option is a string which specifies
              the  arrangement  of  menubuttons  on  the  menubar
              frame.  Each  menubutton  entry is delimited by the
              newline character.

              menubar .mb -menubuttons {
                      menubutton file -text File
                      menubutton edit -text Edit
                      menubutton options -text Options
              }

              the  menubar  (file,  edit, options). Each entry is
              translated into an add command call.

              The menuButtons option can  accept  embedded  vari­
              ables,  commands,  and  backslash quoting. Embedded
              variables and commands must be  enclosed  in  curly
              braces ({}) to ensure proper parsing of the substi­
              tuted values.
_________________________________________________________________


DESCRIPTION

       The menubar command creates a new  window  (given  by  the
       pathName  argument)  and makes it into a menubar menu wid­
       get. Additional options, described above may be  specified
       on the command line or in the option database to configure
       aspects of the menubar such as its colors  and  font.  The
       menubar 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 menubar is a widget that simplifies the task of creating
       menu hierarchies. It encapsulates a frame widget, as  well
       as  menubuttons,  menus,  and  menu  entries.  The menubar
       allows menus to be specified and referenced in a more con­
       sistent manner than using Tk to build menus directly.

       Menubar  allows a menu tree to be expressed in a hierachi­
       cal "language". The menubar accepts a  menuButtons  option
       that  allows  a  list  of  menubuttons  to be added to the
       menubar. In turn, each menubutton accepts  a  menu  option
       that  specifies  a list of menu entries to be added to the
       menubutton's menu. Cascade entries also  accept  the  menu
       option  for  specifying a list of menu entries to be added
       to the cascade's menu.

       Additionally, the menubar allows  each  component  of  the
       menubar  system  to be referenced by a simple menuPathName
       syntax. The menubar also extends the set  of  options  for
       menu entries to include a helpStr option.


MENU PATH NAMES

       A menuPathName is a series of component names separated by
       the `.' character. Each menubar component  can  be  refer­
       enced  via  these menuPathNames. menuPathNames are similar
       to widget pathNames in Tk. Some correspond directly  to  a
       widget  pathName  (components of type menu or menubutton),
       others correspond to a menu entry type. Every  widget  and
       entry in a menubar can be referenced with the menuPathName
       naming convention. A menubar can have four types of compo­
       nents:

              frame. A menubar holds exactly one frame which man­
              ages menubuttons. The frame is always signified  by


              menubutton.  A menubutton corresponds directly to a
              Tk menubutton. See menubutton(n).

              menu. A menu is attached to a menubutton and corre­
              sponds  directly  to  Tk's  menu  widget. A menu is
              always signified by the  menuPathName  ending  with
              the keyword menu. See menu(n).

              entry.  An  entry corresponds directly to Tk's menu
              widget entries. Menus consist of a  column  of  one
              line  entries.  Entries  may  be  of type: command,
              checkbutton, radiobutton,  separator,  or  cascade.
              For  a  complete description of these types see the
              discussion on ENTRIES in menu(n).

       The suffix of a menuPathName may have the form of:

       tkWidgetName  Specifies the name of the component,  either
                     a frame, menubutton, menu, or an entry. This
                     is the normal naming of widgets.  For  exam­
                     ple,  .file  references  a  menubutton named
                     file.

       The menuPathName is a series of segment names, each  sepa­
       rated  by  the  '.' character. Segment names may be one of
       the following forms:

       number        Specifies the index of  the  the  component.
                     For  menubuttons, 0 corresponds to the left-
                     most menubutton of the menu bar frame. As an
                     example,  .1  would correspond to the second
                     menubutton on the menu bar frame.

                     For entries, 0 corresponds to  the  top-most
                     entry  of  the  menu.  For  example, .file.0
                     would correspond to the first entry  on  the
                     menu  attached to the menubutton named file.

       end           Specifes the last  component.  For  menubut­
                     tons,  it  specifies the right-most entry of
                     the menu bar frame.  For  menu  entries,  it
                     specifies the bottom-most entry of the menu.

       last          Same as end.

       Finally, menu components always end with the menu keyword.
       These  components  are automatically created via the -menu
       option on menubuttons and  cascades  or  via  the  add  or
       insert commands.

       menu          Specifes  the  menu  pane that is associated
                     with  the  given  menubutton   prefix.   For

                     attached to the .file menubutton.

       For example, the path .file.new specifies the entry  named
       new  on  the  menu  associated  with  the  file menubutton
       located on the menu bar. The path .file.menu specifies the
       menu  pane  associated with the menubutton .file. The path
       .last specifies the last menu on the menu  bar.  The  path
       .0.last  would  specify the first menu (file) and the last
       entry on that menu (quit), yielding .file.quit.

       As a restriction, the last name  segment  of  menuPathName
       cannot  be one of the keywords last, menu, end, nor may it
       be a numeric value (integer).


WIDGET-SPECIFIC METHODS

       The menubar 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.

       In addition, many of the widget commands for menubar  take
       as  one  argument  a  path name to a menu component. These
       path names are called menuPathNames. See the discussion on
       MENUBAR PATH NAMES above.

       The following commands are possible for menubar widgets:

       pathName add type menuPathName ?option value option value?
              Adds either a menu to the menu bar or a menu  entry
              to a menu pane.

              If  additional  arguments are present, they specify
              options available to component type entry. See  the
              man pages for menu(1) in the section on ENTRIES.

              If  type  is  one of cascade, checkbutton, command,
              radiobutton, or separator it adds a  new  entry  to
              the  bottom  of  the  menu denoted by the prefix of
              menuPathName. If additonal arguments  are  present,
              they  specify  options available to menu entry wid­
              gets. In addition, the helpStr option is  added  by
              the menubar widget to all components of type entry.

              -helpstr value
                     Specifes the string to  associate  with  the
                     entry. When the mouse moves over the associ­
                     ated entry, the variable  denoted  by  help­
                     Variable  is set. Another widget can bind to

                     help.

              If the type of the component added is menubutton or
              cascade, a menubutton or cascade is  added  to  the
              menubar.  If additional arguments are present, they
              specify options available to menubutton or  cascade
              widgets.  In  addition, the menu option is added by
              the menubar widget to all  menubutton  and  cascade
              widgets.

              -menu menuSpec
                     This is only valid for menuPathNames of type
                     menubutton or cascade.  Specifes  an  option
                     set  and/or  a  set of entries to place on a
                     menu and associate with  the  menubutton  or
                     cascade.  The option keyword allows the menu
                     widget to be configured. Each  item  in  the
                     menuSpec  is  treated  as add commands (each
                     with the possibility of having  other  -menu
                     options).  In  this way a menu can be recur­
                     sively built.

                     The last segment of menuPathName  cannot  be
                     one  of  the keywords last, menu, end. Addi­
                     tionally, it may not be  a  number.  However
                     the  menuPathName  may be referenced in this
                     manner (see  discussion  of  COMPONENT  PATH
                     NAMES).

                     Note that the same curly brace quoting rules
                     apply to -menu  option  strings  as  did  to
                     -menubuttons option strings. See the earlier
                     discussion on umenubuttons in  the  "WIDGET-
                     SPECIFIC OPTIONS" section.

       pathName cget option
              Returns  the  current  value  of  the configuration
              option given by option.

       pathName configure ?options 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.

              If menuPathName is of component type Menubutton  or
              Menu,  delete operates on menus. If menuPathName is
              of component type Entry, delete  operates  on  menu
              entries.

              This  command  deletes all components between menu­
              PathName and menuPathName2 inclusive. If  menuPath­
              Name2  is omitted then it defaults to menuPathName.
              Returns an empty string.

              If menuPathName is of type menubar, then all  menus
              and  the  menu bar frame will be destroyed. In this
              case menuPathName2 is ignored.

       pathName index menuPathName
              If menuPathName is of type menubutton or  menu,  it
              returns  the position of the menu/menubutton on the
              menubar frame.

              If menuPathName  is  of  type  command,  separator,
              radiobutton,  checkbutton,  or  cascade, it returns
              the menu widget's numerical  index  for  the  entry
              corresponding to menuPathName. If path is not found
              or the path is equal to  ".",  a  value  of  -1  is
              returned.

       pathName insert menuPathName type name ?option value?
              Insert a new component named name before the compo­
              nent specified by menuPathName.

              If menuPathName is of type Menubutton or Menu,  the
              new  component  inserted  is of type Menu and given
              the name name. In  this  case  valid  option  value
              pairs are those accepted by menubuttons.

              If menuPathName is of type Entry, the new component
              inserted is of type entry and given the name  name.
              In  this  case,  valid option value pairs are those
              accepted by menu entries.  Name cannot  be  one  of
              the  keywords last, menu, end. Additionally, it may
              not be a number. However the  menuPathName  may  be
              referenced in this manner (see discussion of COMPO­
              NENT PATH NAMES).

       pathName invoke menuPathName
              Invoke the action of  the  menu  entry  denoted  by
              menuPathName.  See  the  sections on the individual
              entries in the menu(1) man pages. 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.

              issued.

       pathName menucget menuPathName option
              Returns the  current  value  of  the  configuration
              option given by option. The component type of menu­
              PathName determines the valid available options.

       pathName menuconfigure menuPathName ?option value?
              Query or modify the configuration  options  of  the
              componet  of the menubar specified by menuPathName.
              If no option is specified, returns a list  describ­
              ing  all  of the available options for menuPathName
              (see Tk_ConfigureInfo for information on the format
              of  this  list).  If  option  is  specified with no
              value, then the command returns a  list  describing
              the  one  named option (this list will be identical
              to the corresponding sublist of the value  returned
              if  no option is specified). If one or more option-
              value pairs are specified, then the  command  modi­
              fies  the  given widget option(s) to have the given
              value(s); in this case the command returns an empty
              string.  The  component type of menuPathName deter­
              mines the valid available options.

       pathName path ?mode? pattern
              Returns a fully formed  menuPathName  that  matches
              pattern.  If  no  match is found it returns -1. The
              mode argument indicates how the  search  is  to  be
              matched against pattern and it must have one of the
              following values:

              -glob  Pattern is a  glob-style  pattern  which  is
                     matched  against  each  component path using
                     the same rules as the string match  command.

              -regexp
                     Pattern  is  treated as a regular expression
                     and matched against each  component  of  the
                     menuPathName  using  the  same  rules as the
                     regexp command.  The default mode is  -glob.

       pathName type menuPathName
              Returns  the  type  of  the  component specified by
              menuPathName. For menu entries, this  is  the  type
              argument  passed  to  the add/insert widget command
              when the entry was created, such as command or sep­
              arator.  Othewise  it  is  either a menubutton or a
              menu.

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



EXAMPLE ONE: USING GRAMMAR

       The  following  example  creates  a  menubar  with "File",
       "Edit", "Options" menubuttons. Each of  these  menubuttons
       has  an  associated  menu.  In turn the File menu has menu
       entries, as well as the Edit menu and  the  Options  menu.
       The  Options  menu is a tearoff menu with selectColor (for
       radiobuttons) set to blue.  In addition, the Options  menu
       has  a  cascade  titled  More,  with  several menu entries
       attached to it as well. An entry  widget  is  provided  to
       display help status.

       menubar .mb -helpvariable helpVar -menubuttons {
           menubutton file -text File -menu {
               options -tearoff false
               command new -label New \
                   -helpstr "Open new document" \
                   -command {puts NEW}
               command close -label Close \
                   -helpstr "Close current document" \
                   -command {puts CLOSE}
               separator sep1
               command exit -label Exit -command {exit} \
                   -helpstr "Exit application"
           }
           menubutton edit -text Edit -menu {
               options -tearoff false
               command undo -label Undo -underline 0 \
                   -helpstr "Undo last command" \
                   -command {puts UNDO}
               separator sep2
               command cut -label Cut -underline 1 \
                   -helpstr "Cut selection to clipboard" \
                   -command {puts CUT}
               command copy -label Copy -underline 1 \
                   -helpstr "Copy selection to clipboard" \
                   -command {puts COPY}
               command paste -label Paste -underline 0 \
                   -helpstr "Paste clipboard contents" \
                   -command {puts PASTE}
           }
           menubutton options -text Options -menu {
               options -tearoff false -selectcolor blue
               radiobutton byName -variable viewMode \
                   -value NAME -label "by Name" \
                   -helpstr "View files by name order" \
                   -command {puts NAME}
               radiobutton byDate -variable viewMode \
                   -value DATE -label "by Date" \
                   -helpstr "View files by date order" \
                   -command {puts DATE}
               cascade prefs -label Preferences -menu {
                   command colors -label Colors... \

                       -command {puts COLORS}
                   command fonts -label Fonts... \
                       -helpstr "Change text font" \
                       -command {puts FONT}
               }
           }

       } frame .fr -width 300 -height 300 entry .ef -textvariable
       helpVar pack .mb -anchor nw -fill x -expand yes  pack  .fr
       -fill both -expand yes pack .ef -anchor sw -fill x -expand
       yes Alternatively the same menu could be created by  using
       the add and configure methods:

        menubar .mb
        .mb configure -menubuttons {
               menubutton file -text File -menu {
                       command new -label New
                       command close -label Close
                       separator sep1
                       command        quit -label Quit
               }
               menubutton edit -text Edit
        }
        .mb add command .edit.undo -label Undo -underline 0
        .mb add separator .edit.sep2
        .mb add command .edit.cut -label Cut -underline 1
        .mb add command .edit.copy -label Copy -underline 1
        .mb add command .edit.paste -label Paste -underline 0

        .mb add menubutton .options -text Options -menu {
               radiobutton byName -variable viewMode \
                        -value NAME -label "by Name"
               radiobutton byDate -variable viewMode \
                        -value DATE -label "by Date"
       }

        .mb add cascade .options.prefs -label Preferences -menu {
                       command colors -label Colors...
                       command fonts -label Fonts...
        }
        pack .mb -side left -anchor nw -fill x -expand yes


CAVEATS

       The  -menubuttons  option  as  well as the -menu option is
       evaluated by menubar with the subst command. The  positive
       side  of  this is that the option string may contain vari­
       ables, commands, and/or backslash substitutions.  However,
       substitutions  might  expand into more than a single word.
       These expansions can be protected by  enclosing  candidate
       substitutions  in  curly  braces  ({}).  This ensures, for
       example, a value for an option will still be treated as  a
       single  value and not multiple values. The following exam­
       ple illustrates this case:

              set var {}
              menubar .mb -menubuttons {
                      menubutton file -text {$fileMenuName}
                      menubutton edit -text Edit -menu {
                              checkbutton check \
                                      -label Check \
                                      -variable {[scope var]} \
                                      -onvalue 1 \
                                      -offvalue 0
                      }
                      menubutton options -text Options
              }

              The variable  fileMenuName  will  expand  to  "File
              Menu"  when  the  subst  command  is  used  on  the
              menubutton   specification.   In   addition,    the
              [scope...] command will expand to @scope :: var. By
              enclosing these inside {} they  stay  as  a  single
              value.  Note that only {} work for this. [list...],
              "" etc. will not protect these from the subst  com­
              mand.


ACKNOWLEDGMENTS

       Bret Schumaker

              1994 - Early work on a menubar widget.

       Mark Ulferts, Mark Harrison, John Sigler

              Invaluable feedback on grammar and usability of the
              menubar widget


AUTHOR

       Bill W. Scott


KEYWORDS

       frame, menu, menubutton, entries, help


Man(1) output converted with man2html