Reference Type: Supported, Category: XGF Function Library, Integration Agreement: 3173
This extrinsic function provides a way to perform READs using escape
processing. READs, when escape processing is turned on, are terminated by:
<UP-ARROW> ("↑"), <DOWN-ARROW> ("↓"), <PREV>
<NEXT> ("→"), <TAB>, and other special
$$READ^XGF is a low-level reader compared to the VA FileMan reader. In some respects it is as simple as using the M READ command. This READ function incorporates escape processing, which puts the burden on the operating system to READ the arrow, function, and all other keys.
A call to INITKB^XGF or PREP^XGF must be made at some point prior to calling $$READ^XGF.
If the number of characters you request with the first parameter is not entered, the READ does not terminate until some terminating character is pressed (or the timeout period is reached).
If you do not pass the timeout parameter, DTIME is used for the timeout period. If the READ times out, caret ("^") is returned and DTOUT is left defined.
The list of mnemonics for keys that can terminate READs is:
|Control||^A, ^B, ^C, ^D, ^E, ^F, ^G, ^H, ^J, ^K, ^L, ^N, ^O, ^P, ^Q, ^R, ^S, ^T, ^U, ^V, ^W, ^X, ^Y, ^Z, ^\, ^], ^6, ^_|
|Cursor||UP, DOWN, RIGHT, LEFT, PREV, NEXT|
|Editing||FIND, INSERT, REMOVE, SELECT|
|Function||F6 to F14, HELP, DO, F17 to F20|
|Keypad||KP0 to KP9, KP-, KP+, KP., KPENTER|
|PF||PF1, PF2, PF3, PF4|
(optional) Maximum number of characters to READ.
(optional) Maximum duration of READ, in seconds.
Returns the string READ from the user.
Set to the mnemonic of the key that terminated the READ.
If defined, signifies that the READ timed out.
To READ a name (with a maximum length of 30) from input and display that name on the screen, do the following:
D INITKB^XGF("*") W "Name: " S NM=$$READ^XGF(30) D SAY^XGF(10,20,"Hello " NM)
To accept only <Up-Arrow> ("↑") or <Down-Arrow> ("↓") keys to exit a routine, do the following:
;Only accept UP or DOWN arrow keys F S %=$$READ^XGF(1) Q:XGRT="UP"!(XGRT="DOWN")
NOTE: When you set up the XGF keyboard environment using INITKB^XGF rather than PREP^XGF, the keypad is not automatically set to application mode. For READs to be terminated by the keypad keys (<KP0> to <KP9>, <KPENTER>, <KP+>, <KP->, and <KP>), the keypad must be in application mode. You can put the keypad in application mode by using an M WRITE statement (W IOKPAM to set application mode, IOKPNM to set numeric mode). Take care to preserve the value of $X when using a direct M WRITE, so that relative positioning in XGF cursor/text output calls is not thrown off:
>S X=$X W IOKPAM S $X=X
August 26, 2011