Difference between revisions of "INKEY"

From BeebWiki
Jump to: navigation, search
m (Added BASIC I/O category.)
 
m (Apple II varients.)
 
(35 intermediate revisions by 4 users not shown)
Line 24: Line 24:
 
==Description==
 
==Description==
 
<code>INKEY</code> and <code>INKEY$</code> call [[OSBYTE &81]].
 
<code>INKEY</code> and <code>INKEY$</code> call [[OSBYTE &81]].
<code>INKEY</code> returns a character or -1 for no character, <code>INKEY$</code>
+
<code>INKEY</code> returns a character or -1 for no character,
returns a one-character string or a null string if nothing returned.
+
<code>INKEY$</code> returns a one-character string or a null string if
 +
nothing returned.
  
 
===Wait for input character===
 
===Wait for input character===
 
     Argument: >=0
 
     Argument: >=0
 
     Returns:  >=0, character returned
 
     Returns:  >=0, character returned
               -1, timed out
+
               -1, timed out or Escape key enabled and pressed
 
+
   
 
     Example:  key%=INKEY(200)
 
     Example:  key%=INKEY(200)
 
               REPEAT:k%=INKEY(10):PROCtick:UNTIL k%>-1
 
               REPEAT:k%=INKEY(10):PROCtick:UNTIL k%>-1
Line 37: Line 38:
 
     Some systems allow a delay value with b15 set to return a 16-bit "deep"
 
     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
 
     keyvalue distinguishing between special keys, such as function keys, and
     top-bit characters.<ref>http://mdfs.net/Docs/Comp/KeyMap/Regular</ref><ref>http://mdfs/net/System/C/Lib/console.txt</ref>
+
     top-bit characters.<ref>http://mdfs.net/Docs/Comp/KeyMap/Regular</ref><ref>http://mdfs.net/System/C/Lib/console.txt</ref>
 
      
 
      
 
     Example:  REPEAT:key%=INKEY(&80C8):UNTIL key%>-1
 
     Example:  REPEAT:key%=INKEY(&80C8):UNTIL key%>-1
 
               IF key%=&190 THEN PRINT "Shift-f0 pressed"
 
               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===
 
===Scan for a particular key===
     Argument: -1..-128, negative key number
+
     Argument: -1..-128, [[Negative INKEY numbers|negative key number]]
 
     Returns:  TRUE, key pressed
 
     Returns:  TRUE, key pressed
 
               FALSE, key not pressed
 
               FALSE, key not pressed
Line 52: Line 63:
  
 
===Check machine type===
 
===Check machine type===
 +
Depending on what the program needs to know, [[OSBYTE &00]] is usually the
 +
more appropriate call to make.
 
     Argument: -256
 
     Argument: -256
     Returns:  A value indicating the host (I/O) machine type:
+
     Returns:  A value with the low byte indicating the host (I/O) machine type:
             &00 BBC B with MOS 0.10
+
             &00 BBC A/B with OS 0.10
 
             &00 RM Nimus<ref>Network User, Jan/Feb 1988, p9</ref>
 
             &00 RM Nimus<ref>Network User, Jan/Feb 1988, p9</ref>
             &01 Acorn Electron MOS
+
             &01 Acorn Electron OS
             &FF BBC Micro OS 1.00/1.20
+
             &FF BBC Micro OS 1.00/1.20/1.23, Reuters OS R0.3 with *UK
             &FE BBC Micro (American MOS 1.10)
+
             &FE BBC Micro (American OS A1.0), Reuters OS R0.3 with *US
 
             &FE NetBSD
 
             &FE NetBSD
             &FD Master 128 MOS 3.20
+
             &FD Master 128 MOS 3.20/3.50
             &FC BBC Micro (West German MOS)
+
             &FC BBC Micro (West German MOS) - see note
 
             &FC Windows 32
 
             &FC Windows 32
             &FB BBC B+ 64/128 (MOS2.00)
+
             &FB BBC B+ 64/128 (OS 2.00)
 
             &FB Beos (Brandy Basic)
 
             &FB Beos (Brandy Basic)
             &FA Acorn ABC
+
             &FA Acorn Business Computer OS 1.00/2.00
             &FA DOS with Brandy BASIC
+
            &FA Cambridge Workstation OS 2.10
 +
             &FA DOS with DJGPP extender (Brandy Basic)
 +
            &F9 Communicator
 
             &F9 Linux
 
             &F9 Linux
 
             &F8 MacOS X (Brandy Basic)
 
             &F8 MacOS X (Brandy Basic)
             &F7 Master ET OS 4.00
+
             &F7 Master ET MOS 4
 
             &F7 FreeBSD
 
             &F7 FreeBSD
 
             &F6 OpenBSD
 
             &F6 OpenBSD
             &F5 Compact
+
             &F5 Master Compact MOS 5
 
             &F5 Amiga (Brandy Basic)
 
             &F5 Amiga (Brandy Basic)
 
             &F4 Master 128 MOS 3.26
 
             &F4 Master 128 MOS 3.26
 +
            &F4 GNU FreeBSD (Brandy Basic)
 +
            &F3 GNU (Brandy Basic)
 
             &Ex Spectrum
 
             &Ex Spectrum
 +
                &E0 ZX Spectrum
 +
                (INKEY-256 AND &F0)=&E0 gives TRUE for ZX Spectrum hardware
 
             &Dx Amstrad 464/664/6128, etc.
 
             &Dx Amstrad 464/664/6128, etc.
             &Ax Arthur/RISC OS
+
                (INKEY-256 AND &F0)=&D0 gives TRUE for Amstrad CPC hardware
             &A0 Arthur 1.20
+
             &Cx Commodore 64/64+/128, etc.
            &A1 RISC OS 2.00
+
                (INKEY-256 AND &F0)=&C0 gives TRUE for Commodore hardware
            &A2 RISC OS 2.01
+
            &Bx PDP11 Unix
            &A3 RISC OS 3.0x
+
                &B7 PDP11 Unix Version 7
            &A4 RISC OS 3.1x
+
                &B6 PDP11 Unix Version 6
            &A5 RISC OS 3.50
+
                &B5 PDP11 Unix Version 5
            &A6 RISC OS 3.60
+
                (INKEY-256 AND &F0)=&B0 gives TRUE for PDP11 hardware
            &A7 RISC OS 3.7x
+
             &Ax ARM-based systems
            &A8 RISC OS 4.0x
+
                &A0 Arthur 1.20
            &A9 RISC OS 4.3x
+
                &A1 RISC OS 2.00
            &AA RISC OS 5.xx
+
                &A2 RISC OS 2.01
            &AF Springboard
+
                &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
 
                 (INKEY-256 AND &F0)=&A0 gives TRUE for ARM hardware
             &57 BBC BASIC for Windows
+
            &8x Texas Instruments Calculator
   
+
                &83 TI-83+(SE)
    Depending on what the program needs to know, [[OSBYTE &00] may also need
+
                &84 TI-84+(SE)
    to be called.
+
                (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==
 
==See Also==
Line 102: Line 162:
 
* [[What BASIC is running]]
 
* [[What BASIC is running]]
 
* Negative INKEY numbers
 
* Negative INKEY numbers
 
  
 
==References==
 
==References==
Line 108: Line 167:
  
 
[[User:Jgharston|Jgharston]] 12:27, 28 May 2009 (UTC)
 
[[User:Jgharston|Jgharston]] 12:27, 28 May 2009 (UTC)
 +
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 17:25, 5 July 2018 (CEST)

Latest revision as of 15:52, 10 September 2021

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.[1][2]
   
   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[3]
            &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

References

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