Provided by: iwidgets4-doc_4.1.0-1_all bug

NAME

       iwidgets::menubar - Create and manipulate menubar menu widgets

SYNOPSIS

       iwidgets::menubar pathName ?options?

INHERITANCE

       itk::Widget <- iwidgets::Menubar

STANDARD OPTIONS

       activeBackground      activeBorderWidth     activeForeground
       anchor                background            borderWidth
       cursor                disabledForeground    font
       foreground            highlightBackground   hightlightColor
       highligthThickness    justify               relief
       padX                  padY                  wrapLength

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

              iwidgets::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  iwidgets::menubar  command  creates a new window (given by the pathName 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 iwidgets::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 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 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 referenced 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 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 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 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 .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  iwidgets::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
              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 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
                     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 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  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 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.

       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  menuPathName  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  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 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 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.

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

       pathName menucget menuPathName option
              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 componet 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 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. The component type of menuPathName determines 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 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.  package require Iwidgets 4.0 iwidgets::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:

        package require Iwidgets 4.0
        iwidgets::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  variables,
       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 example illustrates  this
       case:

              set fileMenuName "File Menu"
              set var {}
              iwidgets::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