SET KEY
 Assign a procedure invocation to a key
------------------------------------------------------------------------------
 Syntax

     SET KEY <nInkeyCode> TO [<idProcedure>]

 Arguments

     <nInkeyCode> is the INKEY() value of the key that receives the
     assignment.

     TO <idProcedure> specifies the name of a procedure that executes
     when the user presses the assigned key.  If <idProcedure> is not
     specified, the current <nInkeyCode> definition is released.

 Description

     SET KEY is a keyboard command that allows a procedure to be executed
     from any wait state when a designated key is pressed.  A wait state is
     any mode that extracts keys from the keyboard except for INKEY().  These
     modes include ACHOICE(), DBEDIT(), MEMOEDIT(), ACCEPT, INPUT, READ and
     WAIT.  After a key is redefined, pressing it executes the specified
     procedure, passing three automatic parameters corresponding to
     PROCNAME(), PROCLINE(), and READVAR().  The procedure and variable
     parameters are character data type, while the line number is numeric
     data type.

     You may define a maximum of 32 keys at one time.  At startup, the system
     automatically defines the F1 key to execute Help.  If a procedure with
     this name is linked into the current program and it is visible, pressing
     F1 from a wait state invokes it.

     Note that SET KEY procedures should preserve the state of the
     application (i.e., screen appearance, current work area, etc.) and
     restore it before exiting.

     Warning!  In CA-Clipper, SET FUNCTION is preprocessed into the SET
     KEY and KEYBOARD commands.  This means that SET FUNCTION has the effect
     of clearing any SET KEY for the same key number and vice versa.  This is
     incompatible with previous releases, which maintained separate lists of
     SET FUNCTION keys and SET KEY keys.

 Notes

     .  Precedence: SET KEY definitions take precedence over SET
        ESCAPE and SETCANCEL().

     .  CLEAR with a SET KEY procedure: Do not use CLEAR to clear the
        screen within a SET KEY procedure since it also CLEARs GETs and,
        therefore, terminates READ.  When you need to clear the screen, use
        CLEAR SCREEN or CLS instead.

     .  Terminating a READ from a SET KEY procedure: The following
        table illustrates several ways to terminate a READ from within a SET
        KEY procedure.

        Terminating a READ from a SET KEY Procedure
        ---------------------------------------------------------------------
        Command             Action
        ---------------------------------------------------------------------
        CLEAR GETS          Terminates READ without saving current GET
        BREAK               Terminates READ without saving current GET
        KEYBOARD Ctrl-W     Terminates READ and saves the current GET
        KEYBOARD Esc        Terminates READ without saving current GET
        ---------------------------------------------------------------------

 Examples

     .  This example uses SET KEY to invoke a procedure that presents
        a picklist of account identification numbers when the user presses F2
        while entering data into the account identification field:

        #include   "Inkey.ch"
        //
        SET KEY K_F2 TO ScrollAccounts
        USE Accounts NEW
        USE Invoices NEW
        @ 10, 10 GET Invoices->Id
        READ
        RETURN

        PROCEDURE ScrollAccounts( cProc, nLine, cVar )
           IF cVar = "ID"
              SAVE SCREEN
              Accounts->(DBEDIT(10, 10, 18, 40, {"Company"}))
              KEYBOARD CHR(K_CTRL_Y) + Accounts->Id + ;
                       CHR(K_HOME)
              RESTORE SCREEN
           ELSE
              TONE(100, 2)
           ENDIF
           RETURN

 Files   Library is CLIPPER.LIB, header file is Inkey.ch.