# 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 naturallanguage 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 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: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 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: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 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

### 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.
`
`