To create an event trap line number for a specified event (such as communications, pressing function or cursor control keys, using the light pen, or using joysticks).
ON event specifier GOSUB line number
The syntax shown sets up an event trap line number for the specified event. A line number of 0 disables trapping for this event.
Once trap line numbers have been set, event trapping itself can be controlled with the following syntax lines:
| event specifier ON | When an event is ON, and a nonzero line number is specified for the trap, then every time BASIC starts a new statement, it checks to see if the specified event has occurred. If it has, BASIC performs a GOSUB to the line specified in the ON statement. |
| event specifier OFF | When an event is OFF, no trapping occurs and the event is not remembered, even if it occurs. |
| event specifier STOP | When an event is stopped, no trapping can occur, but if the event happens, it is remembered so an immediate trap occurs when an event specifier ON is executed. |
When a trap is made for a particular event, the trap automatically causes a stop on that event, so recursive traps can never take place.
The return from the trap routine automatically does an ON unless an explicit OFF has been performed inside the trap routine.
When an error trap takes place, this automatically disables all trapping.
Trapping will never take place when BASIC is not executing a program.
The following are valid values for event specifier:
| COM(n) | n is the number of the COM channel (1 or 2). |
| KEY(n) | n is a function key number 1-20. 1 through 10 are the function keys F1 through F10. 11 through 14 are the cursor control keys as follows: 11= CURSOR UP 13= CURSOR RIGHT 15-20 are user-defined keys. |
| PEN | Since there is only one pen, no number is given. |
| PLAY(n) | n is an integer expression in the range of 1-32. Values outside this range result in "Illegal function call" errors. |
| STRIG(n) | n is 0, 2, 4 or 6. (0=trigger A1; 4=trigger A2; 2=trigger B1; 6=trigger B2). |
| TIMER(n) | n is a numeric expression within the range of 1 to 86,400. A value outside of this range results in an "Illegal function call" error. |
| RETURN line number | This optional form of RETURN is primarily intended for use with event trapping. The event-trapping routine may want to go back into the GW-BASIC program at a fixed line number while still eliminating the GOSUB entry that the trap created. Use of the nonlocal RETURN must be done with care. Any other GOSUB, WHILE, or FOR that was active at the time of the trap remains active. If the trap comes out of a subroutine, any attempt to continue loops outside the subroutine results in a "NEXT without FOR" error. |
Typically, the COM trap routine will read an entire message from the COM port before returning.
It is recommended that you not use the COM trap for single character messages, since at high baud rates the overhead of trapping and reading for each individual character may allow the interrupt buffer for COM to overflow.
Trappable keys 15 to 20 are defined by the following statement:
KEY(n),CHR$[hex code]+CHR$[scan code]
n is an integer expression within the range of 15 to 20 defining the key to be trapped.
hex code is the mask for the latched key: (CAPS LOCK, NUM LOCK, ALT, CTRL, LEFT SHIFT, RIGHT SHIFT)
scan code is the number identifying one of the 83 keys to trap. Refer to Appendix H in the GW-BASIC User's Guide for key scan codes.
The appropriate bit in hex code must be set in order to trap a key that is shifted, control-shifted, or alt-shifted. hex code values are as follows:
| Mask | Hex code | Indicates that |
| EXTENDED | &H80 | Key is extended |
| CAPS LOCK | &H40 | CAPS LOCK is active |
| NUM LOCK | &H20 | NUM LOCK is active |
| ALT | &H08 | The ALT key is pressed |
| CTRL | &H04 | The CTRL key is pressed |
| LEFT SHIFT | &H02 | The left SHIFT key is pressed |
| RIGHT SHIFT | &H01 | The right SHIFT key is pressed |
For trapping shifted keys, you may use the value &H01, &H02, or &H03. The left and right SHIFT keys are coupled when &H03 is used.
Refer to the KEY(n) statement for more information.
No type of trapping is activated when GW-BASIC is in direct mode. Function keys resume their standard expansion meaning during input.
A key that causes a trap is not available for examination with the INPUT or INKEY$ statement, so the trap routine for each key must be different if a different function is desired.
If CTL-PRTSCR is trapped, the line printer echo toggle is processed first. Defining CTL-PRTSCR as a key trap does not prevent characters from being echoed to the printer if CTL-PRTSCR is pressed.
Function keys 1 through 14 are predefined. Therefore, setting scan codes 59-68, 72, 75, 77, or 80 has no effect.
A PLAY event trap is issued only when playing background music (PLAY"MB..). PLAY event music traps are not issued when running in MUSIC foreground (default case, or PLAY"MF..).
Choose conservative values for n. An ON PLAY(32).. statement will cause event traps so often that there will be little time to execute the rest of your program.
The ON PLAY(n) statement causes an event trap when the background music queue goes from n to n-1 notes.
Using STRIG(n) ON activates the interrupt routine that checks the trigger status. Down-strokes that cause trapping will not set STRIG(0), STRIG(2), STRIG(4), or STRIG(6) functions.
An ON TIMER(n) event trapping statement is used with applications needing an internal timer. The trap occurs when n seconds have elapsed since the TIMER ON statement.
This is a very simple terminal program.
10 REM "ON COM(n)" EXAMPLE 20 OPEN "COM1:9600, O, 7" AS #1 30 ON COM(1) GOSUB 80 40 COM(1) ON 50 REM TRANSMIT CHARACTERS FROM KEYBOARD 60 A$=INKEY$: IF A$=""THEN 50 70 PRINT #1, A$;: GOTO 50 80 REM DISPLAY RECEIVE CHARACTERS 90 ALL=LOC(1): IF ALL<1 THEN RETURN 100 B$=INPUT$(ALL, #1): PRINT B$;:RETURN
Prevents a CTRL-BREAK or system reset during a program.
10 KEY 15, CHR$(4)+CHR$(70) REM Trap ^BREAK 20 KEY 16, CHR$(12)+CHR$(83) REM Trap system reset 30 ON KEY(15) GOSUB 1000 40 ON KEY(16) GOSUB 2000 50 KEY(15) ON 60 KEY(16) ON . . . 1000 PRINT "I'm sorry, I can't let you do that" 1010 RETURN 2000 ATTEMPS=ATTEMPS+1 2010 ON ATTEMPS GOTO 2100, 2200, 2300, 2400, 2500 2100 PRINT "Mary had a little lamb": RETURN 2200 PRINT "Its fleece was white as snow": RETURN 2300 PRINT "And everywhere that Mary went": RETURN 2400 PRINT "The lamb was sure to go": RETURN 2500 KEY(16) OFF REM If they hit us once more... 2510 RETURN REM then BASIC dies...
Displays the time of day on line 1 every minute.
10 ON TIMER(60) GOSUB 10000 20 TIMER ON . . . 10000 OLDROW=CSRLIN REM Saves the current row 10010 OLDCOL=POS(0) REM Saves the current column 10020 LOCATE 1, 1: PRINT TIME$ 10030 LOCATE OLDROW, OLDCOL REM Restores row and column 10040 RETURN