Share via

ON KEY LABEL Command

  • Article

Specifies a command that executes when you press a specific key or key combination or click the mouse button.

ON KEY [LABEL KeyLabelName] [Command]

Parameters

  • LABEL KeyLabelName
    Specifies the key label name assigned to the key. The KeyLabelName is the letter or digit on the key or a special name assigned to the key. The following table lists the special key label names.

    Visual FoxPro key label assignments

    For this key

    Specify this KeyLabelName value
    ArrowLeft screenshot

    LEFTARROW
    ArrowRight screenshot

    RIGHTARROW
    ArrowUp screenshot

    UPARROW
    ArrowDown screenshot

    DNARROW

    HOME

    HOME

    END

    END

    PAGE UP

    PGUP

    PAGE DOWN

    PGDN

    DEL

    DEL

    BACKSPACE

    BACKSPACE

    SPACEBAR

    SPACEBAR

    INS

    INS

    TAB

    TAB

    SHIFT+TAB

    BACKTAB

    Left Brace

    LBRACE

    Right Brace

    RBRACE

    ENTER

    ENTER

    F1 to F12

    F1, F2, F3 ...

    CTRL+F1 to CTRL+F12

    CTRL+F1, CTRL+F2 ...

    SHIFT+F1 to SHIFT+F12

    SHIFT+F1, SHIFT+F2 ...

    ALT+F1 to ALT+F12

    ALT+F1, ALT+F2, ALT+F3 ...

    ALT+0 to ALT+9

    ALT+0, ALT+1, ALT+2 ...

    ALT+A to ALT+Z

    ALT+A, ALT+B, ALT+C ...

    CTRL+LEFT ARROW

    CTRL+LEFTARROW

    CTRL+RIGHT ARROW

    CTRL+RIGHTARROW

    CTRL+HOME

    CTRL+HOME

    CTRL+END

    CTRL+END

    CTRL+PAGE UP

    CTRL+PGUP

    CTRL+PAGE DOWN

    CTRL+PGDN

    CTRL+A TO CTRL+Z

    CTRL+A, CTRL+B, CTRL+C ...

    CTRL+0

    CTRL+0

    RIGHT MOUSE BUTTON

    RIGHTMOUSE

    LEFT MOUSE BUTTON

    LEFTMOUSE

    MOUSE BUTTON

    MOUSE

    ESC

    ESC

  • Command
    Specifies the command that executes when you press the specified key or key combination or click the mouse button.

    You can include parameter or parameter expressions with the command that you assign to the key, as in the following example:

    ON KEY LABEL ALT+V WAIT WINDOW "Version: " + VERSION()

    You can include variables in the assignment, but they must be public. For example:

    PUBLIC message
message = "Default drive: " + SYS(5)
ON KEY LABEL ALT+D WAIT WINDOW message

Remarks

ON KEY LABEL typically uses DO to execute a procedure.

ON KEY LABEL executes the command immediately during the execution of READ, BROWSE, EDIT, CHANGE, and user-defined menus. If a program is executing when you press the key or click the mouse button, Visual FoxPro executes the current program line and then executes the ON KEY LABEL command. Any ON KEY LABEL key assignments created in a program remain in effect after the program is run. You can also create key assignments in the Command window.

To restore the behavior of a specific key to normal, issue ON KEY LABEL KeyLabelName. To restore all keys to their default behavior, issue ON KEY.

Tip

To prevent recursive calls during the execution of an ON KEY LABEL procedure, include PUSH KEY CLEAR early in the procedure to disable all active ON KEY LABEL commands. Issue POP KEY at the end of the procedure to enable the ON KEY LABEL commands.

The ON KEY LABEL key assignments aren't in effect in the Visual FoxPro system menu bar, system menus, dialog boxes, alerts, and so on. The key assignments are effective in the Visual FoxPro system windows — the Visual FoxPro text editor, the Command window, the Trace window, and so on.

Unlike ON KEY, there can be multiple active ON KEY LABEL commands. For example, you can assign a command to each of the arrow keys and a mouse button.

Executing an ON KEY LABEL resets PARAMETERS( ) to 0. For more information, see PARAMETERS( ) Function.

In Visual FoxPro, certain events cannot be trapped because they are under the control of Windows. In particular, ON KEY LABEL MOUSE, ON KEY LABEL LEFTMOUSE, and ON KEY LABEL RIGHTMOUSE are not executed when you click a Windows control such as a Control menu, scroll bar, or the like. Also, CTRL+0 is supported in ON KEY LABEL in Visual FoxPro, allowing you to redefine the key combination used to enter a null value into a field.

Note that ON KEY LABEL operates outside of the scope of a form; the KeyPress event can be used within forms to execute code when a key is pressed.

Example

The following example displays a message when an arrow key is pressed.

CLEAR
PUBLIC msg
msg = CHR(13) + CHR(13) + "Press F9 to " + ;
   "restore default key definition."
ON KEY LABEL RIGHTARROW Wait Window "Right Arrow " + msg NOWAIT
ON KEY LABEL LEFTARROW Wait Window "Left Arrow " + msg NOWAIT
ON KEY LABEL UPARROW Wait Window "Up Arrow " + msg NOWAIT
ON KEY LABEL DNARROW Wait Window "Down Arrow " + msg NOWAIT

* Press F9 to clear the ON KEY LABEL assignments
ON KEY LABEL F9 ON KEY

See Also

Reference

INKEY( ) Function

KeyPress Event

ON( ) Function

POP KEY Command

PUSH KEY Command

Other Resources

Commands (Visual FoxPro)