Q(uick)BASIC Statement: ON KEY

• n, an integer expression, is the number of a function key, direction key, or user-defined key
• linelabel or linenumber is the first line of the event-handling subroutine

• Keys are processed in the following order:
  1. The line printer's echo-toggle key is processed first. Defining this key as a user-defined key trap does not prevent characters from being echoed to the line printer when pressed.
  2. Function keys and the cursor-direction keys are examined next. Defining a FUNCTION key or DIRECTION key as a user-defined key trap has no effect because these keys are predefined.
• The ON KEY statement can trap any key, including BREAK or system reset. This makes it possible to prevent accidentally breaking out of a program or rebooting the machine.

Usage Notes

• Keys are processed in the following order:
  1. The line printer's echo-toggle key is processed first. Defining this key as a user-defined key trap does not prevent characters from being echoed to the line printer when pressed.
  2. Function keys and the direction keys are examined next. Defining a function key or direction key as a user-defined key trap has no effect because these keys are predefined.
  3. Finally, the user-defined keys are examined.
• The ON KEY statement can trap any key, including Break or system reset (Ctrl+Alt+Del). This makes it possible to prevent accidentally breaking out of a program or rebooting the machine.
• The ON KEY statement specifies only the start of an event-trapping routine. The ⮜ KEY Statements ⮞ determine whether the routine is called and how events are handled when trapping is off:

  KEY ON	Enables event trapping. Event trapping occurs only after a KEY ON statement is executed.
  KEY OFF	Disables event trapping. Even if an event takes place, it is not remembered.
  KEY STOP	Suspends event trapping. Any events that occur are remembered and are trapped as soon as a KEY ON statement is executed.

• If your program contains event-handling statements and you are compiling from the BC command line, use the BC /W or /V option. (The /W option checks for events at every label or line number; the /V option checks at every statement.) If you do not use these options and your program contains event traps, BASIC generates the error message, "ON event without /V or /W on command line."
• The RETURN linenumber or RETURN linelabel forms of RETURN can be used to return to a specific line from the trapping routine. Use this type of return with care, however, because any GOSUB, WHILE, or FOR statements active at the time of the trap remain active. BASIC may generate error messages such as "NEXT without FOR." In addition, if an event occurs in a procedure, a RETURN linenumber or RETURN linelabel statement cannot get back into the procedure because the line number or label must be in the module-level code.

Important

• After a key is trapped, the information on which key was trapped is no longer available. This means that you cannot subsequently use an INPUT statement or INKEY$ function to find out which key caused the trap. Because you do not know which key press caused the trap, you must create a different event-handling routine for each key you want to trap.