NAME
iwidgets::menubar - Create and manipulate menubar menu widgets
SYNOPSIS
iiwwiiddggeettss::::mmeennuubbaarr pathName ?options? IINNHHEERRIITTAANNCCEEitk::Widget <- iwidgets::Menubar
SSTTAANNDDAARRDD OOPPTTIIOONNSS aaccttiivveeBBaacckkggrroouunndd aaccttiivveeBBoorrddeerrWWiiddtthh aaccttiivveeFFoorreeggrroouunndd aanncchhoorr bbaacckkggrroouunndd bboorrddeerrWWiiddtthh ccuurrssoorr ddiissaabblleeddFFoorreeggrroouunndd ffoonntt ffoorreeggrroouunndd hhiigghhlliigghhttBBaacckkggrroouunndd hhiigghhttlliigghhttCCoolloorr hhiigghhlliiggtthhTThhiicckknneessss jjuussttiiffyy rreelliieeff ppaaddXX ppaaddYY wwrraappLLeennggtthh See the "options" manual entry for details on the standard options.WWIIDDGGEETT-SSPPEECCIIFFIICC OOPPTTIIOONNSS
Name: hheellppVVaarriiaabbllee Class: HHeellppVVaarriiaabblleeCommand-Line Switch: -hheellppvvaarriiaabbllee
Specifies the global variable to update whenever the mouse is in motion over a menu entry. This global variable is updated withthe current value of the active menu entry's hheellppSSttrr. Other wid-
gets can "watch" this variable with the trace command, or as is the case with entry or label widgets, they can set theirtteexxttVVaarriiaabbllee to the same global variable. This allows for a sim-
ple 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: mmeennuuBBuuttttoonnss Class: MMeennuuBBuuttttoonnssCommand-Line Switch: -mmeennuubbuuttttoonnss
The menuButton option is a string which specifies the arrange-
ment 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 com-
mand call. The mmeennuuBBuuttttoonnss 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 iiwwiiddggeettss::::mmeennuubbaarr command creates a new window (given by the path-
Name argument) and makes it into a mmeennuubbaarr 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 iiwwiiddggeettss::::mmeennuubbaarr 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 mmeennuubbaarr is a widget that simplifies the task of creating menu hierar-
chies. It encapsulates a ffrraammee widget, as well as mmeennuubbuuttttoonnss, mmeennuuss,and menu eennttrriieess. The menubar allows menus to be specified and refer-
enced in a more consistent manner than using Tk to build menus directly. MMeennuubbaarr allows a menu tree to be expressed in a hierachical "language".The mmeennuubbaarr accepts a mmeennuuBBuuttttoonnss option that allows a list of menubut-
tons to be added to the menubar. In turn, each menubutton accepts a mmeennuu option that specifies a list of menu entries to be added to the menubutton's menu. Cascade entries also accept the mmeennuu 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 hheellppSSttrr option.MENU PATH NAMES
A menuPathName is a series of component names separated by the `.'character. Each menubar component can be referenced via these menuPath-
Names. menuPathNames are similar to widget pathNames in Tk. Some corre-
spond directly to a widget pathName (components of type mmeennuu or mmeennuubbuuttttoonn), others correspond to a menu entry type. Every widget andentry in a menubar can be referenced with the menuPathName naming con-
vention. A menubar can have four types of components:ffrraammee. A menubar holds exactly one frame which manages menubut-
tons. The frame is always signified by the `.' character as the path name.mmeennuubbuuttttoonn. A menubutton corresponds directly to a Tk menubut-
ton. See menubutton(n). mmeennuu. 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 mmeennuu. See menu(n). eennttrryy. An entry corresponds directly to Tk's menu widget entries. Menus consist of a column of one line entries. Entries may be of type: ccoommmmaanndd, cchheecckkbbuuttttoonn, rraaddiioobbuuttttoonn, sseeppaarraattoorr, orccaassccaaddee. For a complete description of these types see the dis-
cussion on EENNTTRRIIEESS in menu(n). The suffix of a menuPathName may have the form of: tkWidgetName Specifies the name of the component, either a ffrraammee, mmeennuubbuuttttoonn, mmeennuu, or an eennttrryy. This is the normal naming of widgets. For example, .file references a mmeennuubbuuttttoonn 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 menubut-
tons, 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.eenndd Specifes the last component. For menubuttons, it speci-
fies the right-most entry of the menu bar frame. For menu
entries, it specifies the bottom-most entry of the menu.
llaasstt Same as end.Finally, menu components always end with the mmeennuu keyword. These compo-
nents are automatically created via the -menu option on menubuttons and
cascades or via the aadddd or iinnsseerrtt commands. mmeennuu 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 oneof the keywords last, menu, end, nor may it be a numeric value (inte-
ger).WWIIDDGGEETT-SSPPEECCIIFFIICC MMEETTHHOODDSS
The iiwwiiddggeettss::::mmeennuubbaarr 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 argu-
ment a path name to a menu component. These path names are called menu-
ahae. e te icsin n MENUBAR PATH NAMES bv.
The following commands are possible for menubar widgets: pathName aadddd 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 avail-
able to component type eennttrryy. See the man pages for mmeennuu(1) in the section on EENNTTRRIIEESS. If type is one of ccaassccaaddee, cchheecckkbbuuttttoonn, ccoommmmaanndd, rraaddiioobbuuttttoonn, or sseeppaarraattoorr 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 eennttrryy widgets. In addition, the hheellppSSttrr option is added by the menubar widget to all components of type entry.-hheellppssttrr value
Specifes the string to associate with the entry. When the mouse moves over the associated entry, the variable denoted by hheellppVVaarriiaabbllee is set. Another widget can bind to the helpVariable and thus display status help. If the type of the component added is mmeennuubbuuttttoonn or ccaassccaaddee, 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 mmeennuu option isadded by the menubar widget to all menubutton and cascade wid-
gets.-mmeennuu menuSpec
This is only valid for menuPathNames of type mmeennuubbuuttttoonn or ccaassccaaddee. Specifes an option set and/or a set of entries to place on a menu and associate with the menubutton or cascade. The ooppttiioonn keyword allows the menu widget to be configured. Each item in the menuSpec is treated as add commands (each with the possibility ofhaving other -menu options). In this way a menu can be
recursively built. The last segment of menuPathName cannot be one of the keywords llaasstt, mmeennuu, eenndd. Additionally, it may not be a number. However the menuPathName may be referenced inhs anr se icsin f COMPONENT PATH NAMES.
Note that the same curly brace quoting rules apply to-mmeennuu option strings as did to -mmeennuubbuuttttoonnss option
strings. See the earlier discussion on uummeennuubbuuttttoonnss inthe "WWIIDDGGEETT-SSPPEECCIIFFIICC OOPPTTIIOONNSS" section.
pathName ccggeett option Returns the current value of the configuration option given by option. pathName ccoonnffiigguurree ?options value option value? Query or modify the configuration options of the widget. If nooption is specified, returns a list describing all of the avail-
able options for ppaatthhNNaammee (see TTkkCCoonnffiigguurreeIInnffoo 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 moreoption-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 ddeelleettee menuPathName ?menuPathName2? If menuPathName is of component type MMeennuubbuuttttoonn or MMeennuu, delete operates on menus. If menuPathName is of component type EEnnttrryy, 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 iinnddeexx 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 ccoommmmaanndd, sseeppaarraattoorr, rraaddiioobbuuttttoonn, cchheecckkbbuuttttoonn, or ccaassccaaddee, it returns the menu widget's numerical index for the entry corresponding to menuPathName. If path isnot found or the path is equal to ".", a value of -1 is
returned. pathName iinnsseerrtt menuPathName type name ?option value? Insert a new component named name before the component specified by menuPathName. If menuPathName is of type MMeennuubbuuttttoonn or MMeennuu, the new component inserted is of type MMeennuu and given the name name. In this case valid option value pairs are those accepted by menubuttons. If menuPathName is of type EEnnttrryy, the new component inserted is of type eennttrryy 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 llaasstt, mmeennuu, eenndd. Additionally, it may not be a number. However the menuPathName may be referencedn hs anr se icsin f COMPONENT PATH NAMES.
pathName iinnvvookkee 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 commandis returned as the result of the iinnvvookkee widget command. Other-
wise the result is an empty string. If menuPathName is not a menu entry, an error is issued. pathName mmeennuuccggeett menuPathName option Returns the current value of the configuration option given by option. The component type of menuPathName determines the valid available options. pathName mmeennuuccoonnffiigguurree 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 menu-
PathName (see TTkkCCoonnffiigguurreeIInnffoo for information on the format ofthis list). If option is specified with no value, then the com-
mand returns a list describing the one named option (this list will be identical to the corresponding sublist of the valuereturned 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 ppaatthh ?mode? pattern Returns a fully formed menuPathName that matches pattern. If nomatch 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:-gglloobb Pattern is a glob-style pattern which is matched against
each component path using the same rules as the string match command.-rreeggeexxpp
Pattern is treated as a regular expression and matched against each component of the menuPathName using the samerules as the regexp command. The default mode is -glob.
pathName ttyyppee menuPathName Returns the type of the component specified by menuPathName. For menu entries, this is the type argument passed to the aadddd/iinnsseerrtt widget command when the entry was created, such as ccoommmmaanndd or sseeppaarraattoorr. Othewise it is either a mmeennuubbuuttttoonn or a mmeennuu. pathName yyppoossiittiioonn menuPathNameReturns a decimal string giving the y-coordinate within the menu
window of the topmost pixel in the entry specified by menuPath-
Name. If the menuPathName is not an entry, an error is issued. EEXXAAMMPPLLEE OONNEE:: UUSSIINNGG GGRRAAMMMMAARR 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.0iwidgets::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 sep1command 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 sep2command 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
EEXXAAMMPPLLEE TTWWOO:: UUSSIINNGG MMEETTHHOODDSSAlternatively the same menu could be created by using the add and con-
figure 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 sep1command 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
CCAAVVEEAATTSSThe -mmeennuubbuuttttoonnss option as well as the -mmeennuu option is evaluated by
menubar with the ssuubbsstt command. The positive side of this is that theoption string may contain variables, commands, and/or backslash substi-
tutions. However, substitutions might expand into more than a singleword. These expansions can be protected by enclosing candidate substi-
tutions 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 thessuubbsstt command is used on the menubutton specification. In addi-
tion, the [ssccooppee...] 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. AACCKKNNOOWWLLEEDDGGMMEENNTTSS Bret Schumaker1994 - Early work on a menubar widget.
Mark Ulferts, Mark Harrison, John SiglerInvaluable feedback on grammar and usability of the menubar wid-
get AUTHOR Bill W. Scott KKEEYYWWOORRDDSS frame, menu, menubutton, entries, help Tk iwidgets::menubar(1)