Q(uick)BASIC Statements: PEN

Quick View

PEN

An event-trapping statement that enables, disables, or suspends lightpen-event trapping

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

PEN ON
PEN OFF
PEN STOP

Description/Parameter(s)

The PEN ON statement enables lightpen-event trapping by using an ON PEN statement. The pen is initially off. A lightpen event occurs whenever the lightpen is activated by pressing the tip to the screen or pressing the touch ring. A PEN ON statement must be executed before any read-pen function calls. If a read-pen function is called when the pen is off, an error message results that reads "Illegal function call."

The PEN OFF statement disables lightpen event trapping. The PEN STOP statement suspends lightpen event trapping; a pen event is remembered and trapped as soon as event trapping is enabled.

To speed program execution, the pen should be turned off by using a PEN OFF statement when pen trapping is not needed.

Note: The lightpen requires an IBM Color Graphics Adapter.

Example

See the ⮜ PEN function programming example ⮞, which uses the PEN statement.

Syntax

PEN ON
PEN OFF
PEN STOP

Description/Parameter(s)

PEN ON	Enables trapping of a lightpen event.
PEN OFF	Disables trapping of a lightpen event. Even if an event takes place, it is not remembered.
PEN STOP	Suspends trapping of a lightpen event. Any events that occur are trapped as soon as a PEN ON statement is executed.
The lightpen requires an IBM Color Graphics Adapter. The PEN statements are not available for OS/2 protected mode.

Usage Notes

PEN ON enables lightpen-event trapping. A lightpen event occurs whenever the lightpen is activated by pressing the tip to the screen or pressing the touch ring. If a lightpen event occurs after a PEN ON statement, the routine specified in the ON PEN statement is executed.
PEN OFF disables lightpen-event trapping so no trapping takes place until another PEN ON statement is executed. Events occurring while trapping is off are ignored.
PEN STOP suspends lightpen-event trapping so no trapping takes place until a PEN ON statement is executed. Events occurring while trapping is suspended are remembered and processed when the next PEN ON statement is executed. However, remembered events are lost of PEN OFF is executed.
When a lightpen event trap occurs (that is, the GOSUB is performed),
an automatic PEN STOP is executed so that recursive traps cannot take place. The RETURN from the trapping routine automatically executes a PEN ON statement unless an explicit PEN 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."
PEN ON must be executed before you use the PEN function. If you try to execute the PEN function when the lightpen is off, BASIC generates the error message, "Illegal function call."
For more information, see Chapter 9, "Event Handling" in the Programmer's Guide.

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