ActiveTcl User Guide
| |
ActiveTcl User Guide
|
|
iwidgets::menubar pathName ?options? itk::Widget <- iwid- gets::Menubar
activeBackground activeBorderWidth activeForeground
tions.
motion over a menu entry. This global variable is updated with
the current value of the active menu entry's helpStr. Other
wid- gets 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
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.
of menubuttons on the menubar frame. Each menubutton entry is
de- limited 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 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.
_________________________________________________________________
pathName argument) and makes it into a menubar menu widget. Addi- tional 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 com- mand returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but path-
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.
guage". 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 al- so accept the menu option for specifying a list of menu entries to be added to the cascade's menu. menubar also extends the set of options for menu entries to in- clude 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 corre- spond 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 menubut- ton(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.
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 wid- gets. 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.
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.
components are automatically created via the -menu option on menubuttons and cascades or via the add or insert commands. menu
ton prefix. For example, .file.menu specifies the menu pane at- tached 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.
one of the keywords last, menu, end, nor may it be a numeric val- ue (integer). The iwidgets::menubar command creates a new Tcl command whose name is pathName. This command may be used to in- voke various operations on the widget. It has the following gen- eral form:
pathName option ?arg arg ...?
option and the args determine the exact behavior of the command.
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:
separator it adds a new entry to the bottom of the menu denoted by the prefix of menuPathName. If additonal arguments are pre- sent, 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 asso- ciated entry, the variable denoted by helpVariable is set. Anoth- er widget can bind to the helpVariable and thus display status help. If the type of the component added is menubutton or cas*- cade, a menubutton or cascade is added to the menubar. If addi- tional 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 wid- gets. -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 con- figured. 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. Addi- tionally, it may not be a number. However the menuPathName may be referenced in this manner (see discussion of COMPONENT PATH
-menu option strings as did to -menubuttons option strings. See the earlier discussion on umenubuttons in the WIDGET-SPECIFIC
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_Con*- figureInfo for information on the format of this list). If option is specified with no value, then the command returns a list de- scribing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is spec- ified). 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.
menu entries.
menuPathName2 inclusive. If menuPathName2 is omitted then it de- faults to menuPathName. Returns an empty string.
bar frame will be destroyed. In this case menuPathName2 is ig- nored. pathName index menuPathName If menuPathName is of type menubutton or menu, it returns the position of the menu/menubut- ton on the menubar frame.
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 menu-
component inserted is of type Menu and given the name name. In this case valid option value pairs are those accepted by menubut- tons. If menuPathName is of type Entry, the new component in- serted is of type entry and given the name name. In this case, valid option value pairs are those accepted by menu entries.
it may not be a number. However the menuPathName may be refer- enced 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 en- tries 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.
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 describ- ing all of the available options for menuPathName (see Tk_Config*- ureInfo 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 identical to the cor- responding sublist of the value returned if no option is speci- fied). 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 op- tions. pathName path ?mode? pattern Returns a fully formed menu-
-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 com- mand. -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. path-
fied by menuPathName. For menu entries, this is the type argument passed to the add/insert widget command when the entry was creat- ed, 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. The following example creates a menubar with File", Edit", Options menubut- tons. Each of these menubuttons has an associated menu. In turn the File menu has menu entries, as well as the Edit menu and the
(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
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
.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
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
en- closing candidate substitutions in curly braces ({}). This en-
sures, 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
}
subst command is used on the menubutton specification. In addi- tion, the [scope...] command will expand to @scope :: var. By en- closing these inside {} they stay as a single value. Note that only {} work for this. [list...], etc. will not protect these from the subst command. Bret Schumaker 1994 - Early work on a menubar widget. Mark Ulferts, Mark Harrison, John Sigler Invalu- able feedback on grammar and usability of the menubar widget Bill