TRAPSHIFT()
 Calls a procedure that depends on switching keys
------------------------------------------------------------------------------
 Syntax

     TRAPSHIFT(<cProcedure>, <nBitMap>) --> cOldProcedure

 Arguments

     <cProcedure>  Designates the procedure name that is called when the
     specified shift keys are selected.

     <nBitMap>  Designates the bit values that allow you to specify which
     of the shift keys should call the procedure.  The description section
     below has a table of valid values.

     ()  If you call the function without parameters, you uninstall a
     previously selected function that monitored the switching keys.

 Returns

     The function returns the name of the previously set trap procedure.  If
     no trap was set, TRAPINPUT() returns a null string.

 Description

     This function makes it possible for all the shift keys, like Shift,
     Ctrl, Alt, Num-Lock etc., to trigger a procedure call.  If the system
     has the European extended (MF-2) keyboard available, which can be
     determined by using the KBDTYPE() function, then additional differences
     like left and right Ctrl keys must be taken into account.  The key scan
     codes and their assigned bits must be added to determine the value for
     the <nBitMap> parameter.  The following code applies:

     Table 2-5: Coding the Switching Keys
     ------------------------------------------------------------------------
     Bit     Key
     ------------------------------------------------------------------------
     1       Right shift at the instant actuated
     2       Left shift at the instant actuated
     3       Ctrl at the instant actuated (left or right)
     4       Alt at the instant actuated (Alt - Shift/Alt)
     5       Scroll-Lock ON/OFF
     6       Num-Lock ON/OFF
     7       Caps-Lock ON/OFF
     8       Insert ON/OFF
     9       Ctrl left at the instant actuated
     10      Alt left at the instant actuated
     11      Ctrl right at the instant actuated
     12      Right Alt (not valid for US keyboards)
     13      Scroll Lock at the instant actuated
     14      Num-Lock at the instant actuated
     15      Caps-Lock at the instant actuated
     16      Alt Print Scrn at the instant actuated
     ------------------------------------------------------------------------

     The Procedure Call
     If the selected switching key or keys are actuated, then the specified
     procedure is called.  The call is always passed as a numeric parameter
     and the status of all the switching keys at the time of the call.  The
     coding of the passed value corresponds to the table above.

     Using this function will not reproduce any CA-Clipper key trap.  Each
     time that CA-Clipper queries the keyboard, the switching keys are
     checked, and if required, the procedure is called directly from the
     driver.  In this way, these traps are always functional.

     Important!  In contrast to CA-Clipper key traps, these internal
     input commands do not have the option to ignore the interruption because
     no internal input routine is reentrant.  You cannot, under any
     circumstances, use the same input command in the called procedure.  This
     applies the GET/READ, PROMPT, ACCEPT, and any similar input
     instructions.  You can easily use INPUTMODE(.T.) to determine which
     input command is currently active when you call a procedure.

 Notes

     .  In contrast to CA-Clipper KEY TRAPS, recursions are
        automatically avoided.

     .  The parameter passed to the trap must be passed in every case,
        even when it is not needed.

     .  If a designated procedure does not exist, then the function
        uninstalls itself and does not produce a runtime error.  If a warning
        regarding a missing procedure is required during linking, use the
        EXTERNAL <procedure> statement.

 Example

     In this example, the Trap_Alt procedure is called as soon as the Alt key
     is actuated.  It is not in any way necessary for a GET/READ mask to be
     active for this example.   This is only intended to be an example of an
     application.

     The trap procedure waits in a loop for as long as you hold the Alt key,
     or until an additional combination key that delivers an INKEY code is
     actuated.  Pressing the Alt key displays an additional help list from
     which you can select the program option.  In this case, Alt-M appends
     the text "Yours Sincerely" to the keyboard buffer.

     CLEAR

     TRAPSHIFT("Trap_ALT", 8)

     cVar1 := SPACE(50)
     cVar2 := SPACE(50)

     @ 10, 20 GET cVar1
     @ 11, 20 GET cVar2
     READ

     TRAPSHIFT()

     RETURN

     PROCEDURE Trap_ALT(nStatus)

        @ MAXROW(), 0 SAY "........Help Line........"

        nInVar := 0

        DO WHILE NUMAND(KBDSTAT(), 8) = 8 .AND. nInVar = 8
           nInVar := INKEY()
        ENDDO

        DO CASE
        CASE nInVar = 306                  // ALT-M
           KEYSEND(CHARMIX("Yours Sincerely", CHR(0), .T.)
        ENDCASE

        @ MAXROW(), 0

        RETURN