Click above to get retro games delivered to your door ever month!

Function:    GETKEY()

Purpose:     Function to replace INKEY() to allow internal customization

Syntax:      GETKEY( timeout )

Arguments:   timeout     - REQUIRED numeric value which is the number of
                           seconds to wait for a keypress, as in INKEY().

Returns:     The INKEY() value of the key pressed.

Description: GETKEY() is a character function which is used as a
             replacement for INKEY() in all RLIB functions that accept
             INKEY() input.  It can otherwise be referred to as a "stub"
             function which lets the programmer create their own
             customized GETKEY() to replace the keyboard wait routines in
             RLIB functions.  One such use is to trap the F1 key (INKEY()
             = 28) within GETKEY() in order to extend the calling of HELP
             routines from within RLIB functions.  This is because INKEY()
             is not considered a "wait" state and help is not called when
             F1 is pressed at an INKEY() state.  By installing the example
             function below, you can have both help and INKEY().

Notes:       All of the RLIB functions that solicit keyboard input use the
             RLIB GETKEY() function instead of INKEY().  This enables you
             to provide your own "hook" into the internals of RLIB
             functions.  By creating your own customized GETKEY() function
             and including it in your application, you can trap keystrokes
             and act on them before they even get to the RLIB function.
             Take a look at the GETKEY() function in the Message Reader
             demo program source code to see how GETKEY() expands the
             capabilities of the RLIB PICKREC() function.

             A sample program KEYBOARD.PRG is provided with the 5.01
             version of Clipper that illustrates the same concept of
             "stubbing out" the INKEY() function.

             WARNING: NO ARGUMENT CHECKING IS PERFORMED IN GETKEY()!!!.
             You MUST pass the <timeout> parameter.  This was done in the
             interest of speed since a parameter will always be used.  If
             someone is stomping on the down arrow key in PICKREC(),
             parameter checking on every call to this function would slow
             it down needlessly.  To add parameter checking, include the
             sample GETKEY() function below.

             Usually, the internal HELP routine receives three parameters;
             the calling procedure name, line number, and input variable.
             Any help called from this function will have GETKEY as the
             calling procedure.

Example:     *-- sample customized GETKEY() that traps the F1 Help key
             FUNCTION GetKey
             PARAMETER timeout
             PRIVATE ikey

             *-- add this if you want parameter checking for safety.
             timeout = IF( TYPE("timeout") = "N", timeout, 0 )

             DO WHILE .T.
                ikey = INKEY(timeout)
                IF ikey != 28
                   EXIT
                ENDIF
                DO Help WITH PROCNAME(), PROCLINE(), READVAR()
             ENDDO
             RETURN (ikey)

Source:      RL_GETKE.PRG

See also:    KEYINPUT(), PICKREC()