# iwidgets2.2.0 User Commands - menubar

##

## 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 vari-
              able 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 variable. 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
              }

              specifies that three menubuttons will be added  to  the
              menubar (file, edit, options). Each entry is translated
              into an add command call.

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

##

## DESCRIPTION

         The menubar command creates a new window (given by the path-
         Name  argument)  and  makes  it  into a menubar menu widget.
         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 com-
         mand 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 consistent
         manner than using Tk to build menus directly.

         Menubar allows a menu tree to be expressed in a  hierachical
         "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 menu-
         bar 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 referenced
         via these menuPathNames. menuPathNames are similar to widget
         pathNames  in Tk. Some correspond directly to a widget path-
         Name  (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  con-
         vention. A menubar can have four types of components:

              frame. A menubar holds exactly one frame which  manages
              menubuttons.  The  frame is always signified by the `.'
              character as the path name.
              menubutton. A menubutton corresponds directly to  a  Tk
              menubutton. See menubutton(n).

              menu.  A  menu  is  attached  to   a   menubutton   and
              corresponds  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  example,
                       .file references a menubutton named file.

         The  menuPathName  is  a  series  of  segment  names,   each
         separated  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  exam-
                       ple,  .1  would correspond to the second menu-
                       button 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  menubuttons,
                       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  example,
                       .file.menu specifies the menu pane attached to
                       the

         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 speci-
         fies 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 can-
         not  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 opera-
         tions on the widget. It has the following general form:

              pathName option ?arg arg ...?

         option and the args determine the exact behavior of the com-
         mand.

         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  MENU-
         BAR 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  menuPath-
              Name.  If additonal arguments are present, they specify
              options available to menu entry widgets.  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 associated entry,
                   the  variable  denoted  by  helpVariable  is  set.
                   Another  widget  can  bind to the helpVariable and
                   thus display status help.

              If the type of the component  added  is  menubutton  or
              cascade,  a menubutton or cascade is added to the menu-
              bar. 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 menu-
                   button 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 recursively
                   built.

                   The last segment of menuPathName 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 COM-
                   PONENT 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" sec-
                   tion.

         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  pathName
              (see  Tk_ConfigureInfo for information on the format of
              this list). If option is specified with no value,  then
              the  command  returns  a  list describing the one named
              option (this list will be identical to the  correspond-
              ing  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.

         pathName delete menuPathName ?menuPathName2?
              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  menuPath-
              Name  and  menuPathName2 inclusive. If menuPathName2 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 correspond-
              ing  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  component
              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 COMPONENT PATH NAMES).

         pathName invoke menuPathName
              Invoke the action of the menu entry  denoted  by  menu-
              PathName. 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 asso-
              ciated 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.

              If menuPathName is  not  a  menu  entry,  an  error  is
              issued.

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

         pathName menuconfigure menuPathName ?option value?
              Query or modify the configuration options of  the  com-
              ponet  of  the menubar specified by menuPathName. If no
              option is specified, returns a list describing  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 sub-
              list 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. The component type of menuPathName deter-
              mines the valid available options.

         pathName path ?mode? pattern
              Returns a fully formed menuPathName that  matches  pat-
              tern.  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  menu-
              PathName.  For  menu entries, this is the type argument
              passed to the add/insert widget command when the  entry
              was  created, such as command or separator. 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 menuPathName  is  not
              an entry, an error is issued.

## 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... \
                         -helpstr "Change text 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

## EXAMPLE TWO: USING METHODS

         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  exam-
         ple, a value for an option will still be treated as a single
         value and not multiple values. The following example  illus-
         trates this case:

              set fileMenuName "File Menu"
              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 command.

## 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