Q(uick)BASIC Statements (Event Trapping): KEY

The argument n is the number of a FUNCTION key, a cursor-direction key, or a user-defined key. See the KEY statements for information on assigning soft-key values to FUNCTION keys. The values of n are as follows:

LEFT, RIGHT, UP, and DOWN refer to the direction keys.

You can enable trapping of combination keys by using a variation of the KEY statement:

• KEY n, CHR$(keyboardflag) + CHR$(scancode)

The argument n is in the range 15-25 to indicate a user-defined key. The keyboardflag can be any combination of the following hexadecimal values:

You can add the values together to test for multiple shift states. A keyboardflag value of &H12 would test for both CTRL and ALT being pressed, for example.

Because key trapping assumes the left and right SHIFT keys are the same, you can use either &H01, &H02, or &H03 to indicate a SHIFT key. The scancode argument is a number identifying one of the 83 keys to trap, as shown in the ⮜ Keyboard Scan Codes ⮞.

The KEY(n) ON statement enables soft-key or cursor-direction-key event trapping by an ON KEY statement. If you specify a nonzero line number in the ON KEY statement while trapping is enabled, BASIC checks to see if you have pressed KEY(n). If you have, BASIC executes the GOSUB clause in the ON KEY statement. The text that would normally be associated with a FUNCTION key is not input.

When you are working in the environment, QuickBASIC tests between statements for key presses. In stand-alone programs, you can specify checking between lines.

KEY(n) OFF disables the event trap; even if an event takes place, it is not remembered. KEY(n) STOP inhibits the event trap; that is, if you press the specified key your action is remembered and an ON KEY event trap is executed as soon as a KEY(n) ON statement is executed.

Usage Notes

• KEY(n%) ON enables trapping of function keys, direction keys, and user-defined keys. If key n% is pressed after a KEY(n%) ON statement, the routine specified in the ON KEY statement is executed.
• KEY(n%) OFF disables trapping of key n%. No trapping takes place until another KEY(n%) ON statement is executed. Events occurring while trapping is off are ignored.
• KEY(n%) STOP suspends trapping of key n%. No trapping takes place until a KEY(n%) ON statement is executed. Events occurring while trapping is suspended are remembered and processed when the next KEY(n%) ON statement is executed. However, remembered events are lost if KEY(n%) OFF is executed.
• When a key event trap occurs (that is, the GOSUB is performed), an automatic KEY STOP is executed so that recursive traps cannot take place. The RETURN from the trapping routine automatically executes a KEY ON statement unless an explicit KEY OFF was performed inside the routine.
• 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."
• For more information, see Chapter 9, "Event Handling" in the Programmer's Guide.

User-Defined Keys

• In addition to providing the preassigned key numbers 1-14 (plus 30 and 31 with the 101-key keyboard), BASIC enables you to create user- defined keys. You do this by assigning the numbers 15-25 to any of the remaining keys on the keyboard. Use ⮜ KEY (Assignment) ⮞ to create user-defined keys.
• You can also set a trap for "shifted" keys. A key is shifted when you press it simultaneously with one or more of the special keys Shift, Ctrl, or Alt, or if you press it after pressing NumLock or Caps Lock. Use the KEY statements (assignment) to define shifted keys before you can trap them. The syntax for KEY (Assignment) is shown below:

• KEY n%, CHR$(keyboardflag) + CHR$(scancode)

• You can add the values in the Keyboard Flag Table together to test for multiple shift states. A keyboardflag value of 12 would test for both Ctrl and Alt being pressed, for example.
• To define Shift, Ctrl, Alt, NumLock, or Caps Lock as a user-defined key (by itself, not in combination with another key), use a keyboard flag of 0. For example, to define Alt as a user-defined key:

• KEY CHR$(0) + CHR$(56)

• To define Alt + Alt as a user-defined key (the second Alt will be trapped as it is being pressed only if the first Alt key is already pressed):

• KEY CHR$(8) + CHR$(56)

• Because key trapping assumes the left and right Shift keys are the same, you can use either 1, 2, or 3 to indicate a Shift key. The scancode argument is a number identifying one of the 83 keys to trap, as shown in the ⮜ Scan Code Table ⮞.
• The scan codes in the Scan Code Table are equivalent to the first column of the scan code table in Appendix A, "Keyboard Codes and ASCII Character Codes" in the BASIC Language Reference. The codes in the other columns of the table in the appendix should not be used for key trapping.