.ENTRY

Define a column entry

.ENTRY name, text[, justification][, DISABLE][, KEY(shortcut)|SUB][, NORESET] –
       [, SELECT(character)][, USER(string)]

Arguments

name

The entry name (a maximum of 10 characters).

text

An alphanumeric or quoted string that contains the text of the column entry.

justification

(optional) Designates how the entry text is aligned within the column: LEFT (default), RIGHT, CENTERED.

DISABLE

(optional) Specifies that when the column is placed on the menu bar, the entry will be disabled.

KEY (shortcut)

(optional) Specifies a shortcut key or sequence.

SUB

(optional) Specifies that a submenu column is associated with the entry.

NORESET

(optional) Keeps the menu from being reset when the entry is selected. (The column and menu stay dropped down.) On Windows, NORESET has no effect.

SELECT (character)

(optional) Specifies a single, printable quick-select character.

USER (string)

(optional) Specifies a user-defined text string to be associated with the entry (a maximum of 80 characters).

Discussion

The .ENTRY command generates a new entry within a primary menu or submenu column. You can define up to 20 menu entries per menu column.

Name is case insensitive. Don’t use names that begin with “U_” unless you want such entries to access the EUTILS_METHOD subroutine. (See Environment Routines for more information.) Also avoid entries that begin with “E_”, “S_”, “T_”, or “I_” (other than the reserved entries); some routines will generate errors if they encounter unrecognized entries of these types. The name O_HELP is reserved for the EHELP_METHOD subroutine. See Appendix B: Reserved Menu Entries for a list of reserved menu entries.

The first character of text is loaded at the second character position within the entry’s display if the entry is left-justified. You can define additional leading or trailing spaces by explicitly including them in the quoted string. If required, the overall width of the column is increased so that at least one trailing blank follows text.

Justification defaults to LEFT if you do not specify RIGHT or CENTERED. If you specify RIGHT, the right side of the column and this entry’s text will be aligned. If you specify CENTERED, this entry will be centered within the column. (See figure 1.) On Windows, you should always use LEFT justification for menu entry text. RIGHT and CENTERED will not operate as expected because Windows uses a proportional font rather than a fixed font for menu column text.

1. Entry justification.

If you specify DISABLE, you can re-enable the entry with the M_ENABLE subroutine later.

NORESET will keep the menu column displayed after a selection has been made. This is useful if you want to do additional processing while the menu is still dropped down. Note, however, that if NORESET is specified, it is the responsibility of the application program to reset the menu with the M_RESET subroutine. If you do not specify NORESET, the menu will be reset to the disabled menu bar after the user makes a selection. Placement or removal of any menu columns will also automatically reset the menu bar.

KEY(shortcut) defines the entry’s shortcut. If shortcut is defined in the key mapping script file (keymap.ctl by default), it must have the form used there. For example, if the key mapping script file has an entry f42=alt_s(“Alt-S”), you can pass only KEY(alt_s) for function 42. If it isn’t defined in the key mapping script file, you can use the following forms for shortcut:

Fnn	where nn is a numeric value from 1 through 63. This form assigns the specified function key as the shortcut for the entry, and can be used only when the keymap.ctl file doesn’t have a corresponding entry. (On Windows, every function from F11 to F63 is already defined in keymap.ctl as distributed.)
^x	where x is an alphabetic value. This form specifies that a control character is the shortcut for the entry (^A for ctrl+a, ^T for ctrl+t, and so forth). ^M is not valid as a shortcut because it is a carriage return. (There are other keys you should avoid using. See Customizing reserved keys.)
LEFT	Specifies the left arrow key as the shortcut for the entry. Can be abbreviated to L.
RIGHT	Specifies the right arrow key as the shortcut for the entry. Can be abbreviated to R.
UP	Specifies the up arrow key as the shortcut for the entry. Can be abbreviated to U.
DOWN	Specifies the down arrow key as the shortcut for the entry. Can be abbreviated to D.

The KEY qualifiers are case insensitive (^e is the same as ^E, f3 is the same as F3, and “left” is the same as “LEFT”). If KEY(shortcut) is not present, no shortcut is assigned.

If you use KEY(shortcut) for an entry in a menu column, the width of the column is a combination of the width of the longest text for a menu shortcut and the width of the longest menu entry in the column.

You can add, change, and delete definitions in keymap.ctl to make KEY(shortcut) definitions more readable. For example, if you want to use the ctrl+p key combination as a shortcut for a menu entry on Windows, you’ll need to pass KEY(alt_p) if you’re using the distributed version of keymap.ctl. (This is because, for historical reasons, the keymap.ctl file includes the definition ^p=alt_p.) If you want to instead pass KEY(^p) to make your code more readable, just delete the ^p=alt_p definition.

If you want to pass an identifier for shortcut that isn’t one of the forms listed above, you can create a definition in keymap.ctl for this identifier. For example, if you want to pass KEY(print) to specify the ctrl+p key combination, just create the definition ^p=print in keymap.ctl. See Modifying shortcut identifiers for menu entries defined in a script for information.

By passing SUB, you can cause the menu entry to display a submenu column. (Note that you must also pass the submenu column’s name as the entry’s name. See the .COLUMN Discussion for more information.) If you specify SUB, the KEY(shortcut) argument is ignored.

If you do not specify SELECT(character), the quick-select character defaults to the first non-blank character of text.

On Windows, quick-select characters are always designated by an underscore (“_”).

Quick-select characters, shortcuts, and disabling/enabling are discussed further in Understanding menus.

USER(string) enables you to specify a user-defined text string. If you pass it, you can

use the M_USER subroutine to retrieve the user string specified by any .ENTRY on a primary menu column.
test the g_entuser field to find out the last .ENTRY the user selected on a primary menu column.

UI Toolkit includes several reserved menu entries that perform scrolling and editing functions (see Appendix B: Reserved Menu Entries). You must specify these entries in your script file (with .ENTRY) to include them on a menu column.