jmenu.tcl

Introduction

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.1/4.4.

Usage

Accessing the Library


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.

Credits and Copyright

Author

Jay Sekora
js@aq.org
http://www.aq.org/~js/

Copyright

The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview

Procedures

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

Usage

j:menu:menubutton mb menu key

Arguments

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

Examples

(See j:menu:commands for examples.)

Description

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 natural­language database, and the underline position (if any) in that string will also be taken from the database.

j:menu:commands
j:menu:command

Usage

j:menu:commands menu w cmds
or
j:menu:command menu w cmds

Arguments

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

Examples

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.

Description

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 natural­language 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 natural­language 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:checkbuttons
j:menu:checkbutton

Usage

j:menu:checkbutton[s] menu [options] list

Arguments

menu - menu to append checkbutton entries to
list - list of {key variable} pairs

Option

-command command (default {})

Example

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)}
}

Description

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 natural­language 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 non­null), 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 natural­language 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:radiobuttons
j:menu:radiobutton

Usage

j:menu:radiobutton[s] menu [options] list

Arguments

menu - menu to append radiobutton entries to
list - list of {key value variable} or {key value} sublists

Options

-command command (default {})
-variable variable (default VAR, which is not very useful :-)

Examples

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}
}

Description

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 natural­language 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 non­null), 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 natural­language 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

Usage

j:menu:docs menu list

Arguments

menu - menu to append documentation entries to
list - list of {key docfile} sublists

Example

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}}
}

Description

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.

Bugs and Limitations

* 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.

Future Directions

* 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.