The
OnChar 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.
The
OnChar 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 and
OnChar functions exist,
OnKey will always be called before
OnChar is called.
The
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.'
The
OnChar function does not return any information about whether any of the Shift, Ctrl, or Alt keys were held down when the character was typed.
The
OnChar 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.