addmenu

Built-in

SYNOPSIS

addmenu menuPathList relationship active menuName menuModifiers menuFunction

DESCRIPTION

Add a menu to the menu tree. The addmenu command allows you to add custom menus and menu items to e93. In building a menu, you associate a command, tool, or script with a menu item that is placed in a menu. When you choose the new menu item, the command, tool, or script associated with it is executed just as though you had entered and executed the commands in the active window.

If you decide to change the commands associated with a menu item, you can execute addmenu again with the same menu name and item name but with a different string of commands. You can change the command key associated with a menu item in the same manner, this time modifying the item name instead of the commands.

NOTE: Menus and menu items created with this command do not persist beyond the current e93 session unless you place the appropriate addmenu commands in one of your e93 rc files.

INPUT

None

OUTPUT

None

STATUS

The addmenu command will return an error in the following cases:
BADRELATIONSHIP
BADPATH

for Windows only:
BADKEYNAME
BADMODIFIERS

PARAMETERS

menuPathList

Is a Tcl List that specifies where the add should take place.

relationship

Tells how the new item should be linked to the path; this can be any of the following values:
Valid Values Description
NEXTSIBLING link as next sibling of the given path.
PREVIOUSSIBLING link as previous sibling of the given path.
FIRSTCHILD link as the first child of the given path.
LASTCHILD link as the last child of the given path.

active

Specifies if the menu is selectable or grayed and inactive.

menuName

Is the name of the new element to add.

menuModifiers

Is a string that is used to change the menu item:

Valid Values Description
\S makes the item a separator line.
\K[modifiers]keyName assigns keyName for a command a key for the menu item.

The default behavior is to use the keyName specified with the Command key as the modifier.
keyName is case-sensitive.
If the single character key specified is uppercase the modifiers will be Command + Shift.
If keyName is not found, e93 for Windows will report an error.

NOTE: Optionally you may use the same key modifiers used by bindkey. This is an option unique to e93 on Windows.

menuFunction

Is a Tcl script to run when the menu item is selected.

OPTIONS

None

EXAMPLES

The following two command lines create a menu named Info and append the menu item List files to it. This menu item lists the names of each file and directory in the current directory. addmenu {} LASTCHILD 1 {Info} "" "";
addmenu {Info} LASTCHILD 1 "List files" {} {puts [exec ls]};

In the following example, addmenu creates an Extras menu with a TimeStamp item. Choosing the menu item or typing its keyboard equivalent, Command-2, writes the current time and date in the active window. addmenu {} LASTCHILD 1 {Extras} "" "";
addmenu {Extras} LASTCHILD 1 "Timestamp" {\\K2} {puts [exec date]};

Adding the following commands to one of your e93rc files appends new menu items to the Find menu to create the menu shown in Figure 1. addmenu {Find} LASTCHILD 0 {Space1} {\\S} {}
addmenu Find LASTCHILD 1 {Top} {\\Kt} {movecursor [ActiveWindowOrBeep] STARTDOC; HomeWindowToSelectionStart [ActiveWindowOrBeep]}
addmenu Find LASTCHILD 1 {Bottom} {\\Kb} {movecursor [ActiveWindowOrBeep] ENDDOC; HomeWindowToSelectionStart [ActiveWindowOrBeep]}

Figure 1: The Find menu with appended menu items

The first command line creates a new section at the bottom of the menu by inserting a disabled separator "Space0" as a menu item. Each menu, including separators must have a unique name. Although, in the case of separators the name is not displayed. The newly created Top and Bottom menu items appear below the separator and allow the user to position the insertion point at the top and bottom of the target window. Their keyboard equivalents appear to the right of their names.
Notice the use of backslashes in the previous example. The "\K" needed to specify the command key is typed as "\\K", this is because Tcl use the '\' character as it literal character delimiter. To use a '\' character in a Tcl script, which is what all the e93 rc files are, '\' needs to be typed twice.

In the following example, . addmenu {} LASTCHILD 1 "Test" "" ""
addmenu {Test} LASTCHILD 1 "One" {\\KT} {okdialog "testing; one, two..."}
addmenu {Test} LASTCHILD 0 "space0" {\\S} {}
addmenu {Test} LASTCHILD 1 "Two" {} {beep}

When you choose "One" from the Test menu, or type command-shift T, e93 displays an OK dialog box with "testing; one, two..." displayed in it.
When you choose "Two" from the Test menu, e93 makes an annoying beep sound.

LIMITATIONS

Menus and menu items created with this command do not persist beyond the current e93 session unless you place the appropriate addmenu commands in one of your e93 rc files.

SEE ALSO

deletemenu bindkey waitkey