ON

command · Also: ON COM, ON ERROR, ON GOSUB, ON GOTO, ON KEY, ON KEYDOWN, ON MOUSECLICK, ON MOUSEDOWN, ON MOUSEMOVE, ON MOUSEUP, ON PEN, ON PLAY, ON STRIG, ON TIMER

Jump to the n-th line number (1-based), or call a SUB when a key or pointer event is waiting. ON ERROR chooses what happens on a runtime error.

ON n GOTO line [, line]… ON n GOSUB line [, line]… ON ERROR GOTO line ON ERROR SKIP [n] ON ERROR IGNORE ON ERROR ABORT ON ERROR CLEAR ON ERROR ON KEY subname ON KEY 0 ON KEY ascii, subname ON KEY ascii, 0 ON KEYDOWN subname ON KEYDOWN 0 ON MOUSECLICK subname ON MOUSEDOWN subname ON MOUSEUP subname ON MOUSEMOVE subname

n - 1-based index into the line list line - destination line numbers, or the error handler subname - SUB called when a key or pointer event is waiting ascii - Colour Maximite 2 key code (see KEYBOARD CODES)

ON KEY subname installs the general key interrupt: subname is called once when a key starts waiting. The key stays in the input buffer for INKEY$ to read; leaving it unread does not call the handler again until another key arrives. Bare ON KEY and ON KEY 0 clear the general interrupt.

ON KEY ascii, subname installs a handler for one key only. The key is removed from the input buffer, so INKEY$ does not also return it. This is independent of the general ON KEY handler, so both can be active at once. Up to 24 per-key handlers may be registered; ON KEY ascii, 0 removes one. Use the same codes as INKEY$, for example Escape 27 and arrows 128-131. Per-key dispatch stops at the first queued key with no handler of its own, so keys behind it wait until the program reads INKEY$.

ON KEYDOWN subname is the held-keys interrupt. It runs whenever the KEYDOWN() held set changes: a key goes down or a held key comes up. It never fires for an operating-system key repeat, and it does not read or consume the INKEY$ queue, so a menu that polls INKEY$ keeps working. The handler takes no arguments; read the new set with KEYDOWN(0) and KEYDOWN(n) (or just track the keys it cares about). Bare ON KEYDOWN and ON KEYDOWN 0 clear the handler. Keys already down when the handler is installed do not fire an event; dispatch starts with the next change. This is the handler to use for “move while an arrow is held” without polling KEYDOWN() from a tick.

Key and mouse handlers run between program lines and during PAUSE or VSYNC_WAIT waits, never in the middle of a statement, and they never nest with each other or with SETTICK.

ON ERROR GOTO jumps to the handler when a runtime error occurs during RUN. RESUME continues at the failing line, RESUME NEXT at the following line, and RESUME line at a chosen line. Without RESUME a second error aborts the program. Entering the handler unwinds any active SUB/FUNCTION/GOSUB call frames, so the handler sees the enclosing scope; see RESUME for how that affects the resume forms.

ON ERROR SKIP [n] ignores errors in the next n statements, then reverts to the OPTION ERROR CONTINUE/ABORT default (ABORT unless CONTINUE is set). The default n is 1. The failing statement is skipped and execution carries on at the next one; the call stack is not unwound, so it works inside a SUB or FUNCTION. ON ERROR IGNORE ignores errors until the handler is changed. ON ERROR ABORT stops trapping for the rest of the RUN, overriding OPTION ERROR CONTINUE; it leaves MM.ERRNO and MM.ERRMSG$ as they are. ON ERROR CLEAR clears MM.ERRNO and MM.ERRMSG$ but keeps the current GOTO/SKIP/IGNORE mode in force. Plain ON ERROR removes the handler, clears both variables, and restores the OPTION ERROR CONTINUE/ABORT default.

An ignored error sets MM.ERRNO to a non-zero error code and MM.ERRMSG$ to the error text. Both are also set when ON ERROR GOTO traps an error. They are cleared at RUN, ON ERROR SKIP, ON ERROR IGNORE and ON ERROR CLEAR.

ON ERROR SKIP 1
OPEN "C:/.scores" FOR OUTPUT AS #1
IF MM.ERRNO <> 0 THEN PRINT "Cannot save: "; MM.ERRMSG$
ON ERROR ABORT

Example:

N = 2
ON N GOTO First, Second, Third
END

First:

PRINT 1

Second:

PRINT 42

Third:

PRINT 3
ON 1 GOSUB A, B
END

A:

PRINT "A"
RETURN

B:

PRINT "B"
RETURN
ON KEY KeyHandler
ON KEY 128, UpHandler

ON MOUSECLICK and ON MOUSEUP need MOUSE ON. The click handler receives (x, y, button$) with button$ equal to “left”, “middle” or “right”; the move handler receives (x, y). ON MOUSEDOWN is an alias of ON MOUSECLICK and fires on the same button press; ON MOUSEUP fires when a button is released, with the same (x, y, button$) arguments.

MOUSE ON
ON MOUSEMOVE MoveHandler
ON MOUSECLICK ClickHandler
ON MOUSEDOWN DownHandler
ON MOUSEUP UpHandler

Source: docs/help/on.txt inmmcore. On the computer, typeHELP ON.