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 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 vari
able. 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
}
the menubar (file, edit, options). Each entry is
translated into an add command call.
The menuButtons option can accept embedded vari
ables, commands, and backslash quoting. Embedded
variables and commands must be enclosed in curly
braces ({}) to ensure proper parsing of the substi
tuted values.
_________________________________________________________________
DESCRIPTION
The menubar command creates a new window (given by the
pathName argument) and makes it into a menubar menu wid
get. 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 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 con
sistent manner than using Tk to build menus directly.
Menubar allows a menu tree to be expressed in a hierachi
cal "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 refer
enced 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 compo
nents:
frame. A menubar holds exactly one frame which man
ages menubuttons. The frame is always signified by
menubutton. A menubutton corresponds directly to a
Tk menubutton. See menubutton(n).
menu. A menu is attached to a menubutton and corre
sponds 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 exam
ple, .file references a menubutton named
file.
The menuPathName is a series of segment names, each sepa
rated 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 menubut
tons, 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
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 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 wid
gets. 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 associ
ated entry, the variable denoted by help
Variable is set. Another widget can bind to
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 recur
sively built.
The last segment of menuPathName cannot be
one of the keywords last, menu, end. Addi
tionally, 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 path
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ
ing the one named option (this list will be identi
cal 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.
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 menu
PathName and menuPathName2 inclusive. If menuPath
Name2 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 compo
nent 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 COMPO
NENT 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.
issued.
pathName menucget menuPathName option
Returns the current value of the configuration
option given by option. The component type of menu
PathName 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 describ
ing 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 modi
fies 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
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 sep
arator. 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
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... \
-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 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
example, a value for an option will still be treated as a
single value and not multiple values. The following exam
ple illustrates this case:
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 com
mand.
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
Man(1) output converted with
man2html