QB64-PE/internal/help/_KEYCLEAR.txt

Briefly: Clear keyboard input buffers.

{{PageSyntax}}_KEYCLEAR [buffer&]

Buffer& indicates the buffer to be cleared:
* 1 - Clear the regular keyboard buffer, as used by all input command except the following:  _KEYHIT, _KEYDOWN, INP(&H60.  This is the same as the the emulated BIOS keyboard buffer, so legacy code reading from it via PEEK/POKE/CALL ABSOLUTE will also be affected.
* 2 - Clear the buffer used by _KEYHIT.
* 3 - Clear INP(&H60) buffer (but see the "Warning" section below).
* No parameter - Clear all three buffers.


Description:
{{DISPLAYTITLE:_KEYCLEAR}}

The '''_KEYCLEAR''' command clears the specified keyboard input buffer. In effect,
it is as if a loop has been used to read from the buffer until it is empty.
All keys cleared are lost. 

This command is best used just before getting input, in order to clear stray 
keypresses from commands such as SLEEP, or just random keyboard bashing by the
user. The programmer also aught to be weary of key release events in the 
_KEYHIT buffer; consider the following code:

{{CodeStart}}
INPUT "Name: ", name$
_KEYCLEAR
_DELAY 2 'Simulate doing some processing that takes some time.
PRINT _KEYHIT
{{CodeEnd}}

The INPUT statement finishes as soon as the Enter key is struck; the program then
proceeds to clear all input buffers. Because this is executed so quickly, it is
likely that the user will release the Enter key after the _KEYCLEAR command is 
executed, leaving a -13 (Enter key release) event in the _KEYHIT buffer.

As mentioned above, it is best to place the _KEYCLEAR after the processing, 
immediately before the PRINT _KEYHIT command:

{{CodeStart}}
INPUT "Name: ", name$
_DELAY 2 'Simulate doing some processing that takes some time.
_KEYCLEAR
PRINT _KEYHIT
{{CodeEnd}}


Example:
{{CodeStart}}
PRINT "Press a key"
SLEEP 'Wait for keypress
'Three alternative _KEYCLEAR calls. Try uncommenting different ones to see the effect.
'_KEYCLEAR
'_KEYCLEAR 1
'_KEYCLEAR 2
PRINT "In regular buffer, there is "; INKEY$ 'read regular buffer
PRINT "In _KEYHIT buffer, there is "; _KEYHIT 'read the _KEYHIT buffer
{{CodeEnd}}

Warning:
The buffer read by INP(&H60) does not behave as the other buffers do. Whilst reading from
the others will eventually empty after reading all data, this buffer will continue to return
the last value. For this reason, _KEYCLEAR is of little effect, but is included for completeness
(an internal flag indicating new data on the port is cleared). However, using INP for anything
is strongly discouraged, and is for backwards compatibility only.