Q(uick)BASIC Statement: ON PLAY

Quick View

ON PLAY(n)

An event trapping statement that specifies a subroutine to branch to when there are too few notes in the music queue

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

PLAY ON
PLAY OFF
PLAY STOP
ON PLAY(queuelimit%) GOSUB line

Description/Parameter(s)

PLAY ON	Enables play event trapping.
PLAY OFF	Disables play event trapping.
PLAY STOP	Suspends play event trapping. Events are processed once event trapping is enabled by PLAY ON.
queuelimit%	A number in the range 1 through 32. ON PLAY branches to a subroutine when there are fewer than queuelimit% notes in the music buffer.
line	The label or number of the first line of the event-trapping subroutine.

Example

ON PLAY(3) GOSUB Background
PLAY ON
Music$ = "MBo3L8ED+ED+Eo2Bo3DCL2o2A"
PLAY Music$
LOCATE 2, 1: PRINT "Press any key to stop.";
DO WHILE INKEY$ = "": LOOP
END

Background:
    i% = i% + 1
    LOCATE 1, 1: PRINT "Background called "; i%; "time(s)";
    PLAY Music$
    RETURN

Syntax

ON PLAY(queuelimit) GOSUB {linelabel | linenumber}

Description/Parameter(s)

queuelimit, an integer expression, is the minimum number of notes to maintain in the background music queue (between 1 and 32)
linelabel or linenumber is the first line of the event-handling subroutine to branch to when the number of notes in the music buffer goes from queuelimit to queuelimit - 1

The following three rules apply to the use of ON PLAY:
1. A play event trap occurs only when music is playing in the background. Play event traps do not occur when music is running in the foreground.
2. A play event trap does not occur if the background music queue has already gone from having queuelimit to queuelimit -1 notes when a PLAY ON is executed.
3. If queuelimit is a large number, event traps may occur often enough to slow down the program.

Example

Here is a program that plays continuous music by calling an event-handling subroutine when the music buffer goes from three to two notes:

'  Call subroutine Background when the music buffer goes from
'  3 to 2 notes.
ON PLAY(3) GOSUB Background
'  Turn on event trapping for PLAY.
PLAY ON

'  Define a string containing the melody.
Lizzie$ = "o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A"
'  Play the melody for the first time.
PLAY "MB X" + VARPTR$(Lizzie$)

'  Continue until a key is pressed.
LOCATE 2, 1 : PRINT "Press any key to stop.";
DO WHILE INKEY$ = ""
LOOP
END

' PLAY event-handling subroutine.
Background:
   ' Increment and print a counter each time.
   Count% = Count% + 1
   LOCATE 1, 1 : PRINT "Background called "; Count%; "time(s)";
   ' Execute another PLAY to fill the buffer.
   PLAY "MB X" + VARPTR$(Lizzie$)
RETURN

Syntax

ON PLAY(queuelimit%) GOSUB {linenumber | linelabel}

Description/Parameter(s)


queuelimit%	An integer expression that is the minimum number of notes to maintain in the background music queue (between 1 and 32).
linenumber or linelabel	The first line of the event-handling routine to branch to when the number of notes in the music queue goes from queuelimit% to queuelimit% - 1.
ON PLAY is not available for OS/2 protected mode.

Usage notes

A play-event trap occurs only when music is playing in the background. Play-event traps do not occur when music is running in the foreground.
A play-event trap does not occur if the background-music queue has already gone from having queuelimit% notes to queuelimit% - 1 notes when a PLAY ON is executed.
If queuelimit% is a large number, event traps may occur often enough to slow down the program.

The ON PLAY statement specifies only the start of an event-trapping routine. The ⮜ PLAY Statements ⮞ determine whether the routine is called and how events are handled when trapping is off:

PLAY ON	Enables event trapping. Event trapping occurs only after a PLAY ON statement is executed.
PLAY OFF	Disables event trapping. Even if an event takes place, it is not remembered.
PLAY STOP	Suspends event trapping. Any events that occur are remembered and are trapped as soon as a PLAY 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 other 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.

Example

This example uses the PLAY statements and the PLAY and VARPTR$ functions to play continuous music by calling an event-handling subroutine when the background music buffer goes from three to two notes.

CLS
'Call subroutine Replay when the music buffer goes from 3 to 2 notes.
ON PLAY(3) GOSUB Replay
'Turn on event trapping for PLAY.
PLAY ON
'Define a string containing the melody.
FElise$ = "o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A"
PLAY "MB X" + VARPTR$(FElise$)
'Suspend event trapping until next PLAY ON but remember events that occur
'while event trapping is disabled.
PLAY STOP
'Introduce a variable-length delay.
LOCATE 23, 1: PRINT "Press any key to continue."
DO
LOOP WHILE INKEY$ = ""
 
'Re-enable play event trapping remembering that a PLAY event has occurred.
PLAY ON
LOCATE 23, 1: PRINT "Press any key to stop.    "
'Loop until a key is pressed.
DO
    GOSUB BackGround
LOOP WHILE INKEY$ = ""
'Disable PLAY event processing.
PLAY OFF
'Count down to 0 notes in the queue.
DO
    GOSUB BackGround
LOOP UNTIL NoteCount = 0
END
 
'PLAY event-handling subroutine.
Replay:
    'Increment and print a counter each time.
    Count% = Count% + 1
    LOCATE 3, 1: PRINT "Replay routine called"; Count%; "time(s)";
    'PLAY it again to fill the buffer.
    PLAY "MB X" + VARPTR$(FElise$)
RETURN
 
'Background music queue reporting subroutine.
BackGround:
    'Get a notecount.
    NoteCount = PLAY(0)
    LOCATE 1, 1
    PRINT "Background queue notes remaining --> "; NoteCount
    'Loop until Notecount changes or equals 0.
    DO
    LOOP UNTIL NoteCount <> PLAY(0) OR NoteCount = 0
RETURN