Q(uick)BASIC Statement: ON PEN

Quick View

ON PEN

An event trapping statement that specifies a subroutine to branch to when the lightpen is activated

Worth knowing

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

Syntax

PEN ON
PEN OFF
PEN STOP
ON PEN GOSUB line

Description/Parameter(s)

PEN ON	Enables light-pen event trapping.
PEN OFF	Disables light-pen event trapping.
PEN STOP	Suspends light-pen event trapping. Events are processed once event trapping is enabled by PEN ON.
line	The label or number of the first line of the event-trapping subroutine.

Example

    'This example requires a light pen.
    ON PEN GOSUB Handler
    PEN ON
    PRINT "Press Esc to exit."
    DO UNTIL INKEY$ = CHR$(27): LOOP
    END

Handler:
    PRINT "Pen is at row"; PEN(6); ", column"; PEN(7)
    RETURN

Syntax

ON PEN GOSUB {linelabel | linenumber}

Description/Parameter(s)

Any activation of the lightpen will be trapped.
linelabel or linenumber is the first line of the event-handling subroutine

Example

There is no programming example for the ON PEN statement.
The following programming examples show how to integrate ON event statements, statements that enable traps, and event-handling subroutines into a working program:⮜ ON PLAY ⮞
⮜ ON TIMER ⮞

Syntax

ON PEN GOSUB {linenumber | linelabel}

Description/Parameter(s)

linenumber or linelabel

A linenumber value of 0 disables event trapping and does not specify line 0 as the start of the routine.

Usage Notes

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

PEN ON	Enables event trapping. Event trapping occurs only after a PEN ON statement is executed.
PEN OFF	Disables event trapping. Even if an event takes place, it is not remembered.
PEN STOP	Suspends event trapping. Any events that occur are remembered and are trapped as soon as a PEN 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 PEN statement to enable event trapping and the PEN function to display current light pen status and position. ON PEN GOSUB passes control to the PenReport subroutine when a pen event occurs.
Note: Do not run this example if your mouse driver is enabled.

CLS                'Clear screen.
COLOR 0, 7         'Set black on white.
CLS                'Clear screen.
PEN ON             'Enable light pen.
ON PEN GOSUB PenReport
DO
    LOCATE 23, 12
    PRINT "Press the Light Pen against the screen to see a report."
    LOCATE 24, 17
    PRINT "  Press the Space Bar to exit the program.     ";
LOOP UNTIL INKEY$ = " "
PEN OFF            'Disable light pen.
COLOR 7, 0         'Set back to black on white.
CLS                'Clean up the screen.
END
 
PenReport:
    DO
  P = PEN(3)
  'Report light pen status and get X and Y position.
  LOCATE 10, 27
  PRINT "A Pen event has occurred."
  LOCATE 24, 17
  PRINT "Press ANY key to exit the Light Pen report.";
  LOCATE 12, 30
  PRINT "Light Pen is ";
  IF P THEN
      PRINT "Down"
      X = PEN(4): Y = PEN(5)
  ELSE
      PRINT "Up  "
      X = 0: Y = 0
  END IF
  'Report the X and Y position.
  LOCATE 14, 22
  PRINT "X Position ="; X; "   "
  LOCATE 14, 40
  PRINT "Y Position ="; Y; "   "
    LOOP WHILE INKEY$ = ""
    RETURN