The [[INKEY$]] function returns user input as [[ASCII]] [[STRING]] character(s) from the keyboard buffer.


{{PageSyntax}}
: {{Parameter|keypress$}} = [[INKEY$]]


{{PageDescription}}
* Returns [[ASCII]] character string values in upper or lower cases. See: [[UCASE$]] and [[LCASE$]]
* Returns "" if no key has been pressed since the last keyboard read.
* Some control keys cannot be read by INKEY$ or will return 2 byte [[ASCII]] codes.
* INKEY$ can also be used to clear a [[SLEEP]] key press or the keyboard buffer in a loop.
* Assign the INKEY$ return to a string variable to save the key entry.
* &lt;span style="font-family: Courier New, monospace, Courier; background: #dddddd">[[LOCATE]] , , 1&lt;/span> displays the INKEY$ cursor. Use &lt;span style="font-family: Courier New, monospace, Courier; background: #dddddd">LOCATE , , 0&lt;/span> to turn it off.
* To receive input from a [[$CONSOLE]] window, use [[_CINP]].
* Returns can be evaluated as certain [[ASCII]] characters or codes.
{{WhiteStart}}'                                '''ASCII Keyboard Codes'''
'
'''' Esc  F1  F2  F3  F4  F5  F6  F7  F8  F9  F10  F11  F12  Sys ScL Pause'''                  
'  27 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68  +133 +134   -   -    -
'''' `~  1!  2@  3#  4$  5%  6^  7&amp;  8*  9(  0) -_ =+ BkSp   Ins Hme PUp   NumL  /   *    -''' 
' 126 33  64  35  36  37  94  38  42  40  41 95 43   8    +82 +71 +73    -    47  42   45
'''  96 49  50  51  52  53  54  55  56  57  48 45 61''
'''' Tab Q   W   E   R   T   Y   U   I   O   P  [{  ]}  \|   Del End PDn   7Hme 8/▲  9PU  + '''
'  9  81  87  69  82  84  89  85  73  79  80 123 125 124  +83 +79 +81   +71  +72  +73  43
'''    113 119 101 114 116 121 117 105 111 112  91  93  92                 55   56   57 ''
'''' CapL  A   S   D   F   G   H   J   K   L   ;:  '" Enter                4/◄-  5   6/-►  
'   -   65  83  68  70  71  72  74  75  76  58  34  13                  +75  +76  +77  '''E'''
'''       97 115 100 102 103 104 106 107 108  59  39                       52   53   54 '' '''n'''                                    
'''' Shift  Z   X   C   V   B   N   M   ,&lt;  .>  /?    Shift       ▲        1End 2/▼  3PD  t'''
'   *    90  88  67  86  66  78  77  60  62  63      *        +72       +79  +80  +81  '''e'''
'''       122 120  99 118  98 110 109  44  46  47                          49   50   51 '' '''r'''
'''' Ctrl Win Alt       Spacebar          Alt Win Menu Ctrl   ◄-  ▼   -►   0Ins     .Del '''
'  *    -   *           32              *   -   -    *    +75 +80 +77   +82       +83  13 
'                                                                   ''     48        46''
'
' '''    ''Italics'' = LCase/NumLock On  * = 2 byte combo only,  + = 2 Byte: CHR$(0) + CHR$(code)'''
'
{{WhiteEnd}}

==Two Byte Combinations==
* INKEY$ 2 byte combinations always begin with [[CHR$]](0). [[ASC]] will always read the first byte code as zero. 
* Read the second byte code using: '''{{text|code2 &lt;nowiki>=&lt;/nowiki> ASC(press$, 2)|green}}'''


&lt;center>'''[[ASCII#Two_Byte_Codes|Two Byte Ctrl, Alt and Shift + Function key combinations]]'''&lt;/center>

{{WhiteStart}}                    '''Two Byte Characters        Key                 CHR$(0) + "?" '''

                    CHR$(0) + CHR$(16-50)      [Alt] + letter       
                    CHR$(0) + CHR$(59)         [F1]                 ";"
                    CHR$(0) + CHR$(60)         [F2]                 "&lt;"
                    CHR$(0) + CHR$(61)         [F3]                 "="
                    CHR$(0) + CHR$(62)         [F4]                 ">"
                    CHR$(0) + CHR$(63)         [F5]                 "?"
                    CHR$(0) + CHR$(64)         [F6]                 "@"
                    CHR$(0) + CHR$(65)         [F7]                 "A"
                    CHR$(0) + CHR$(66)         [F8]                 "B"
                    CHR$(0) + CHR$(67)         [F9]                 "C"
                    CHR$(0) + CHR$(68)         [F10]                "D"
                    CHR$(0) + CHR$(71)         [Home]               "G"
                    CHR$(0) + CHR$(72)         [↑] Arrow            "H"
                    CHR$(0) + CHR$(73)         [Page Up]            "I"
                    CHR$(0) + CHR$(75)         [←] Arrow            "K"
                    CHR$(0) + CHR$(76)         [5 NumberPad]        "L" (NumLock off in QB64)
                    CHR$(0) + CHR$(77)         [→] Arrow            "M"
                    CHR$(0) + CHR$(79)         [End]                "O"
                    CHR$(0) + CHR$(80)         [↓] Arrow            "P"
                    CHR$(0) + CHR$(81)         [Page Down]          "Q"
                    CHR$(0) + CHR$(82)         [Insert]             "R"
                    CHR$(0) + CHR$(83)         [Delete]             "S"
                    CHR$(0) + CHR$(84-93)      [Shift] + F1-10
                    CHR$(0) + CHR$(94-103)     [Ctrl] + F1-10
                    CHR$(0) + CHR$(104-113)    [Alt] + F1-10
                    CHR$(0) + CHR$(114-119)    [Ctrl] + keypad 
                    CHR$(0) + CHR$(120-129)    [Alt] + number
                    CHR$(0) + CHR$(130 or 131) [Alt] + _/- or +/=   "é" or "â"
                    CHR$(0) + CHR$(133)        [F11]                "à"
                    CHR$(0) + CHR$(134)        [F12]                "å"
                    CHR$(0) + CHR$(135)        [Shift] + [F11]      "ç"
                    CHR$(0) + CHR$(136)        [Shift] + [F12]      "ê"
                    CHR$(0) + CHR$(137)        [Ctrl] + [F11]       "ë"
                    CHR$(0) + CHR$(138)        [Ctrl] + [F12]       "è"
                    CHR$(0) + CHR$(139)        [Alt] + [F11]        "ï"
                    CHR$(0) + CHR$(140)        [Alt] + [F12]        "î"
{{WhiteEnd}}
:In '''QB64''', [[CVI]] can be used to get the [[_KEYDOWN]] 2-byte code value. Example: '''{{text|status &lt;nowiki>=&lt;/nowiki> _KEYDOWN(CVI(CHR$(0) + "P"))|green}}'''


{{PageExamples}}
''Example 1:'' Clearing the keyboard buffer after [[SLEEP]] delays for later [[INPUT]].
{{CodeStart}}{{Cl|PRINT}} "Press any keyboard typing key to end SLEEP"
{{Cl|SLEEP}}
{{Cl|DO}}: K$ = {{Cl|INKEY$}}: {{Cl|PRINT}} K$: {{Cl|LOOP}} {{Cl|UNTIL}} K$ = "" '' ''
{{CodeEnd}}
:''Explanation:'' [[SLEEP]] key presses will be kept in the keyboard buffer and may be added into an [[INPUT]] later.
:See also: [[_KEYCLEAR]]


''Example 2:'' Entering a Ctrl + letter keypress combination will print [[ASCII]] Control characters 1 to 26. .
{{CodeStart}}DO
    K$ = {{Cl|INKEY$}}
    {{Cl|IF...THEN|IF}} K$ &lt;> "" {{Cl|THEN}} {{Cl|PRINT}} K$; " ";
{{Cl|LOOP}} {{Cl|UNTIL}} K$ = {{Cl|CHR$}}(27) 'Esc key exit '' ''
{{CodeEnd}}
: ''Note:'' The above code will print Esc arrow, Backspace symbol, and 2 byte characters led by CHR$(0) in addition to normal keys.  


''Example 3:'' Use [[UCASE$]](INKEY$) in a keyboard read loop looking for uppercase "Y" or "N" user inputs to avoid multiple IF statements.
{{CodeStart}} '' ''
{{Cl|DO...LOOP|DO}}
  {{Cl|PRINT}} "Do you want to continue? (Y/N): ";  'semicolon saves position for user entry
  {{Cl|DO...LOOP|DO}}: K$ = {{Cl|UCASE$}}({{Cl|INKEY$}}) 'change any user key press to uppercase
  {{Cl|LOOP}} {{Cl|UNTIL}} K$ = "Y" {{Cl|OR (boolean)|OR}} K$ = "N"
  {{Cl|PRINT}} K$  'print valid user entry
  {{Cl|IF...THEN|IF}} K$ = "N" {{Cl|THEN}} {{Cl|END}}
{{Cl|LOOP}}  '' ''
{{CodeEnd}}


''Example 4:'' Getting just number values entered by a user in an INKEY$ input loop.
{{CodeStart}} '' ''
{{Cl|LOCATE}} 10, 10: {{Cl|PRINT}} "Enter a number value: ";
{{Cl|DO}}: {{Cl|SLEEP}}
  K$ = {{Cl|INKEY$}}
  {{Cl|IF}} K$ >= {{Cl|CHR$}}(48) {{Cl|AND (boolean)|AND}} K$ &lt;= {{Cl|CHR$}}(57) {{Cl|THEN}} entry$ = entry$ + K$ ' numbers only
  L = {{Cl|LEN}}(entry$) ' check entry length for possible backspace
  {{Cl|IF}} K$ = {{Cl|CHR$}}(46) {{Cl|AND (boolean)|AND}} flag = 0 {{Cl|THEN}} entry$ = entry$ + K$: flag = 1: mark = L ' decimal point
  {{Cl|IF}} K$ = {{Cl|CHR$}}(8) {{Cl|AND (boolean)|AND}} L > 0 {{Cl|THEN}} ' backspace pressed and entry has a length
    entry$ = {{Cl|MID$}}(entry$, 1, L - 1) ' remove one character from entry$
    {{Cl|IF}} {{Cl|LEN}}(entry$) &lt; mark {{Cl|THEN}} flag = 0 ' allow decimal point entry if other was removed.
    {{Cl|LOCATE}} {{Cl|CSRLIN}}, {{Cl|POS}}(0) - 1: {{Cl|PRINT}} {{Cl|SPACE$}}(1); ' remove end character from screen
  {{Cl|END IF}}
  {{Cl|LOCATE}} 10, 32: {{Cl|PRINT}} entry$; ' display entry to user (semicolon required for correct {{Cl|POS}})
{{Cl|LOOP}} {{Cl|UNTIL}} K$ = {{Cl|CHR$}}(13) {{Cl|AND (boolean)|AND}} L > 0 'assures something is entered '' ''
{{CodeEnd}}

: ''Explanation:'' [[SLEEP]] waits for a keypress. It also allows background programs to share the processor and it leaves the keypress in the buffer for INKEY$. Keyboard string number characters range from [[ASCII]] codes 48 to 57. Any other entry is ignored by the IF statement. A decimal point (code 46) entry is allowed once in the input. The flag value stops further decimal point additions. Backspacing (code 8) is also allowed if the entry has at least one character. The cursor column returned by [[POS]](0) reverts too after the end of the entry when printed each loop. The loop exits when [Enter] (code 13) is pressed and the entry has a length.


''Example 5:'' Using arrow keys to move a text character. A change from a previous position tells program when to PRINT:
{{CodeStart}}movey = 1: movex = 1 'text coordinates can never be 0
at$ = "@"  'text sprite could be almost any ASCII character
{{Cl|LOCATE}} movey, movex: {{Cl|PRINT}} at$;
DO
    px = movex: py = movey 'previous positions
    B$ = {{Cl|INKEY$}}
    {{Cl|IF...THEN|IF}} B$ = {{Cl|CHR$}}(0) + {{Cl|CHR$}}(72) {{Cl|AND (boolean)|AND}} movey > 1 {{Cl|THEN}} movey = movey - 1 'rows 1 to 23 only
    {{Cl|IF...THEN|IF}} B$ = {{Cl|CHR$}}(0) + {{Cl|CHR$}}(80) {{Cl|AND (boolean)|AND}} movey &lt; 23 {{Cl|THEN}} movey = movey + 1
    {{Cl|IF...THEN|IF}} B$ = {{Cl|CHR$}}(0) + {{Cl|CHR$}}(75) {{Cl|AND (boolean)|AND}} movex > 1 {{Cl|THEN}} movex = movex - 1 'columns 1 to 80 only
    {{Cl|IF...THEN|IF}} B$ = {{Cl|CHR$}}(0) + {{Cl|CHR$}}(77) {{Cl|AND (boolean)|AND}} movex &lt; 80 {{Cl|THEN}} movex = movex + 1 
    
    {{Cl|IF...THEN|IF}} px &lt;> movex {{Cl|OR (boolean)|OR}} py &lt;> movey {{Cl|THEN}} 'only changes when needed
        {{Cl|LOCATE}} py, px: {{Cl|PRINT}} {{Cl|SPACE$}}(1); 'erase old sprite
        {{Cl|LOCATE}} movey, movex: {{Cl|PRINT}} at$; 'show new position
    {{Cl|END IF}}
{{Cl|LOOP}} {{Cl|UNTIL}} B$ = {{Cl|CHR$}}(27) 'ESCape key exit
{{Cl|END}}
{{CodeEnd}}


''Example 6:'' Using INKEY$ with the arrow or WASD keys to move the QB64 bee image sprite with [[_PUTIMAGE]]:
{{CodeStart}} '' ''
{{Cl|DIM}} image {{Cl|AS}} {{Cl|LONG}}
{{Cl|DIM}} x {{Cl|AS}} {{Cl|INTEGER}}
{{Cl|DIM}} y {{Cl|AS}} {{Cl|INTEGER}}
{{Cl|DIM}} Keypress {{Cl|AS}} {{Cl|STRING}}

{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 32)

x = 0
y = 0
image = {{Cl|_LOADIMAGE}}("QB64bee.png") 'Here I actually used the QB64 icon

DO
  {{Cl|_PUTIMAGE}} (x, y), image
  DO
    Keypress = {{Cl|UCASE$}}({{Cl|INKEY$}})
    ' ***** The following line detects the arrow keys *****
    {{Cl|IF...THEN|IF}} {{Cl|LEN}}(Keypress) > 1 {{Cl|THEN}} Keypress = {{Cl|RIGHT$}}(Keypress, 1)
  {{Cl|LOOP}} {{Cl|UNTIL}} Keypress > ""

  {{Cl|CLS}} ' blank screen after valid key press to avoid smearing image on page

  {{Cl|SELECT CASE}} Keypress
    {{Cl|CASE}} "W", "H": y = y - 10 'Up
    {{Cl|CASE}} "A", "K": x = x - 10 'Left
    {{Cl|CASE}} "S", "P": y = y + 10 'Down
    {{Cl|CASE}} "D", "M": x = x + 10 'Right
    {{Cl|CASE}} "Q", {{Cl|CHR$}}(27): {{Cl|END}} 'Q or Esc Ends prog.
  {{Cl|END SELECT}}
  {{Cl|_PUTIMAGE}} (x, y), image 
{{Cl|LOOP}} '' ''
{{CodeEnd}} {{small|Adapted from code by Daniel}}
: ''Note:'' The image can be placed off of the screen without error. The image moves 10 pixels to move faster. [[CLS]] eliminates any background.


''Example 7:'' Creating upper [[ASCII]] characters in a QB program using '''Alt +''' three number keys:
{{CodeStart}}
DO
    A$ = "": {{Cl|WHILE}} A$ = "": A$ = {{Cl|INKEY$}}: {{Cl|WEND}}
    {{Cl|IF...THEN|IF}} {{Cl|LEN}}(A$) = 2 {{Cl|THEN}} '2 byte INKEY$ return
        B$ = {{Cl|RIGHT$}}(A$, 1)  'read second byte
        b% = {{Cl|ASC}}(B$)        'read second byte code 
        {{Cl|IF...THEN|IF}} b% > 119 {{Cl|AND (boolean)|AND}} b% &lt; 130 {{Cl|THEN}} ' Alt + number codes only
           C% = b% - 119  ' convert to actual number
           {{Cl|IF...THEN|IF}} C% > 9 {{Cl|THEN}} C% = 0
           num$ = num$ + {{Cl|LTRIM$}}({{Cl|STR$}}(C%))
        {{Cl|END IF}}
    {{Cl|END IF}}
{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|LEN}}(num$) = 3  ' 3 digit codes only

{{Cl|PRINT}} num$
{{Cl|PRINT}} {{Cl|CHR$}}({{Cl|VAL}}(num$)'' ''
{{CodeEnd}}{{small|Code by Ted Weissgerber}}
{{OutputStart}} 155 ¢ {{OutputEnd}}
:''Explanation:'' Hold down Alt key and press 3 keyboard code number keys. '''Number pad keys may not work.''' Note that [[INKEY$]] cannot read Alt, Ctrl or Shift key presses without a key combination and the return is CHR$(0) + CHR$(code). 




''See also:'' 
* [[_KEYHIT]], [[_KEYDOWN]], [[_MAPUNICODE]]
* [[_KEYCLEAR]]
* [[INPUT]], [[LINE INPUT]]
* [[INPUT$]], [[INP]] 
* [[CHR$]], [[ASCII]]
* [[ASC]], [[Scancodes]] (keyboard)
* [[Windows_Libraries#Hot_Keys_.28maximize.29|Windows hot keys]]


{{PageNavigation}}
<
