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

Quick View

PLAY ON, PLAY OFF, and PLAY STOP

Event-trapping statements that enable, disable, and suspend play event trapping

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

PLAY ON
PLAY OFF
PLAY STOP

Description/Parameter(s)

PLAY ON enables play-event trapping by an ON PLAY statement.
PLAY OFF disables the event trap; even if an event takes place, it is not remembered.
PLAY STOP inhibits the event trap; if an event takes place, it is remembered and the ON PLAY event-trap will be executed as soon as PLAY ON is executed.

These statements are used with the ON PLAY statement to trap play events. When a PLAY OFF statement is executed, the event-trapping subroutine is not performed and the event is not remembered.

A PLAY STOP statement does not perform the event-trapping subroutine, but the subroutine is performed as soon as a PLAY ON statement is executed.

When a play event trap occurs (that is, the GOSUB is performed), an automatic PLAY STOP is executed so that recursive traps cannot take place. The RETURN from the trapping subroutine automatically performs a PLAY ON statement unless an explicit PLAY OFF was performed inside the subroutine.

Example

See the ⮜ ON PLAY(n) statement programming example ⮞, which uses the PLAY ON statement.

Syntax

PLAY ON
PLAY OFF
PLAY STOP

Description/Parameter(s)

PLAY ON	Enables trapping of a play event by a PLAY ON statement.
PLAY OFF	Disables the event trap. Even if an event takes place, it is not remembered.
PLAY STOP	Suspends the event trap. Any events that occur remembered and are trapped as soon as the PLAY ON statement is executed.
The PLAY statements (event trapping) are not available for OS/2 protected mode.

Usage notes

PLAY ON enables play-event trapping. A play event occurs when the number of notes in the background-music queue drops below the limit you set in the ON PLAY statement. If a play event occurs after a PLAY ON statement, the routine specified in the ON PLAY statement is executed.
PLAY OFF disables play-event trapping so no trapping takes place until another PLAY ON statement is executed. Events occurring while trapping is off are ignored.
PLAY STOP suspends play-event trapping so no trapping takes place until a PLAY ON statement is executed. Events occurring while trapping is suspended are remembered and processed when the next PLAY ON statement is executed. However, remembered events are lost if PLAY OFF is executed.
When a play-event trap occurs (that is, the GOSUB is performed), an automatic PLAY STOP is executed so that recursive traps cannot take place. The RETURN from the trapping routine automatically executes a PLAY ON statement unless an explicit PLAY 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.

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