(MBF_KBD) Although you might find it convenient in menus to set your button or other control cmd strings to mimic what might otherwise be keypunched by the operator to make a menu selection, care must be taken to prevent the user from sending such "ordinary text" commands in the wrong context. The best way to avoid that problem is to define your keyboard cmd strings to send pseudo function key sequences. These will automatically be converted by INFLD (and other routines which wait for events, such as BTNMNU.SBR and AUI AUI_EVENTWAIT) into exitcodes, and can be processed relatively easily by other character-level input routines.
There are several formats for defining pseudo-function key sequences:
chr(7) + chr(n)
or
chr(7) + chr(250) + "####."
or
"VK_xF####"
or
"VK_xrF####"
The first format is limited to values of (n) from 1 (for F1) to 249. The last three provide a nearly unlimited range of pseudo-function key numbers and are therefore preferable. (The #### shown can actually be any number of digits. In the second format it must be terminated with a period, but not in the symbolic formats which start with "VK_".) So you can theoretically assign a different pseudo function key to every single control in an entire application, or at the very least to every control in a program. Note that in either case, if converted by INFLD or a similar routine into an exitcode, the exitcode will be the negative of the pseudo-function key number. So in the first case, the range is from –1 to –249, while in the others it is from –1 to –9999999. See Event-driven Programming for more details on how to use this form of keyboard command string to allow a program to respond to a user clicking randomly on controls. Also see the highlighted note below.
The last format example above is equivalent to the third one, except that the presence of the "r" indicates that a right click on the field is also allowed, and if so, the exitcode value will be positive rather than negative. So, for example "VK_xrF421" will generate exitcode -421 for a left click, and +421 for a right click.
The symbolic notation is preferable to the chr(x)... notation, both for readability, and because in the ATE environment, certain control characters may have trouble passing through the data stream to the client without being filtered.
Besides the pseudo-function key sequences, there are also symbolic equivalents for most standard control character sequences. For example, a Ctrl+X can be represented by "^X" rather than chr(24). An escape character can be represented by "VK_ESC" instead of chr(27). See Virtual Key Symbolic Names for a table of all the symbolic control key definitions, and also for information on how to combine multiple control codes into a single command string.
When assigning pseudo-function key sequences to controls, avoid using exitcodes in the range of -100 to +100. Many of these are used for internal navigation and other event codes by routines such as INFLD, EVENTWAIT, XTREE and XTEXT. Exitcodes -1 thru -32 are possible exceptions. They are not used by A-Shell, but have been typically used in the past to represent function keys F1 thru Shift+F16. If you want to equate, say, a button to F5, then it might be appropriate to set cmd string to VK_xF5. The downside is that some users may have expectations for function key actions that don't match yours, which could cause them confusion. For example, some people expect F1 to bring up help, so defining a button which says "Cancel" with cmd = "VK_xF1" might not be the best idea.