Difference between revisions of "INKEY"

From BeebWiki
Jump to: navigation, search
m (Removed strikeout from &4D (for the rationale see https://stardot.org.uk/forums/viewtopic.php?f=63&p=271601#p270640))
(→‎Check machine type: ref)
 
(10 intermediate revisions by 2 users not shown)
Line 31: Line 31:
 
     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)
Line 42: Line 42:
 
     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 53: 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 with the low byte indicating the host (I/O) machine type:
 
     Returns:  A value with the low byte indicating the host (I/O) machine type:
Line 58: Line 70:
 
             &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 OS
 
             &01 Acorn Electron OS
−
             &FF BBC Micro OS 1.00/1.20/1.23 (full value returned is -1)
+
             &FF BBC Micro OS 1.00/1.20/1.23, Reuters OS R0.3 with *UK
−
            &FF Reuters OS R0.3 with *UK (full value returned is -1)
 
 
             &FE BBC Micro (American OS A1.0), Reuters OS R0.3 with *US
 
             &FE BBC Micro (American OS A1.0), Reuters OS R0.3 with *US
 
             &FE NetBSD
 
             &FE NetBSD
Line 83: Line 94:
 
             &Ex Spectrum
 
             &Ex Spectrum
 
                 &E0 ZX Spectrum
 
                 &E0 ZX Spectrum
−
                (INKEY-256 AND &F0)=&E0 gives TRUE for ZX Spectrum hardware
+
                (INKEY-256 AND &F0)=&E0 gives TRUE for ZX Spectrum hardware
 
             &Dx Amstrad 464/664/6128, etc.
 
             &Dx Amstrad 464/664/6128, etc.
−
                (INKEY-256 AND &F0)=&D0 gives TRUE for Amstrad CPC hardware
+
                (INKEY-256 AND &F0)=&D0 gives TRUE for Amstrad CPC hardware
 
             &Cx Commodore 64/64+/128, etc.
 
             &Cx Commodore 64/64+/128, etc.
−
                (INKEY-256 AND &F0)=&C0 gives TRUE for Commodore hardware
+
                (INKEY-256 AND &F0)=&C0 gives TRUE for Commodore hardware
 
             &Bx PDP11 Unix
 
             &Bx PDP11 Unix
 
                 &B7 PDP11 Unix Version 7
 
                 &B7 PDP11 Unix Version 7
 
                 &B6 PDP11 Unix Version 6
 
                 &B6 PDP11 Unix Version 6
−
                (INKEY-256 AND &F0)=&B0 gives TRUE for PDP11 hardware
+
                &B5 PDP11 Unix Version 5
 +
                (INKEY-256 AND &F0)=&B0 gives TRUE for PDP11 hardware
 
             &Ax ARM-based systems
 
             &Ax ARM-based systems
 
                 &A0 Arthur 1.20
 
                 &A0 Arthur 1.20
Line 105: Line 117:
 
                 &AA RISC OS 5.xx
 
                 &AA RISC OS 5.xx
 
                 &AE RISC OS Pyromaniac
 
                 &AE RISC OS Pyromaniac
−
                 &AF Springboard   (An ARM-based development system plugged into a PC)
+
                 &AF Springboard - an ARM-based development system plugged into
−
                (INKEY-256 AND &F0)=&A0 gives TRUE for ARM hardware
+
                  a PC)
 +
                (INKEY-256 AND &F0)=&A0 gives TRUE for ARM hardware
 
             &8x Texas Instruments Calculator
 
             &8x Texas Instruments Calculator
 
                 &83 TI-83+(SE)
 
                 &83 TI-83+(SE)
 
                 &84 TI-84+(SE)
 
                 &84 TI-84+(SE)
−
                (INKEY-256 AND &F0)=&80 gives TRUE for TI Calculator hardware
+
                (INKEY-256 AND &F0)=&80 gives TRUE for TI Calculator
 +
                hardware
 
             &68 6809 system
 
             &68 6809 system
 
             &63 6309 system
 
             &63 6309 system
 
             &73 BBC BASIC on SDL abstraction from C source (ie ASC"s")
 
             &73 BBC BASIC on SDL abstraction from C source (ie ASC"s")
 
             &57 BBC BASIC for Windows (ie ASC"W")
 
             &57 BBC BASIC for Windows (ie ASC"W")
−
             &53 BBC BASIC on SDL abstraction from assembly language source (ie ASC"S")
+
             &53 BBC BASIC SDL abstraction from assembly language source
−
                 (INKEY-256 AND &DB)=&53 gives TRUE for R.T.Russell's BBC BASIC for Windows/SDL/etc
+
                (ie ASC"S")
−
             &4D Matrix Brandy BASIC (ie ASC"M") for all builds from V1.22.6 except RISC OS.
+
                 (INKEY-256 AND &DB)=&53 gives TRUE for R.T.Russell's
−
+
                BBC BASIC for Windows/SDL/etc
−
    The known examples of German BBC MOS return X=&FF.
+
            &50 Sega Master System (ASC"P")
−
 
+
             &4D Matrix Brandy BASIC (ie ASC"M") for all builds from v1.22.6
−
Depending on what the program needs to know, [[OSBYTE &00]] is usually the
+
                except RISC OS, and including RISC OS from v1.22.12.
−
more appropriate call to make.
+
            &2A Apple IIgs<ref>https://github.com/bobbimanners/Applecorn/blob/fb180a625c627b8be78ea7a6b36efbfaaeb0350b/auxmem.chario.s#L265</ref>
 +
            &2C Apple IIc
 +
            &2E Apple IIe
 +
 
 +
  The known examples of German BBC MOS return X=&FF.
  
 
==Extensions==
 
==Extensions==
Line 131: Line 149:
  
 
A parameter of &8000-&FEFF is undefined. Some systems extend INKEY as follows:
 
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)
+
   &FE00+nn - scan for low level DOS/Window VK_xxxx keypress (cZ80Tube,
−
   &FC00+nn - scan for low level SDL1.2 SDK_xxx keypress (Brandy test builds)
+
            console library)
−
   &8000+nn - wait for keypress, return 16-bit character code (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==

Latest revision as of 15:03, 4 January 2024

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, and including RISC OS from v1.22.12.
            &2A Apple IIgs[4]
            &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

  1. ↑ http://mdfs.net/Docs/Comp/KeyMap/Regular
  2. ↑ http://mdfs.net/System/C/Lib/console.txt
  3. ↑ Network User, Jan/Feb 1988, p9
  4. ↑ https://github.com/bobbimanners/Applecorn/blob/fb180a625c627b8be78ea7a6b36efbfaaeb0350b/auxmem.chario.s#L265

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

Retrieved from "http://beebwiki.mdfs.net/index.php?title=INKEY&oldid=4607"