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