The OnKey global function allows you to trap keystrokes in order to perform special actions or to change the action of the key. It also can be used to disable or remap keys. This function must be placed in the Global procedure.

If an OnKey global function is coded, every keystroke the operator types is sent to the OnKey function for processing. If the OnKey function returns a value, then the return value is processed by the field as the keystroke. If a statement in the OnKey function causes movement to another field within the case, then the movement is executed. If no OnKey function is coded, then keystrokes are unmodified.

The key value is a number code identifying what key was pressed on the keyboard. Its value can be used within the function. See detailed description below.

You can use the OnKey Character Map to determine the value of characters.

Calls to this function are ignored when executed on mobile devices.

The OnKey function must return a number. The value should be either the value of the key pressed (the same as the value passed to the function), a substituted key value (remapping the key), or zero (0) to indicate that the key is to be ignored.

A summary of key values passed into and out of the OnKey function are given below. If in doubt, use the OnKey Character Map to determine the value of characters. It can be accessed from CSPro's View menu option.

For the number keys across the top of the keyboard or on the numeric keypad when the "NumLock" button is depressed, the value 48 should be added to the number. For example, the keyboard key value returned for the range 0-9 is 48-57 respectively.

For the 26 a-z letters the code range 65-90 will be returned. If uppercase letters are sought, then you must add the Shift key value (1000) to the 65-90 range, yielding 1065-1090. If the Ctrl and/or Alt keys are being held down that will impact the value returned too; however, the CapsLock key does not impact the code returned.

If the control keys Shift, Ctrl, or Alt are pressed in isolation, i.e., are not combined with any other keystroke, they will have the following key values:

If the control keys Shift, Ctrl, and/or Alt are pressed in combination with another key, the following base values should be added to the code of the other key.

For example, if Shift, Ctrl, and/or Alt are held down when 'a' is pressed, it causes the following codes:

The 12 function keys F1-F12 return the key value 112-123.

See also: CSPro Program Structure, User-Defined Functions, OnKey Character Map