The jmenu.tcl library provides procedures for creating menus and menubuttons. It provides concise ways to specify menus for command procedures as specified by the jcommand.tcl library, for options controlled with checkbuttons, and for viewing documentation. Those three kinds of menu entries can be interspersed in the same menu with each other and with ordinary menu entries defined with plain Tk code.
The jmenu.tcl library is distributed as part of the jstools package.
This document describes jmenu.tcl version 4.0/4.0.
In order to use the jmenu.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.
Jay Sekora
js@calumet.org
http://shore.net/~js/
The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.
j:menu:menubutton - create a menubutton and associated menu
j:menu:commands - create menu entries to perform command procedures
j:menu:command - alias for j:menu:commands
j:menu:checkbuttons - create checkbutton menu entries
j:menu:checkbutton - alias for j:menu:checkbuttons
j:menu:docs - create menu entries to look up documentation
j:menu:menubutton mb menu key
mb - name of new menubutton to create
menu - new menu to create and link to mb
key - key to look up mb's label and underline position under, via jldb.tcl
(See j:menu:commands for examples.)
This procedure creates a new menubutton mb and associated menu menu. (It's a common Tk convention for menu to be mb.m, although this isn't required.) Menu itself is not populated with menu entries, just created.
The menubutton will be labelled with the string associated with key in the current naturallanguage database, and the underline position (if any) in that string will also be taken from the database.
j:menu:command
j:menu:commands menu w cmds
or
j:menu:command menu w cmds
menu - menu to add the command menu entries to
w - window argument for the command procedures
cmds - list of command procedure to be performed by menu entries
j:menu:menubutton .menu.file File .menu.file.m
j:menu:commands .menu.file.m .text {
note:cmd:load
note:cmd:save
note:cmd:print
-
note:cmd:new
}
j:menu:menubutton $w.mb.help menu:help $w.mb.help.m
j:menu:command $w.mb.help.m $w.text note:cmd:help
See jcommand.tcl for a further example.
This procedure adds one or several command entries to menu, a menu which should already exist. (See the Tk man page for menu(n) for more information.) The text, underline position, and accelerator displayed in the menu are taken from the current naturallanguage string database as implemented in jldb.tcl.
When a menu entry is invoked, its corresponding command procedure will be invoked with w as its sole argument.
There must be a string translation for each command procedure in cmds, or the menu will display only the Tcl name of the command procedure. (The j:command:register procedure aids in ensuring that.)
The accelerator specified in the naturallanguage database, if any, will be displayed to the right of the menu entry text, but that doesn't automatically create an accelerator binding. You should do that explicitly with j:command:bind.
A single hyphen (`-') can appear anywhere in the cmds list, and will produce a separator line in the corresponding position in the menu.
There's currently no way to specify radiobutton entries, cascade submenus, or menu entries with bitmap rather than text labels. However, you can create them with ordinary Tk commands.
This procedure can be invoked either as j:menu:commands or j:menu:command; the two forms function identically, but j:menu:command may read more clearly when you're only adding a single command.
j:menu:checkbutton
j:menu:checkbutton[s] menu [options] list
menu - menu to append checkbutton entries to
list - list of {key variable} pairs
-command command (default {})
j:menu:menubutton .check .check.m Check...
j:menu:checkbuttons .check.m -command "parray check" {
{check_brakes check(brakes)}
{check_oil check(oil)}
{check_fuel check(fuel)}
}
This procedure adds one or several checkbutton entries to menu, a menu which should already exist.
For each entry in list, the text, underline position, and accelerator displayed are looked up based on key in the current naturallanguage string database (as implemented in jldb.tcl), and that entry will be associated with the global variable variable. When variable's value is 1 (true), the checkbutton will be highlighted. Otherwise (typically when variable's value is 0) it won't. Invoking the checkbutton toggles the state of variable.
If `-command command' is specified (and nonnull), then when any of the menu entries is invoked (after toggling the state of variable), command will be executed. Note that command must be a complete Tcl command with all its arguments, and need not be a `command procedure' in the sense required for j:menu:commands.
There must be a string translation for each key in list, or the menu will display only the key itself. (The j:ldb:set_defaults procedure aids in ensuring that, or you can just use keys that will make sense to the user.)
The accelerator specified in the naturallanguage database, if any, will be displayed to the right of the menu entry text, but that doesn't automatically create an accelerator binding. In order to support accelerators, you need to do that explicitly for each entry, e.g. by binding to a procedure that toggles the global variable.
A single hyphen (`-') can appear anywhere in the cmds list, and will produce a separator line in the corresponding position in the menu.
This procedure can be invoked either as j:menu:checkbuttons or j:menu:checkbutton; the two forms function identically, but j:menu:checkbutton may read more clearly when you're only adding a single entry.
j:menu:radiobutton
j:menu:radiobutton[s] menu [options] list
menu - menu to append radiobutton entries to
list - list of {key value variable} or {key value} sublists
-command command (default {})
-variable variable (default VAR, which is not very useful :-)
j:menu:menubutton .font .font.m Font
j:menu:radiobuttons .font.m -variable font \
-command {set_font .t $font} {
{fontTimes times}
{fontPalatino palatino}
{fontGaramond garamond}
-
{fontHelvetica helvetica}
{fontLucida lucida}
{fontOptima optima}
}
j:menu:menubutton .par .par.m Paragraph
j:menu:radiobuttons .par.m {
{left_justify l justify}
{center c justify}
{right_justify r justify}
-
{single-space 1 spacing}
{double-space 2 spacing}
}
This procedure adds one or several radiobutton entries to menu, a menu which should already exist.
For each entry in list, the text, underline position, and accelerator displayed are looked up based on key in the current naturallanguage string database (as implemented in jldb.tcl), and that entry will be associated with the global variable variable. When variable's value is value, the radiobutton will be highlighted. Otherwise it won't. Invoking the radiobutton sets variable to value.
A default global variable to be shared among the entries can be specified with the -command option, as in the first example above, or (possibly) distinct variables can be specified for each entry, as in the second example. If both are specified, the variable in the sublist for a particular entry takes precedence.
If `-command command' is specified (and nonnull), then when any of the menu entries is invoked (after setting the corresponding variable), command will be executed. Note that command must be a complete Tcl command with all its arguments, and need not be a `command procedure' in the sense required for j:menu:commands.
There must be a string translation for each key in list, or the menu will display only the key itself. (The j:ldb:set_defaults procedure aids in ensuring that, or you can just use keys that will make sense to the user.)
The accelerator specified in the naturallanguage database, if any, will be displayed to the right of the menu entry text, but that doesn't automatically create an accelerator binding. In order to support accelerators, you need to do that explicitly for each entry, e.g. by binding to a procedure that sets the global variable.
A single hyphen (`-') can appear anywhere in the cmds list, and will produce a separator line in the corresponding position in the menu.
This procedure can be invoked either as j:menu:radiobuttons or j:menu:radiobutton; the two forms function identically, but j:menu:radiobutton may read more clearly when you're only adding a single entry.
j:menu:docs menu list
menu - menu to append documentation entries to
list - list of {key docfile} sublists
j:menu:docs $mb.help.m {
{{Help on Pottery} {pottery.jdoc}}
{{Help on Etruscan Pottery} {pottery.jdoc#etruscan}}
{{Help on Ming Pottery} {pottery.jdoc#ming}}
-
{{Help on jstools} {jstools.jdoc}}
}
This procedure creates menu entries that allow the user to access documentation with jdoc. It would typically be used to create a `Help' menu. The menu menu must already exist. Each sublist of list consists of a key, which is looked up using j:ldb to find the string to display in the menu entry, and a docfile, which is a document specification as used by jdoc. When the user invokes the menu entry, jdoc will be invoked with docfile as its argument to display the document. A particular location in a document can be specified; for more details, see The jdoc Document Viewer.
* The j:menu:commands procedure isn't as flexible as it could be; it can only handle normal command entries.
* You can't specify -onvalue or -offvalue options to menu entries created by j:menu:checkbuttons.
* Normal use of these procedures will result in multiple calls to the jldb.tcl procedures to look up the same information, which is a minor performance hit.
* There's no mechanism for providing additional configuration options to the menubutton or the menu created by j:menu:menubutton.
* If and when I stop supporting Tk 3.6, j:menu:commands will be able to add automatic accelerator bindings, taking advantage of Tk 4.0's more elaborate binding mechanism.
* When jdoc is embeddable, j:menu:docs will use the embeddable version rather than starting up a second process for each document.