+---------------------------------+
|          ON KEY LABEL           |
+---------------------------------+
ON KEY [LABEL <key label>]
        [<command>]

-----------------------------------
Traps for specific keys being pressed.
-----------------------------------

The ON KEY LABEL command sets a trap for specific keys being pressed or
a click of a mouse button.  If any of the specified keys are pressed or
the mouse is clicked, the trap is triggered and the <command> is
executed.

Unlike ON KEY, you may have multiple ON KEY LABEL commands active at a
time.  For example, you could have an ON KEY LABEL routine specified for
each of the arrow keys and both mouse buttons.  The <key label> is the
letter or digit on the key itself, or a special name assigned to the
key.  See the following table for the special <key label> assignments.

ON KEY LABEL traps the specified key immediately while in READ, BROWSE,
EDIT, CHANGE, user-defined menus and popups.  ON KEY LABEL also traps
the specified key at inter-statement transition.  After an ON KEY LABEL
routine is complete, program execution resumes on the line immediately
following the line on which the branch occurred.  However, if the
<command> is DO <program> and the <program> is exited via a RETRY
statement, execution resumes on the same line on which the branch
occurred.  If a READ is active and an ON KEY LABEL routine is executed,
you are returned to the READ.

ON KEY LABEL also extends to the FoxPro interactive mode.  The ON KEY
LABEL key assignments remain in effect after a program is exited, and
you may issue the ON KEY LABEL command from within the Command window.

For example, you may redefine the "A" key to "B" by issuing the command
ON KEY LABEL A KEYBOARD "B" in the Command window or a program.
Pressing the "A" key will then return the letter "B".  With a series of
ON KEY LABEL statements you could redefine your keys to emulate a Dvorak
keyboard.

The ON KEY LABEL key assignments are not in effect in all areas of the
FoxPro interactive environment.  The exceptions are the System menu bar,
dialogs, alerts, System popups and so on.  The ON KEY LABEL key
assignments are if effect in System windows -- the FoxPro text editor,
the Command window, the Trace window, etc.

If you use a defined function or macro key in an ON KEY LABEL routine,
the function or macro definition takes precedence in commands that wait
for keyboard input (READ, BROWSE, EDIT, INPUT, ACCEPT, etc.).  You must
first clear the function or macro key to execute your ON KEY LABEL
routine in these commands.  A function key may be cleared with the
command SET FUNCTION <function key name> TO.  A macro key may be cleared
from the Macros... option of the System menu.

   Special Key Label Assignments

Keycap
Identification                  <key label>
-----------------------------------

Left arrow                              LEFTARROW
Right arrow                             RIGHTARROW
Up arrow                                UPARROW
Down arrow                              DNARROW
Home                                    HOME
End                                             END
PgUp                                    PGUP
PgDn                                    PGDN
Del                                             DEL
Backspace                               BACKSPACE
Spacebar                                SPACEBAR
Ins                                             INS
Tab                                             TAB
Shift Tab                               BACKTAB
Enter                                   ENTER
{                                               LBRACE
}                                               RBRACE
F1 to F12                               F1, F2 ...
Ctrl+F1 to Ctrl+F12             Ctrl+F1, Ctrl+F2 ...
Shift+F1 to Shift+F9    Shift+F1, Shift+F9...
Shift+F11, Shift+F12    Shift+F11 ...
Alt+F1 to Alt+F12               Alt+F1, Alt+F2 ...
Alt+0 to Alt-9                  Alt+0, Alt+1 ...
Alt+A to Alt+Z                  Alt+A, Alt+B ...
Ctrl+left arrow                 Ctrl+LEFTARROW
Ctrl+right arrow                Ctrl+RIGHTARROW
Ctrl+Home                               Ctrl+HOME
Ctrl+End                                Ctrl+END
Ctrl+PgUp                               Ctrl+PGUP
Ctrl+PgDn                               Ctrl+PGDN
Ctrl+A to Ctrl+Z                Ctrl+A, Ctrl+B ...
Right Mouse                             RIGHTMOUSE
Left Mouse                              LEFTMOUSE
Mouse                                   MOUSE
Escape                                  ESC

+---------------------------------+
|         Program Example         |
+---------------------------------+
This example outputs appropriate message if one of arrow keys is
pressed.

SET TALK OFF
CLEAR
ON KEY LABEL RIGHTARROW ? 'Right Arrow'
ON KEY LABEL LEFTARROW ? 'Left Arrow'
ON KEY LABEL UPARROW ? 'Up Arrow'
ON KEY LABEL DNARROW ? 'Down Arrow'
SET ESCAPE ON
STORE .F. TO mexit
ON ESCAPE STORE .T. TO mexit
STORE 0 TO TEMP
@ 0,0 SAY 'Press an arrow key to test ON KEY LABEL, <Escape> to exit'
DEFINE WINDOW menter FROM 10,20 TO 14,60 DOUBLE
ACTIVATE WINDOW menter
DO WHILE NOT mexit
ENDDO
DEACTIVATE WINDOW menter
ON KEY

-----------------------------------

See Also:  INKEY(), LASTKEY(), ON KEY, ON(), READKEY()

-----------------------------------