**** If you have used a prior version of JKEY, read the JKEY.NEW file,
**** which outlines what has changed since the prior versions.

**********************************************************************
**** jKey Version 1.06 ****
**********************************************************************

One of the drawbacks of using BROWSE for pick-lists is that
incremental searching is not available. There are ways of doing this
with FoxPro code, either with many many ON KEY LABEL commands, or with
the incremental search a-la George F. Goley IV, published a while back in the Databased Advisor.

jKey.PLB is a routine written in C, which interfaces to FoxPro through
the SET LIBRARY TO command, and makes it very easy to do
incremental searches with BROWSE. Esencially jKey intercepts all
keystrokes, appends them to any previous keys, and SEEKS the result.
If no keyboard activity is detected in _DBLCLICK seconds, the buffer
is reset. This is consistant with FoxPro's handeling of incremental
searches.

The _DBLCLICK delay can be displayed by entering the command
? _DBLCLICK
from the command window. It can be chanced with the command
_DBLCLICK = x.x
Where x.x = the number of seconds, up to 5. Its default is .49
seconds.

CTRL-Y clears jKey's buffer.

If SET NEAR is ON, jKey will perform soft-seeks.

If SET BELL is ON, jKey will beep when keys do not result in a
successfull seek.

If SET TALK is ON WHEN JKEYINIT() is called, a window appears in
the upper right section of the screen, which displays the JKEY
search string. An optional "talk prefix" parameter can be included
which will also be displayed in the window. Alternatley, by specifying
an asterics (*) for the "talk prefix" will cause jKey to use the
current WONTOP() window for its display.

VIA a fourth optional parameter, JKEY can be told to only be active
while a particular window is on top. This is usefull of the BROWSE
is not a stand-alone popup. More on this later...

**********************************************************************
**** JKEYINIT() ****
**********************************************************************

The syntax for it is:

SET LIBRARY TO JKEY
...
...
* when you are ready to use it
SET ORDER/INDEX TO WHATEVER
=JKEYINIT([ [, [, [,Prim_Window]]]])
l_oldSysm = set("sysm")
set sysmenu off
BROWSE
set sysmenu &l_oldSysm.
=jKeyCanc() && or SET LIBRARY TO

In english:

1 - First you need to SET LIBRARY TO JKEY (this can be done any time,
either just before you use it to save memory, or on program
startup, to avoid delays during the application, or complications
with other loaded libraries.)

2 - SET ORDER TO the index key that will be used for searching.

3 - Call the JKEYINIT function. This function starts jKey
running. After this routine has been called, most keypresses
will result in a SEEK being performed on the currently selected
database, which will update the browse window accordingly.

4 - Issue the BROWSE command

5 - Call the jKeyCanc function to stop the routine from running. If
the BROWSE is exited with the [Esc], [Ctrl-Q], or [Crtl-W] key
sequences the routine will be automatically canceled, but if is
is closed with the mouse, the routine will still be active.
Because of this, always place the =jKeyCanc() right after the
browse.

Alternatley you can SET LIBRARY TO, which will remove the .PLB
from memory altogether.

jKeyInit takes four optional paramaters.

The first must be a U, L, or A:

U - Converts all letters to upper case before SEEKing.
L - Converts all letters to lower case before SEEKing.
A - Does not perform any conversion. This is the default, if
no parameters are supplied.
"" (blank) - Same as 'A'

The second parameter is a 'prefix' which can be attached to the seek.
This is useful where the first part of the index key is not known by
the user (i.e. a foreign key). It can be any CHARACTER string.


The third parameter is a "prefix" which will appear in the TALK
window. If the third parameter is an asterics (*), then jKey will
use the current WONTOP() window, instead of its own TALK WINDOW.
If this parameter is ommitted, or blank (""), and TALK is set OFF,
then jKey will not display status.

A fourth optional parameter specifies the name of the BROWSE window
JKEY will be used with. If this is specified, and another window
is made active while JKEY is active (via CTRL-F1, or mouse), JKEY will
be disabled. When the specified window is made active, JKEY will
re-enable itself.

Example:

set libr to jKey
use OS_PAT
SET ORDER TO PATLAST && key is pt_Resp + upper(pt_last)
&& pt_Resp can either be P, or R

set talk on
=jKeyInit("U", "P", "Search string: ") && search for records
&& where pt_Resp = 'P'
&& converting letters
&& to upper case.
set talk off
l_oldsysm = set("sysm")
set sysmenu off
BROWSE field pt_Last key 'P' title "Names"
set sysm to &l_oldsysm.
=jKeyCanc()

**********************************************************************
**** JKEYCANC() ****
**********************************************************************
The JKEYCANC() function disables jKey. It is documented in the above
section.

**********************************************************************
**** JKEYCLOSE() ****
**********************************************************************
Not callable from FoxPro. This function is executed when JKEYCANC() is
called, or when the .PLB is removed from memory.

**********************************************************************
**** JKEYFOUND() ****
**********************************************************************
JKEYFOUND() returns a logical value. If the last key pressed while
jKey was active, jKeyFound() will return a .T., otherwise it will return
a .F.

Example:
if jKeyFound()
wait window "Congradulations!"
else
wait window "Too bad you didn't find one."
endif

**********************************************************************
**** JKEYABOUT() ****
**********************************************************************
JKEYABOUT() displays version information about jKey.

Example:
=jKeyAbout()

**********************************************************************
**** INTERNATIONAL KEYBOARD SUPPORT ****
**********************************************************************
To address european concerns with the upper and lower
case conversion, JKEY has been modified to look for a
"conversion table" when it is run. The conversion table
is in the form of an array called _JKEYINTER, which should
be defined with 1 row for each translation, two columns for
each row. The first column is the lower case ascii code, the
second the upper case code. For example, the upper case
equivalent of chr(132) is chr(142). The array would be:

decl _jKeyInter[1, 2]
_jKeyInter[1, 1] = 132
_jKeyInter[1, 2] = 142.

The file INTER.MEM is included with JKEY - it contains the
translations that I am currently aware of.

**********************************************************************
**** EXAMPLES ****
**********************************************************************
The program JKEYSAMP.PRG included with jKey shows several examples
of jKey calls. It makes use of the FOXHELP.DBF file. If you have not
installed the HELP file, you can not run this program.

**********************************************************************
**** MISCELENEOUS INFORMATION ****
**********************************************************************
Some other things,

1 - Since there is currently no way for the API to know when the
system menu is active, I can not program for it. Therefore
SET SYSMENU OFF before calling JKEY. If the user gets into
the system menu while JKEY is active, things could get confusing!

2 - jKey has been tested to the best of my ability. Defects may
remain. If you find any, please contact me immediatly, and
I will do my best to correct jKey as quickly as possible.

3 - (The obligitory legal stuff):
jKey goes to the public as is, no warranties are expressed or
otherwise are made. No liability is held by the author
for data damage or lost resulting from the use of jKey.

4 - jKey.PLB takes slightly over 9,100 bytes of ram, when loaded.

5 - The idea for this routine origionally came from Tom Rettig's API
presentation in the 1990 (?) Developers Conference.

-----------------------------------------------------------------------
6 - jKey is shareware - feel free to use it in your applications.
If you find it useful, a contribution of any size would
be greatly appreciated. A Contribution of $30, or more will
register you as a jKey user, and will assure you that future
updates of jKey will be automatically sent your way.


Check or money order to: Joe Gotthelf
41 Willowbrook Rd
Broomall PA 19008-1749

7 - I can be contacted at the above address, or :

Joe Gotthelf - CIS ID : 74017,3670