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

Function:    KEYINPUT()

Purpose:     Get keyboard input, optionally echoing dots to the screen

Syntax:      KEYINPUT( length, upper_case, echo_chars, string )

Arguments:   length      - Optional numeric value specifying the maximum
                           length of the string that may be entered (and
                           returned by KEYINPUT).  If omitted or an
                           invalid parameter is passed, the default length
                           will be 80 characters.

             upper_case  - Optional logical value indicating if all
                           characters that are typed will be forced to
                           upper case.  If omitted or an invalid parameter
                           is passed, the default is false, characters
                           will be returned as entered.

             echo_chars  - Optional logical value indicating if typed
                           characters will appear on the screen.  If this
                           value is false, dots will echo on screen.  If
                           omitted or an invalid parameter is passed, the
                           default is true, characters will echo on screen
                           as entered.

             string      - Optional starting character string for key
                           input.  If omitted or an invalid parameter is
                           passed, KEYINPUT() starts with a null (empty)
                           string.

Returns:     The character string typed in, or a null string ("") if the
             Escape key was pressed.

Description: KEYINPUT() is a screen function used for accepting direct
             keyboard input from the user while giving the programmer
             control over each key press.  One such use is for direct dots
             onto the screen instead of the characters typed.  This is
             most often used during password entry.

Notes:       There is no built in way of allowing key input while echoing
             dots on the screen to prevent on-lookers from seeing what is
             being entered.  SETting COLOR TO X will blank out the screen
             but then you cannot see how many characters have been
             entered.  We may want to see dots echo (as most BBS' do) so
             we can tell how many characters we have entered.  With
             KEYINPUT() you can easily do this, while also determining the
             maximum length of the input string, whether or not it is to
             be all upper case, and whether or not to echo the actual
             characters on the screen, or just dots.

             KEYINPUT() starts accepting character input at the current
             cursor location on the screen and terminates when either the
             maximum character count has been reached or ENTER or ESCAPE
             is pressed.

             If <length> is greater than the remaining width of the
             screen, KEYINPUT() will wrap to the next line.

Example:     *-- get the user's password, keep it less than or equal to 30
             *-- characters, make upper case, and echo dots on screen
             @ 5,0 SAY "Enter your password: "
             password = KEYINPUT( 30, .T., .F.  )

Source:      RL_KEYIN.PRG

See also:    BOXASK(), GETFILE()