|
ActiveTcl User Guide |
|
menubar - Create and manipulate menubar menu widgets
SYNOPSIS
menubar pathName ?options?
INHERITANCE
itk::Widget <- menubar
STANDARD OPTIONS
activeBackground
activeBorderWidth
activeForeground
anchor
foreground
|
borderWidth
cursor
disabledForeground
font
padX
|
highlightBackground
highligthThickness
highlightColor
justify
|
padY
relief
wrapLength
background
|
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.
-menubuttons
-text
-text
-text
|
{
File
Edit
Options
|
menubar
menubutton
menubutton
menubutton
}
|
.mb
file
edit
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
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 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 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.
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
-height
-textvariable
-anchor
-expand
-fill
pack
-fill
EXAMPLE
Alternatively
could
using
configure
menubar
-menubuttons
-text
command
command
separator
-label
edit
.edit.undo
0
.edit.sep2
.edit.cut
1
.edit.copy
1
.edit.paste
0
.options
{
viewMode
-label
byDate
-value
Date"
cascade
-menu
-label
-label
.mb
nw
yes
option
the
evaluated
the
positive
is
string
commands,
However,
into
single
can
enclosing
curly
ensures,
value
will
as
and
The
this
Menu"
menubar
menubutton
menubutton
-menu
\\
-variable
-onvalue
0
-text
|
.fr
300
helpVar
nw
yes
both
.ef
x
TWO:
the
be
the
methods:
.mb
{
File
new
close
sep1
Quit
-text
.mb
-label
.mb
.mb
-label
.mb
-label
.mb
-label
.mb
-text
radiobutton
\\
"by
-variable
DATE
}
.options.prefs
{
Colors...
Fonts...
-side
-fill
CAVEATS
as
-menu
by
subst
side
that
may
and/or
substitutions
more
word.
be
candidate
braces
for
for
still
a
not
following
case:
set
set
.mb
file
edit
{
-label
{[scope
1
}
Options
|
-width
entry
pack
-fill
pack
-expand
-anchor
-expand
USING
same
created
add
.mb
menubutton
-menu
-label
-label
command
}
Edit
add
Undo
add
add
Cut
add
Copy
add
Paste
add
Options
byName
-value
Name"
viewMode
-label
.mb
-label
command
command
}
left
x
The
well
option
menubar
command.
of
the
contain
backslash
might
than
These
protected
substitutions
({}).
example,
an
be
single
multiple
example
fileMenuName
var
-menubuttons
-text
-text
checkbutton
Check
var]}
\\
menubutton
}
300
.ef
.mb
x
.fr
yes
sw
yes
METHODS
menu
by
and
configure
file
{
New
Close
quit
menubutton
}
command
-underline
separator
command
-underline
command
-underline
command
-underline
menubutton
-menu
-variable
NAME
radiobutton
\\
"by
add
Preferences
colors
fonts
pack
-anchor
-expand
-menubuttons
as
is
with
The
this
option
variables,
substitutions.
expand
a
expansions
by
in
This
a
option
treated
value
values.
illustrates
"File
{}
{
{$fileMenuName}
Edit
check
\\
\\
-offvalue
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 |