INKEY

INKEY and INKEY$ are BASIC functions to:

• wait a specified time for a character from the input stream
• test for a keypress
• return a value indicating the machine host/operating system type

INKEY

Availability	Present in all versions of BBC BASIC.
Syntax	<numeric> = INKEY<numeric>	<string> = INKEY$<numeric>
Token (hex)	A6 (function)	BF (function)
Description	Reads an character from the input stream.

Description

INKEY and INKEY$ call OSBYTE &81. INKEY returns a character or -1 for no character, INKEY$ returns a one-character string or a null string if nothing returned.

Wait for input character

   Argument: >=0
   Returns:  >=0, character returned
             -1, timed out or Escape key enabled and pressed
   
   Example:  key%=INKEY(200)
             REPEAT:k%=INKEY(10):PROCtick:UNTIL k%>-1
   
   Some systems allow a delay value with b15 set to return a 16-bit "deep"
   keyvalue distinguishing between special keys, such as function keys, and
   top-bit characters.
   
   Example:  REPEAT:key%=INKEY(&80C8):UNTIL key%>-1
             IF key%=&190 THEN PRINT "Shift-f0 pressed"
   
   Some BASICs do not allow this to be called via INKEY as they treat any
   return value with b8-b15 non-zero as a timeout and replace the return
   value with -1.

Note that -1 is returned for a pending Escape state regardless of what actual key is the current Escape key. If an Escape state is pending, BASIC will acknowledge the Escape and generate an "Escape" error at the start of the next statement. In the above examples this would be at the point of passing through the colon after the INKEY call.

Scan for a particular key

   Argument: -1..-128, negative key number
   Returns:  TRUE, key pressed
             FALSE, key not pressed

Scan for a range of keys

   Argument: -129...-255, lowest internal key number to start at EOR&7F
   Returns:  internal key number pressed, or 255 for none

Check machine type

Depending on what the program needs to know, OSBYTE &00 is usually the more appropriate call to make.

   Argument: -256
   Returns:  A value with the low byte indicating the host (I/O) machine type:
            &00 BBC A/B with OS 0.10
            &00 RM Nimus
            &01 Acorn Electron OS
            &FF BBC Micro OS 1.00/1.20/1.23, Reuters OS R0.3 with *UK
            &FE BBC Micro (American OS A1.0), Reuters OS R0.3 with *US
            &FE NetBSD
            &FD Master 128 MOS 3.20/3.50
            &FC BBC Micro (West German MOS) - see note
            &FC Windows 32
            &FB BBC B+ 64/128 (OS 2.00)
            &FB Beos (Brandy Basic)
            &FA Acorn Business Computer OS 1.00/2.00
            &FA Cambridge Workstation OS 2.10
            &FA DOS with DJGPP extender (Brandy Basic)
            &F9 Communicator
            &F9 Linux
            &F8 MacOS X (Brandy Basic)
            &F7 Master ET MOS 4
            &F7 FreeBSD
            &F6 OpenBSD
            &F5 Master Compact MOS 5
            &F5 Amiga (Brandy Basic)
            &F4 Master 128 MOS 3.26
            &F4 GNU FreeBSD (Brandy Basic)
            &F3 GNU (Brandy Basic)
            &Ex Spectrum
                &E0 ZX Spectrum
                (INKEY-256 AND &F0)=&E0 gives TRUE for ZX Spectrum hardware
            &Dx Amstrad 464/664/6128, etc.
                (INKEY-256 AND &F0)=&D0 gives TRUE for Amstrad CPC hardware
            &Cx Commodore 64/64+/128, etc.
                (INKEY-256 AND &F0)=&C0 gives TRUE for Commodore hardware
            &Bx PDP11 Unix
                &B7 PDP11 Unix Version 7
                &B6 PDP11 Unix Version 6
                &B5 PDP11 Unix Version 5
                (INKEY-256 AND &F0)=&B0 gives TRUE for PDP11 hardware
            &Ax ARM-based systems
                &A0 Arthur 1.20
                &A1 RISC OS 2.00
                &A2 RISC OS 2.01
                &A3 RISC OS 3.0x
                &A4 RISC OS 3.1x
                &A5 RISC OS 3.50
                &A6 RISC OS 3.60
                &A7 RISC OS 3.7x
                &A8 RISC OS 4.0x
                &A9 RISC OS 4.3x
                &AA RISC OS 5.xx
                &AE RISC OS Pyromaniac
                &AF Springboard - an ARM-based development system plugged into
                  a PC)
                (INKEY-256 AND &F0)=&A0 gives TRUE for ARM hardware
            &8x Texas Instruments Calculator
                &83 TI-83+(SE)
                &84 TI-84+(SE)
                (INKEY-256 AND &F0)=&80 gives TRUE for TI Calculator
                hardware
            &68 6809 system
            &63 6309 system
            &73 BBC BASIC on SDL abstraction from C source (ie ASC"s")
            &57 BBC BASIC for Windows (ie ASC"W")
            &53 BBC BASIC SDL abstraction from assembly language source
                (ie ASC"S")
                (INKEY-256 AND &DB)=&53 gives TRUE for R.T.Russell's
                BBC BASIC for Windows/SDL/etc
            &50 Sega Master System (ASC"P")
            &4D Matrix Brandy BASIC (ie ASC"M") for all builds from v1.22.6
                except RISC OS.
            &2A Apple IIgs
            &2C Apple IIc
            &2E Apple IIe
  
 The known examples of German BBC MOS return X=&FF.

Extensions

The parameter to INKEY is a 16-bit number. The standard implementation interprets that as:

 <&8000   - wait for keypress
 &FF00+nn - scan for BBC keypress
 &FF00    - return host machine type

A parameter of &8000-&FEFF is undefined. Some systems extend INKEY as follows:

 &FE00+nn - scan for low level DOS/Window VK_xxxx keypress (cZ80Tube,
            console library)
 &FC00+nn - scan for low level SDL1.2 SDK_xxx keypress (Brandy test
            builds)
 &8000+nn - wait for keypress, return 16-bit character code (cZ80Tube,
            console library)

See Also

• http://mdfs.net/Docs/Comp/BBC/Osbyte80
• http://mdfs.net/Docs/Comp/Acorn/HostVals
• http://mdfs.net/Docs/Comp/Acorn/Hosts
• What BASIC is running
• Negative INKEY numbers

References

Jgharston 12:27, 28 May 2009 (UTC) Jgharston (talk) 17:25, 5 July 2018 (CEST)