iwidgets::menubar - Create and manipulate menubar menu widgets

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

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.

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.

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

Inheritance

       itk::Widget <- iwidgets::Menubar

Keywords

       frame, menu, menubutton, entries, help

Tk                                                                                          iwidgets::menubar(1)

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

Name

       iwidgets::menubar - Create and manipulate menubar menu widgets

Standard Options

activeBackgroundactiveBorderWidthactiveForegroundanchorbackgroundborderWidthcursordisabledForegroundfontforegroundhighlightBackgroundhightlightColorhighligthThicknessjustifyreliefpadXpadYwrapLength

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

Synopsis

iwidgets::menubarpathName ?options?

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: pathNameoption ?argarg...? 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 MENUBARPATHNAMES above.

The following commands are possible for menubar widgets:

pathNameaddtypemenuPathName ?optionvalueoptionvalue?
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.

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

-menumenuSpec
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 COMPONENTPATHNAMES).

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-SPECIFICOPTIONS" section.

pathNamecgetoption
Returns the current value of the configuration option given by option.

pathNameconfigure ?optionsvalueoptionvalue?
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.

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

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

pathNameinsertmenuPathNametypename ?optionvalue?
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 optionvalue 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 optionvalue 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 COMPONENTPATHNAMES).

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

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

pathNamemenuconfiguremenuPathName ?optionvalue?
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.

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

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

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

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