M_RPLENT

Replace menu entry names with their shortcuts

xcall M_RPLENT(string, [length][, not_found])

Arguments

string

The field to be modified. (a)

length

(optional) Returned with the trimmed length. (n)

not_found

(optional) Returned with the number of menu entries that weren’t found. (n)

Discussion

M_RPLENT scans a string for menu entry names to be replaced by their corresponding shortcut key text.

This subroutine searches for entry names enclosed in square brackets ([ ]) within the string and replaces the brackets and entry name with the shortcut text currently assigned to that entry name. If any entry name is not found, it is replaced by a single space. The text that follows the entry name may shift due to the differing lengths of the entry name and its shortcut text.

You can escape the leading bracket with a back slash (\). Any leading bracket that is preceded by a “\” will not be considered as delimiting a menu entry name, and the string “\[” will be replaced by “[”. If there is no ending bracket for a beginning bracket, all further replacement ceases. A set of brackets ([ ]) with no entry name is treated as an entry not found.

When not_found is passed, it is returned with a value of 0 if all menu entries are found and they all have shortcut text. Otherwise, not_found is returned with the number of menu entries that were either not on a placed column or had no associated shortcut text.

This subroutine is especially useful for creating messages and information lines that contain the names of keys to be pressed. Since different keys may be mapped with runtime terminal binding to the same function for different users or terminal types, you can use this subroutine to insert the correct key name at runtime. (See Customizing key mapping for menu shortcuts for information about runtime terminal binding.)

Examples

This example scans all currently placed columns for the entry name “O_HELP.” If found, and a shortcut key has been assigned to the entry, “[O_HELP]” in the string is replaced by the shortcut text and nohelp is returned with a value of zero. If the entry is not found or does not have a shortcut, “[O_HELP]” is replaced by a single space and nohelp is returned with a value of 1. For example, if the F1 key is assigned to the entry “O_HELP,” the resulting contents of infoline would be “Press F1 for Help.”

infoline = "Press [O_HELP] for Help"
xcall m_rplent(infoline,, nohelp)