| iwidgets::menubar(1) | [incr Widgets] | iwidgets::menubar(1) |
iwidgets::menubar - Create and manipulate menubar menu widgets
iwidgets::menubar pathName ?options?
itk::Widget <- iwidgets::Menubar
activeBackground activeBorderWidth activeForeground anchor background borderWidth cursor disabledForeground font foreground highlightBackground hightlightColor highligthThickness justify relief padX padY wrapLength
See the "options" manual entry for details on the standard options.
Name: helpVariable Class: HelpVariable Command-Line Switch: -helpvariable
Name: menuButtons Class: MenuButtons Command-Line Switch: -menubuttons
iwidgets::menubar .mb -menubuttons {
menubutton file -text File
menubutton edit -text Edit
menubutton options -text Options
}
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.
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:
The suffix of a menuPathName may have the form of:
The menuPathName is a series of segment names, each separated by the '.' character. Segment names may be one of the following forms:
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.
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).
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:
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:
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.
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.
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.
If menuPathName is not a menu entry, an error is issued.
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
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
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
}
Bret Schumaker
Mark Ulferts, Mark Harrison, John Sigler
Bill W. Scott
frame, menu, menubutton, entries, help
| Tk |