Reads one keystroke from an input source and
sets the value of LASTKEY to the keycode of that keystroke. Use
the READKEY statement when you want to look at each keystroke a
user makes and take some action based on that keystroke.
Note: Does not apply to SpeedScript programming.
Caution:
If you are executing the READKEY statement
while blocking on a .NET main form, a user action can unconditionally
shut down the ABL application. For more information, see the
WAIT-FOR statement (.NET and ABL) reference entry.
Syntax
READKEY [ STREAM stream | STREAM-HANDLE handle ][ PAUSE n ]
|
- STREAM stream
- Specifies the name of a stream. If you do not name a stream,
the AVM uses the unnamed stream. See the DEFINE STREAM statement.
- STREAM-HANDLE handle
- Specifies the handle to a stream. If handle it
is not a valid handle to a stream, the AVM generates a run-time
error. Note that stream handles are not valid for the unnamed streams.
See the chapter on alternate I/O sources in OpenEdge Development:
Programming Interfaces for more information on streams and
stream handles.
- PAUSE n
- The READKEY statement waits up to n seconds
for a keystroke. You can choose a whole or a fractional value for
the time-out interval. If the time-out period you specify is a fractional
value, the value is rounded to the nearest whole millisecond. If
you do not press a key during that amount of time, READKEY ends,
and sets the value in LASTKEY to -1.
PAUSE 0 causes READKEY to
immediately return a value. If no character is available, READKEY
sets the value of LASTKEY to -1. Use this form of READKEY to do
polling through UNIX pipes or terminal ports.
Example
In
the following procedure, when the user presses a key, the READKEY statement
reads the keystroke and stores the character code value of that
key (the key code) as the value of LASTKEY. The CHR function converts
the character code value into a character value. If the character
value is a Y, the AVM deletes the Customer. KEYFUNCTION determines
the function of the LASTKEY. If that function is END-ERROR, the
AVM exits the block, ending the procedure.
r-readky.p
FOR EACH Customer:
DISPLAY Customer.CustNum Customer.Name Customer.Address Customer.City
Customer.State WITH 1 DOWN.
MESSAGE "If you want to delete this customer, press Y".
MESSAGE "Otherwise, press any other key.".
READKEY.
IF CHR(LASTKEY) = "Y" THEN DELETE Customer.
ELSE IF KEYFUNCTION(LASTKEY) = "END-ERROR" THEN LEAVE.
END.
|
Notes
- If
you use READKEY, it intercepts any input from the user. Thus no
widgets receive the input. To pass the input to a widget, you must
use the APPLY statement.
- The READKEY function is double-byte enabled. The READKEY function
returns values only after the input method places the data in the keyboard
buffer. It returns the key code of the most recent key sequence returned
from the keyboard buffer. A key sequence is the set of keystrokes necessary
to generate one character or function key event in ABL.
- If the current input source is a file, then READKEY reads the
next character from that file and returns the value of that character
(1 to 255) to LASTKEY. READKEY does not translate periods (.) in
the file into the ENDKEY value. It does translate end of line into
RETURN (13), but it cannot read any special keys, such as function
keys.
When the AVM reaches the end of the file, it sets the value
of LASTKEY to -2, but does not close the input file. At that point,
an APPLY LASTKEY (same as APPLY -2) raises the ENDKEY condition.
- If the current input source is a UNIX pipe, any timer you set
with the PAUSE option might expire before READKEY can read a character.
If so, LASTKEY is set to -1.
- If the last key typed is an invalid character sequence, READKEY
sets the value of LASTKEY to -1.
- READKEY counts to determine whether an UNDO, RETRY should be
treated as UNDO, NEXT, and whether UNDO, NEXT should be treated
as UNDO, LEAVE . This presents infinite loops.
- For more information on monitoring keystrokes, see OpenEdge Development:
Programming Interfaces.
- In the context of the .NET blocking method, System.Windows.Forms.Application:Run( ),
if you directly or indirectly execute the READKEY statement within
an editing block while displaying a non-modal ABL window, in certain
contexts (such as within a user-defined function or non-VOID method)
this statement execution raises the STOP condition. For more information
on the .NET Application:Run( ),
method, see the reference entry for the WAIT-FOR statement (.NET and ABL). For more information on editing blocks, see
the EDITING phrase entry.
