Tandy 1000 Basic Reference Manual page 238

Chapter 10 I
BASIC
Keywords
ON PLAY() GOSUB
Statement
ON PLAY(number) GOSUB line
Transfers program control to a subroutine when the number of
notes in the background music buffer goes from
number
to
num-
ber
minus 1. This event trapping allows continuous music by let-
ting you maintain a full music buffer.
Number
is a n integer in the range 1 to 32, indicating that con-
trol should transfer to
line
when the number of notes left in the
music buffer is less than
number.
Line
is the first line of the subroutine to execute when the num-
ber of notes in the music buffer is less than
number.
If you spec-
ify Line 0, you turn off play event trapping. Use the RETURN
statement to exit the subroutine.
BASIC executes the ON PLAY() GOSUB statement only when
playing background music (PLAY "MB") and if the PLAY ON
statement has been executed to enable event trapping.
If a PLAY STOP statement has been issued to halt event trap-
ping temporarily, BASIC executes the subroutine immediately
after the next PLAY ON statement.
When you execute the
ON
PLAY() GOSUB statement, BASIC
immediately issues a PLAY() STOP to prevent recursive traps.
When BASIC executes the RETURN from the subroutine, it au-
tomatically executes another PLAY0 ON statement t o enable
trapping again, unless the subroutine executes a PLAY0 OFF
statement
.
Notes: BASIC does not issue a play event trap if the
background music queue is already empty when you
execute a PLAY ON.
The PLAY statement is supported by a 32-element mu-
sic queue. Given that "normal" and "staccato" notes
are constructed from 2-note elements, the queue can
contain as few as 16 notes or as many as 32 notes.
236