Have you ended up with a project using jKey? Don't have any documentation to go with it? Well, here it is…

jKey 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 BROWSEs and GRIDs. Essentially jKey works behind the scene & watches all keystrokes, appending them to previous keys, and SEEKing the result; updating the record pointer and display accordingly.

NOTE: For those who learn by looking at samples, check out JKEYSAMP.PRG

A jKey Overview

As stated above, jKey allows the easy programming of fast incremental searching through BROWSEs & Grids.  It does this by taking advantage of a current FoxPro index order. When jKey is active it intercepts all character keystrokes, and appends them to the previous, then does a SEEK, and updated the BROWSE window. If no characters are keyed in a set number of times (via _DBLCLICK, or _JDBLCLICK, see jKey PERSONALITY below), then the jKey buffer is reset. The default value is ½ second, so if no characters are typed in half a second, the search effectively stars over. This "resetting" feature can be disabled. As with other FoxPro input fields, CTRL-Y will clear the buffer.

Before you can use jKey, it must be loaded into memory. This is done with the FoxPro command

1. SET LIBRARY TO jKey
   This can be done at any time, either on program startup, or when you are ready to use jKey. jKey uses only a very small amount of RAM, so unless you are stuck in a time-warp and are working with a 286 with 2mb of RAM this won't cause your application any problems; if you are, simply remove jKey from RAM with the "SET LIBRARY TO" command after the browse closes.
   
2. SET ORDER TO the index key that will be used for searching.
   
3. Call the jKeyInit() function. This function starts jKey running. The syntax for jKeyInit() is detailed below. After this routine has been called, most key presses will result in a SEEK being performed on the currently selected database, which will update the browse window accordingly. jKey takes its personality from parameters sent to jKeyInit(), and the FoxPro environment.
   
4. Issue the BROWSE command NOTE: In DOS versions of FoxPro Set Sysmenu Off around the BROWSE. There is now way for jKey to know when the system menu is active under DOS, so things can get messy if it left active.
   
5. Call the jKeyCanc() function to stop the routine from running. If you don't do this, jKey may remain active, eating keystrokes. NOTE: If the browse is exited with [Esc], [CTRL-Q], or [CTRL-W] jKey will be turned off, however, if the BROWSE is exited with the mouse, jKey will not, so always call this function.
   
6. When you are done using jKey, you can remove it from memory. This is not needed, but if you wish to, there are three ways to do it.
   
   A - SET LIBRARY TO, which will remove ALL API libraries from RAM.
   B - RELEASE LIBRARY jKey, which just removes jKey
   C - QUIT FoxPro!
   

jKey PERSONALITY

jKey takes its personality from parameters passed to the jKeyInit() function, and from the FoxPro environment at the time jKeyInit() is called. Here is a rundown on the how the FoxPro environment affects the workings of jKey. Some other jKey personality traits can be set with the JKEYPERS() FUNCTION.

• SET NEAR
  If Set Near is On, then jKey will perform SOFT-SEEKS.
• SET TALK
  If Set Talk is On, jKey will display keying status whether a TALK PREFIX is specified or not. If Set Talk is Off, and a TALK PREFIX IS specified, then status is displayed.
• SET BELL
  If Set Bell is On then a BELL sound is produced when a keystroke produces an unsuccessful SEEK.
• FONTS
  FoxPro/Windows. If a user defined window is used for the status display, jKey will respect whatever FONT the window is defined with.
• _JKEYINTER
  International character support; see International Considerations below for more information.
• _JEXITKEY
  If the variable _JEXITKEY exists, it defines the key which will terminate jKey. I.E. if _JEXITKEY = 13, then the ENTER key will terminate jKey. When jKey intercepts the _JEXITKEY character, it puts a [CTRL-W] into the keyboard buffer, effectively terminating an active BROWSE.
  
  NOTE: This does not work with FoxPro 2.0 (X)! This appears to be due to a bug in FoxPro 2.0(X)! Do NOT set this variable in 2.0 (X) programs - it will terminate jKey, but will NOT close the BROWSE, allowing users to become real confused, and possibly change data in the BROWSE!!!!
• _DBLCLICK
  _DBLCLICK is a FoxPro System Memory Variable which defines how long FoxPro waits to determine double mouse clicks. It also controls the Incremental search time on POPUPS and HELP. It also controls jKey's time-out. If no keys are pressed in _DBLCLICK seconds, jKey's input buffer is cleared.
  To see the value of _DBLCLICK just issue the FoxPro command ? _DBLCLICK && Default is .49/.50 seconds To change it, you can use the same syntax as with any variable, i.e.
  
  _DBLCLICK = 4
  
  The valid values are between .1 and 5 seconds.
• _JDBLCLICK
  If the variable _JDBLCLICK exits, it must be a NUMERIC type, and overrides the value of _DBLCLICK for jKey's use only. If _JDBLCLICK = -1, then the input buffer will never be cleared.

The jKey functions

jKeyInit()

jKeyInit() is the function which stars jKey in motion. When jKeyInit() is called, jKey starts intercepting keystrokes, and performing SEEKs. jKeyInit() takes four parameters:

=jKeyInit([<case> [,<key prefix> [,<talk prefix>[,Prim_Window]]]])

<case>

This first parameter tells jKey how to read incoming characters. The following are valid values:

NOTE: See the section below on INTERNATIONAL CONSIDERATIONS for information on European character translations.

<key prefix>

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.

<talk prefix>

The third parameter is a "prefix" which will appear in a window.

If it is anything besides an asterisk, a window looking similar to a WAIT WINDOW appears. Keystrokes are shown in this window.

If the third parameter is an asterisk (*), then jKey will use the current WONTOP() window to display keystrokes, giving full control of how things are displayed, including position and FONT.

NOTE: WONTOP() is read at the time jKeyInit() is called. If this parameter is omitted, or blank (""), and TALK is set OFF, then jKey will not display keystrokes. If it is blank, and TALK is ON, then jKey will display the window and keystrokes.

<Prim_Window>

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.

Some examples of jKeyInit()

=jKeyInit("U")
Perform incremental searches, converting all incoming characters to upper case.

=jKeyInit("U", "SET ")
Perform searches, converting characters to upper case, and appending them to the string "SET ".

=jKeyInit("U", "SET ", "Find this: ")
Perform searches, converting characters to upper case, and appending them to the string "SET ", while displaying a window showing what

keys are typed, with the phrase "Find this: " displayed.

=jKeyInit("U", "", "Find this: ")
Perform searches, converting characters to upper case, while displaying a window showing what keys are typed, with the phrase "Find this: " displayed.

=jKeyInit("P", "", "*")
Perform searches, converting characters to PROPER case, while displaying incoming keystrokes in the WONTOP() window.

jKeyCanc()

The jKeyCanc() function disables jKey. When the BROWSE is exited jKeyCanc() should be called, or jKey will still be active.

jKeyClose()

Not callable from FoxPro. This function is executed when jKeyCanc() is called, or when the jKey library is removed from memory.

Ignore the fact that it exists.

jKeyFound()

jKeyFound() returns a logical value. jKeyFound() will return a .T., or a .F., depending on whether the last key pressed while jKey was active resulted in a successful seek, or not.

Example:

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

jKeySearch()

jKeySearch() returns the value of the last thing SEEKed for by jKey.

Example:

=jKeyInit("U", "", "Search for: ")
browse
=jKeyCanc() && turn jKey off
@ srows() - 1, 0
@ srows() - 1, 0 say "Last search: " + jKeySearch()

jKeySusp()

jKeySusp() suspends jKey's operation - but does not deactivate jKey. It is intended for use with jKeyGo().

Example:

on key label f2 xxxx=jKeySusp()
on key label f3 xxxx=jKeyGo()
=jKeyInit("U", "", "Search for: ")
brow window jbrowser title "[F2]=Suspend for data entry, [F3]=Resume"
on key label f2
on key label f3
=jKeyCanc() && turn jKey off

jKeyGo()

jKeyGo() resumes jKey's operation after it was suspended by a call to jKeySusp(). See the example for jKeySusp above.

jKeyAbout()

jKeyAbout() displays version information about jKey.

Example:

=jKeyAbout()

jKeyPers()

=jKeyPers('Type', [value]) Sets some jKey Personality Features

<type>

The values for type are:

INTERNATIONAL CONSIDERATIONS

To address European concerns with the upper and lower case conversion, jKey looks 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:

declare _jKeyInter[1, 2]
_jKeyInter[1, 1] = 132
_jKeyInter[1, 2] = 142

The file INTER.MEM is included with jKey - it contains the most commonly needed translations.

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 FoxPro style HELP file, you can not run this program.

The program JDBLCL20.PRG and JDBLCLK.PRG show how to have a DBL-CLICK terminate the jKey & Browse, effectively selecting a record.

JDBLCL20.PRG should be used with FoxPro 2.0 only, JDBLCLK.PRG contains the version which should be used with FoxPro 2.5, DOS and Windows. The difference between the two is the 2.5 version works intelligently in Windows, with any FONT.

MISCELLANEOUS INFORMATION

1. When working in DOS (time warp again), there is no way for jKey  to reliably know when the system menu is active, therefore it can not be accounted for. Therefore SET SYSMENU should be set to OFF before calling jKey from FoxPro/DOS. If the user gets into the system menu while jKey is active, things could get messy!
   
2. jKey has been tested to the best of my ability. As with any software, defects may remain. If you find any, please contact me immediately, and I will do my best to correct jKey as quickly as possible.
   
3. (The obligatory legal stuff):
   August Technologies, Inc., provides no warranties expressed, implied, or otherwise.  No liability is assumed, or held by the author for any consequences resulting from the use of jKey in any way.
   
4. The idea for this routine originally came from Tom Rettig's API presentation at the 1990 Developers Conference.  A great man who should always be remembered.