global function allows you to trap characters in order to perform special actions or to change the action of the character. It can also be used to disable or remap characters. This function must be placed in PROC GLOBAL
If an OnChar
function is defined, every character the operator types is sent to the function for processing. If the function returns a value, then the return value is processed by the field as the character. If a statement in the function causes movement to another field within the case, then the movement is executed. If no function is defined, then characters are unmodified.
The parameter key_value is a numeric code identifying what character was typed using the keyboard. Its value can be used within the function.
Calls to this function are ignored when executed on mobile devices.
function differs from the OnKey
function. A keystroke contains information about the key pressed on the keyboard, regardless of what this keystroke eventually maps to. A character refers to the final representation of one or more keystrokes. This is important when using non-Latin languages that require multiple keystrokes to create one character. For example, creating the Chinese character '马' using a Pinyin input system requires two keystrokes: 'm' and 'a.' The code for this character is 39532. If typing such a keystroke, OnKey
will be called several times before OnChar
is called. If both OnKey
functions exist, OnKey
will always be called before OnChar
function also returns values different from the OnKey
function for some Latin keystrokes. For example, with Caps Lock off, if a keyer holds down Shift and types 'M,' OnKey
will return 1077 (1000 for the shift, 77 for 'm'). OnChar
, on the other hand, will return 77, the character code for 'M.' For a lowercase 'm,' OnKey
returns 77 and OnChar
returns 109, the character code for 'm.'
function does not return any information about whether any of the Shift, Ctrl, or Alt keys were held down when the character was typed.
function must return an integer value. The value should be either the value of the character pressed (the same as the value passed to the function), a substituted character value (remapping the character), or zero (0) to indicate that the character is to be ignored.