****************************************************************************
*                                                                          *
* Author:      R. Scott Mackay (CompuServe ID: 76236,2355)                 *
*              Computer Software Solutions                                 *
*                                                                          *
* Program:     KeyMask Library - Version 1.00 May 21, 1994                 *
*                                                                          *
* Description: KeyMask library traps masks keystrokes by replacing the     *
*              keystrokes with *s while storing the original keystroke     *
*              values to a string.  This library is most commonly used for *
*              password entry.  The main advantage that this library has   *
*              over an INKEY() loop is that a GET field is used for input, *
*              preserving the native user interaction (including mouse     *
*              navigation).                                                *
*                                                                          *
****************************************************************************
IMPORTANT:  This software is for FoxPro 2.5 (and above) only.

THIS LIBRARY IS SUBMITTED AS PUBLIC DOMAIN BY THE AUTHOR.  THIS PROGRAM IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED.
IN NO EVENT WILL THE AUTHOR BE LIABLE TO THE DEVELOPER/USER FOR ANY DAMAGES,
INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THIS
PRODUCT.

The functions in this library are:
     KMClear()     Clear keystroke string.
                     Use in SETUP code of screen, or in WHEN of KeyMask
                     field if more than 1 KeyMask field exists in the
                     current READ.
     KeyMask()     Initiate KeyMask for current field.
                     Call in WHEN event of fields to be masked.
     KMCancel()    Cancel keystroke masking.
                     Call in VALID event of fields to be masked.  Also
                     call in the screen's CLEANUP code since the READ can
                     be exited without the field's VALID event being
                     triggered.
     KMValue()     Return keystroke string.
                     Call in screen's CLEANUP code or other places as
                     needed to get the character string typed into
                     the KeyMask field.

These functions are explained in detail in the following section, which
has been formatted similar to the help screens in FoxPro so that it may
be included in the help database and be available on-line.  If it is
included in the FoxHelp database, it is recommended that the appropriate
carriage returns be removed so that when the help window is resized the
text will be reformatted so that it will be more readable.



ķ
            KMClear()            
Ķ
 External Library: KeyMask       
Ľ

KMClear()


KMClear resets the keystroke string
preparatory to the logon screen
being activated.

Return value - NONE
 

NOTE: This function is not a product of, or supported by Microsoft -
Please send questions and comments via CompuServe Mail ID#: 76236,2355.

This function is called from the add-on library 'KeyMask', so in
order to utilize this function, the library must be made available to
FoxPro by:  SET LIBRARY TO KEYMASK [ADDITIVE]  (It is assumed that the
library file is in the current directory or path -- see SET LIBRARY in the
FoxPro manuals for more information).

KMClear resets the keystroke string.  KMClear should be called once in the
setup of the screen, or other times if appropriate.  If KMClear is called
during the read, it is the developers responsibility to also clear the
corresponding field so that the keystroke string and the field remain
in sync.




See Also:  KeyMask(), KMCancel(), KMValue()





ķ
            KeyMask()            
Ķ
 External Library: KeyMask       
Ľ

KeyMask()


KeyMask initiates keystroke
masking.

Return value - NONE
 

NOTE: This function is not a product of, or supported by Microsoft -
Please send questions and comments via CompuServe Mail ID#: 76236,2355.

This function is called from the add-on library 'KeyMask', so in
order to utilize this function, the library must be made available to
FoxPro by:  SET LIBRARY TO KEYMASK [ADDITIVE]  (It is assumed that the
library file is in the current directory or path -- see SET LIBRARY in the
FoxPro manuals for more information).

KeyMask initiates keystroke masking and should be called in the WHEN event
of fields participating in the keystroke masking.

NOTES:  Due to limitations in the FoxPro API, and some limitations in
        the KeyMask library, it is important to keep the following in
        mind to ensure that the KeyMask routines function properly.
        
        - In Windows (and MAC when available) it is important that the
          window font of the window containing the GETs is set to the
          FoxFont 9 point font (This does not mean that the SAY/GETS have
          to use FoxFont, only that the window coordinates are based on the
          FoxFont 9 point font.  This is so that the KeyMask library can be
          compiled and used in DOS, Windows and MAC without having to
          maintain multiple sets of source code.

        - A KeyMask field variable needs to be initialized with the #
          of spaces that match the visible screen length (i.e. no scrolling
          fields and no fields smaller than the display length).
          
        - If more than 1 field in a READ will be using the KEYMASK,
          KMClear() should be called in the WHEN event prior to calling
          KeyMask(), and the variable should be reinitialized with spaces,
          and the GET redisplayed with SHOW GET m.FieldName.  In future
          versions I plan on allowing KeyMask() to be passed a string that
          represents the current state of a GET field assuming that more
          than 1 GET field in the same READ will be using the KeyMask
          functions.
          
        - The mouse may be used to navigate between fields and buttons.
          But the mouse is not available for editing while on a field
          using KeyMask().  When clicking on a field that has KeyMask()
          in the WHEN event, the entire field is selected, and the mouse
          clicks on the same row (and 1 row above and 1 row below since
          a click can be between rows in Windows/MAC) of the current
          KeyMask field are "eaten" by the KeyMask event handler to prevent
          actions that can not be adequately tracked by the FoxPro API.
          This indicates that if there are other fields on the same row
          as the currently active KeyMask field, the mouse will not work
          to activate them.  The mouse can still be used to select other
          fields or buttons while KeyMask is active.
        
        - The "Select All" menu bar defined in the foxpro menu MUST be
          defined in the menu that is active when the KeyMask functions
          are used.  The "Select All" menu bar can not be disabled, and
          must be defined with the shortcut of "CTRL+A".  If this does
          not fit with your current development scheme, simply push the
          menu, define the menu bar, run the logon program, then pop the
          menu.  If there is a big enough demand, I will add more
          functionality to the KeyMask library so that an "Select All"
          menu bar will be dynamically created if there is not already one,
          and then released when the KeyMask functions are completed.




See Also:  KMClear(), KMCancel(), KMValue()





ķ
            KMCancel()           
Ķ
 External Library: KeyMask       
Ľ

KMCancel()


KMCancel cancels keystroke masking.

Return value - NONE
 

NOTE: This function is not a product of, or supported by Microsoft -
Please send questions and comments via CompuServe Mail ID#: 76236,2355.

This function is called from the add-on library 'KeyMask', so in
order to utilize this function, the library must be made available to
FoxPro by:  SET LIBRARY TO KEYMASK [ADDITIVE]  (It is assumed that the
library file is in the current directory or path -- see SET LIBRARY in the
FoxPro manuals for more information).

KMCancel cancels keystroke masking initiated by KeyMask().  KMCancel should
be called in the VALID event of a field participating in the KeyMask.
KMCancel should also be called in the CLEANUP code of a screen since a
read can be terminated without the VALID event of the current object getting
triggered.

NOTE:  KMCancel does note clear the current keystroke string.  Use KMClear()
       when it is necessary to clear the keystroke string




See Also:  KMClear() KeyMask(), KMValue()





ķ
             KMValue()           
Ķ
 External Library: KeyMask       
Ľ

KMValue()


KMValue returns the current
keystroke string which represents
the actual characters typed that
were masked out.

Return value - Character String
 

NOTE: This function is not a product of, or supported by Microsoft -
Please send questions and comments via CompuServe Mail ID#: 76236,2355.

This function is called from the add-on library 'KeyMask', so in
order to utilize this function, the library must be made available to
FoxPro by:  SET LIBRARY TO KEYMASK [ADDITIVE]  (It is assumed that the
library file is in the current directory or path -- see SET LIBRARY in the
FoxPro manuals for more information).

KMValue returns the current keystroke string representing the actual
characters typed that were masked out.  KMValue can be called at any time, 
but normally would be called in the screen's cleanup to store or return
the value to a calling program.




See Also:  KMClear() KeyMask(), KMCancel()


