ON KEY, ON KEY =, ON KEY Label, On(“Key”), POP KEY, PUSH KEY

These commands provide the ability to interrupt the flow of normal event processing by jumping immediately to a routine you’ve created. Similar to the dreaded GOTO command of the venerable BASIC language (and others), these can lead to code nearly impossible to debug.

Usage

ON KEY [ Command ]
cOnCommand = ON( "KEY" )
ON KEY = nKeyCode [ Command ]
ON KEY LABEL KeyLabel [ Command ]
cOKLCommand = ON( "KEY", cKeyLabel )

These commands allow developers to trap a number of keystrokes and perform processing based on them. Unfortunately, in order to make the ON KEYs work properly, the detection of these keystrokes is built right into the native event loop, and checking for these keystrokes occurs between each line of code processed. That means when a specified key is pressed, regardless of what process was in effect, control jumps immediately to the specified procedure. When the procedure is completed, control attempts to return to the line of code following the one last executed.

That’s cool if you write perfect code that restores everything to the way it was before you started, and you never run timing-critical code while the ON KEYs are in effect. But if you ever forget to reselect the original work area, or reset a SET command, heaven help you. If the code that was in process before the ON KEY rudely interrupted depends on these settings, the code you’ve been running for weeks, months or years, the code you know works without a fault will crash and burn, and you will be left trying to explain how your code could have failed in this bizarre manner.

As you may surmise, we’re not in favor of using ON KEYs. Although other alternatives might require a little more coding up front, they will provide a more stable final product. Use the KeyPress event to trap individual characters, or hot-key accelerators in the Captions of controls to switch focus to a new control. Use keyboard macros to stuff the keyboard.

Where ON KEY LABELS (OKLs, for short) do still have a place is in development. We prefer to use keyboard macros for events we would like to have occur only while the machine is in an “inputable” wait state, but sometimes you need to interrupt running procedures, and nothing will get you out of an infinite loop like an OKL along the lines of ON KEY LABEL F12 CANCEL. Ted likes to open the debugger with an OKL on F11 set to DEBUG.

Our advice: Avoid the ON KEY and ON KEY= commands and stick with the native event loop. Use ON KEY LABELs only in development situations where the native event loop must be overridden.

Example

ON KEY LABEL F3 DEBUG

* TestKeys - display the ASC() value of most keyboard keys
* Press Escape when done
SET ESCAPE ON
ON ESCAPE RETURN
DO WHILE .T.
  ON KEY WAIT WINDOW NOWAIT LTRIM(STR(INKEY()))
ENDDO

Usage

PUSH KEY [ CLEAR ]
POP KEY [ ALL ]

PUSH KEY stores the current ON KEY settings to a stack, and POP KEY brings these definitions back into effect. The CLEAR keyword clears all definitions that were in effect, until the POP KEY is used to restore them. The ALL keyword POPs all stored functions off the stack.

Use PUSH KEY CLEAR when entering a routine where you want no ON KEYs to be in effect, such as a modal form, or where you want to set a whole new batch of ON KEYs, or in the actual procedure called by the ON KEY routine. Use POP KEY ALL to CLEAR ALL ON KEY LABELs. ON KEYs, on the other hand, must be cleared with an ON KEY command.

See Also

KeyPress, On(), Set Function