KEYBOARD/MOUSE

Function FKLABEL()

 FKLABEL(<nFunctionKey>) --> cKeyLabel

FKLABEL() is a compatibility function used to replicate the FKLABEL() function in dBASE III PLUS. As a general principle, the use of this function is not recommended and not needed in xClipper. The function keys are labeled Fn, where n ranges from one to 40 and corresponds directly to the FKLABEL() argument.

Function FKMAX()

 FKMAX() --> nFunctionKeys

FKMAX() is a compatibility function used to replicate the FKMAX() function in dBASE III PLUS. As a general principle, the use of this function is not recommended and not needed in xClipper. It simply returns a constant value of 40.

Function FT_MBUTPRS()

 FT_MBUTPRS( <nButton> [, @nButPrs [, @nX [, @nY] ] ] ) --> nButStatus

Retrieves the mouse button status and the position of the cursor when a button was last pressed.

 IF Empty( FT_MBUTPRS(1) )
 ? "No Item selected"
 ENDIF

Function FT_MBUTREL()

 FT_MBUTREL( nButton [, @nButRel [, @nX [, @nY] ] ]) --> nBStat

This function returns the release status of the mouse buttons and the coordinates of the last release.

 IF( FT_MBUTREL( 0 ) == 1 )
 ? "Left button released"
 ENDIF

Function FT_MCONOFF()

 FT_MCONOFF( <nTop>, <nLeft>, <nBottom>, <nRight> )

This function tells the mouse driver to hide the cursor if it is in the given region. The driver hides the cursor by decrementing the cursor flag. A call to FT_MSHOWCRS is required to turn the cursor back on. Calling FT_MSHOWCRS also disables this function.

See FT_MSHOWCRS for a discussion of the cursor display flag.

 FT_MCONOFF( 10, 10, 11, 20 )

Function FT_MCURSOR()

 FT_MCURSOR( [ <lState> ] ) --> lCursorState

This function works like most Clipper state functions. If no value is sent to FT_MCURSOR() it will return the state of the mouse cursor.

 IF !( FT_MCURSOR() )
 FT_MCURSOR( .T. )
 ENDIF

Function FT_MDBLCLK()

 FT_MDBLCLK( [ <nClick> [, <nButton> [, <nInterval> [, <nRow> [, <nCol>;
 [, <nTime> ] ] ] ] ] ] ) --> lIsDoubleClk

This is a mouse meta function that checks for the presence of a double click.

 IF FT_MISREGION( 10, 10, 11, 20 ) .AND.;
 FT_MDBLCLK(0,1,,FT_MGETX(),FT_MGETY())  && double click, right button
 && at current location with
 && default interval
 
 MnuItem1()
 ENDIF

Function FT_MDEFCRS()

 FT_MDEFCRS( <nCrsType>, <nScrMask>, <nCrsMask> ) --> NIL

In text mode the mouse cursor can either be a software generated or the actual hardware cursor. This routine allows one choose between them. The software cursor is the default and its effect on the character it covers is determined by the screen mask and the cursor mask. Both of these masks are 16 bit values (which in Clipper are passed as standard numerical values). The 16 bit masks are arranged in a manner identical to the way information is stored for each character cell on the screen. The low order 8 bits represent the actual character displayed while the high order bits represent the display atributes such as blinking, intensity and forground and background colors. The mask is represented in the diagram below:

Bit: |15 |14 12|11 |10 8|7 0| Function:|blink |background|intensity|foreground|character|

Blinking and high intensity are on when the bit is 1. The background and foreground indicate which colors are used for each. The software mouse cursor uses these two values by taking the mask from the screen cell it is on and performing a logical AND on each bit with the screen mask value. The result is then logically XOR'ed with the cursor mask value. Thus to keep the character the same but invert the foreground and background colors the following values would be used:

Bit: |15 |14 12|11 |10 8|7 0| Function:|blink |background|intensity|foreground|character| screen: | 0 | 111 | 0 | 111 |11111111 | =30719 cursor: | 0 | 111 | 0 | 111 |00000000 | =30464

The hardware cursor is the text cursor provided by the video board. One specifies the range of scan lines which are on using <nScrMask> and <nCrsMask>. The range of values is dependant upon the type of monitor. The first scan line is 0.

Function FT_MGETCOORD()

 FT_MGETPOS( @<nX>, @<nY> ) --> nButtonStatus

Loads cursor position into x and y coordinates passed by reference and returns the button status.

 LOCAL nX, nY
 LOCAL nButton := FT_MGETCOORD( @nX, @nY )
 ? "Mouse Row    :", nX
 ? "Mouse Column :", nY
 ? "Button Status:", nButton

Function FT_MGETPAGE()

 FT_MGETPAGE() --> <nPage>

This function gets the display page for the mouse cursor. The valid values of nPage is dependent upon the display mode. See FT_SETVPG() for changing the current video page

 nPage = FT_MGETPAGE( )  // Gets the mouse cursor display page

Function FT_MGETPOS()

 FT_MGETPOS( @<nX>, @<nY> ) --> nButtonStatus

Loads cursor position into x and y coordinates passed by reference and returns the button status. The coordinate system in text mode has eight virtual coordinates per character cell. Thus x=16 means that you are in the Row 2. The values returned by this routine when in text mode and with mouse driver versions 6 and above are multiples of 8. We have experience with drivers prior to that version

 LOCAL nX, nY
 LOCAL nButton := FT_MGETPOS( @nX, @nY )
 ? "Mouse Row    :", nX
 ? "Mouse Column :", nY
 ? "Button Status:", nButton

Function FT_MGETSENS()

 FT_MGETSENS( <@nHoriz>, <@nVert>, <@nDouble> ) --> NIL

This function returns the current values of the mouse movement sensitivity parameters. The first two arguments control the amount of movement necessary to move the cursor a given amount. The third argument determines the threshold above which the mouse moves at twice the normal speed. For further discussion of these values see FT_MSETSENS()

 FT_MGETSENS( @nHoriz, @nVert, @nDouble )

Function FT_MGETX()

 FT_MGETX() --> nRowPos

Retrieves mouse's row position in virtual screen coordinates. The values returned are multiples of 8 when in text mode and with at least Microsoft drivers 6 and above.

 ? FT_MGETX()

Function FT_MGETY()

 FT_MGETY() --> nColPos

Retrieves mouse's column position in virtual screen coordinates. The values returned are multiples of 8 when in text mode and with at least Microsoft drivers 6 and above.

 ? FT_MGETY()

Function FT_MHIDECRS()

 FT_MHIDECRS() --> NIL

Hides the mouse cursor. Make sure to turn the mouse cursor off when redrawing screens. The mouse cursor dutifully saves the screen under it, so if you draw over the mouse cursor it will create a "hole" in your screen when you move the mouse cursor.

Note: A call to FT_MHIDECRS() decrements a mouse driver variable which indicates whether the cursor is shown. The cursor is visible only when the variable = 0. Thus multiple calls to FT_MHIDECRS() require an equal number of calls to FT_MSHOWCRS() before the cursor will again be visible. Once the variable is 0 calls to FT_MSHOWCRS() does not increment the varaible above 0.

 FT_MHIDECRS()
 @ 10, 10 to 20, 20
 FT_MSHOWCRS()

Function FT_MINIT()

 FT_MINIT() --> lMouseStatus

Initializes the mouse drive, associated variables and returns mouse status. It checks to see if the mouse has been previously initialized and if so it does not reinitialize. The row and column limits of mouse movement is set to the maximum for the current video mode. Use FT_MSHOWCRS() to display the mouse cursor.

 IF .NOT. FT_MINIT()
 ? "No mouse driver is installed"
 ENDIF

Function FT_MINREGION()

 FT_MINREGION( <nT>, <nL>, <nB>, <nR> ) --> lInRegion

This function will check to see if the mouse cursor is within the confines of the specified region.

 IF FT_MINREGION( 10, 10, 11, 20 )
 nChoice := 1
 ENDIF

Function FT_MMICKEYS()

 FT_MMICKEYS( @<nX>, @<nY> ) --> NIL

<nX> and <nY> must be passed by reference to receive the mouse position in Mickeys.

 FT_MMICKEYS( @nX, @nY )
 ? nX
 ? nY

Function FT_MRESET()

 FT_MRESET() --> nMouseStatus

Resets the mouse driver and returns mouse status. Use FT_MSHOWCRS() to display the mouse cursor. The mouse is set to allow it to cover the complete screen (as defined by MAXCOL() and MAXROW()). This is necessary because at least some versions of the mouse drivers do not operate according to the documentation when confronted with a 43 or 50 line screen.

Normally, FT_MINIT() should be used to initialize the mouse since it will not reinitialize if already done.

 IF Empty( FT_MRESET() )
 ? "No mouse driver is installed"
 ENDIF

Function FT_MSETCOORD()

 FT_MSETPOS( <nX>, <nY> ) --> NIL

Positions mouse cursor on screen using text (normal row and column) coordinates.

 FT_MSETCOORD( 10, 20 )     // position mouse cursor at row 10, col 20
 // in text screen coordinates

Function FT_MSETPAGE()

 FT_MSETPAGE( <@nPage> ) --> NIL

This function sets the display page for the mouse cursor. The valid values of nPage is dependent upon the display mode. See FT_SETVPG() for changing the current video page

 FT_MSETPAGE( 1 )  // Sets the mouse cursor to page 1

Function FT_MSETPOS()

 FT_MSETPOS( <nX>, <nY> ) --> NIL

Positions mouse cursor on screen. The virtual coordinate system in text mode has eight virtual coordinates per character cell. Thus x=16 means that you are in the Row 2.

 FT_MSETPOS( 10, 20 )     // position mouse cursor at row 10, col 20
 // in virtual screen coordinates

Function FT_MSETSENS()

 FT_MSETSENS( <nHoriz>, <nVert>, <nDouble> ) --> NIL

This function allows one to control the mouse movement sensitivity. The first two arguments control the amount of movement necessary to move the cursor a given amount. The values are the percentage of full sensitivity and the default values after installing the mouse driver is 50 which represents approximately 3.2 inches of horizontal and 2 inches of vertical mouse movement to cover the entire screen. A value of 100 requires about 0.9 inches of horizontal mouse movement to cover the screen from one side to the other.

The third argument changes the threshold above which the mouse moves at twice the normal speed. The value is a percentage of full sensitivity with the default (50) providing doubling at 64 mickeys per second.

NOTE: These values are NOT restored after resetting the mouse driver/ hardware. A well behaved application should reset them to the original value upon exiting.

NOTE: The above description is counter to all of the documentation I have available. However, it does not work the way it is documented with Microsoft drivers versions 6.16, 6.24, 7.04 and 8.20. The above movement values are documented to be the number of mickeys per 8 pixels and the double speed value as the number mickeys per second required to double the speed. Each of these values should range from 1 to 32K but the driver forces a maximum of 100. Also the documentation states that resetting the mouse will reset these values. This is not the case.

 FT_MSETSENS( 75,75,50 )     // a little less mouse movement necessary.

Function FT_MSHOWCRS()

 FT_MSHOWCRS() --> NIL

Displays the mouse cursor. Make sure to turn the mouse cursor off when redrawing screens. The mouse cursor dutifully saves the screen under it, so if you draw over the mouse cursor it will create a "hole" in your screen when you move the mouse cursor.

Note: A call to FT_MHIDECRS() decrements a mouse driver variable which indicates whether the cursor is shown. The cursor is visible only when the variable = 0. Thus multiple calls to FT_MHIDECRS() require an equal number of calls to FT_MSHOWCRS() before the cursor will again be visible. Once the variable is 0 calls to FT_MSHOWCRS() does not increment the variable above 0.

 IF Empty( FT_MRESET() )
 FT_MSHOWCRS()
 ENDIF

Function FT_MVERSION()

 FT_MVERSION( <@nMinor>, <@nType>, <@nIRQ>  ) --> <nMajor>

This function returns the current values of the mouse driver version number and type. The major version would be 6 and the minor version would be 10 if the driver were version 6.10. The mouse type and IRQ numbers are also returned.

NOTE: It appears that the values reported when one starts the mouse driver actually have the minor version in hexadecimal! Thus on bootup my screen showed 6.24 but this routine returned 30 for the minor version number!

 nMajor=FT_MVERSION( @nMinor )
 IF (nMajor+nMinor/100)<7.2
 ? "Sorry mouse driver version too old"
 RETURN
 ENDIF

Function FT_MXLIMIT()

 FT_MXLIMIT( <nX1>, <nX2> ) --> NIL

Set maximum vertical bounds of mouse using virtual screen coordinates.

 FT_MXLIMIT( 10, 20 )

Function FT_MYLIMIT()

 FT_MYLIMIT( <nY1>, <nY2> ) --> NIL

Set maximum horizontal bounds of mouse using virtual screen coordinates.

 FT_MYLIMIT( 10, 20 )

Function FT_SCANCODE()

 FT_SCANCODE() --> cCode

FT_SCANCODE() enables you to distinguish the different scancodes of similar keys (such as Grey minus versus regular minus), thus increasing the number of keys your input routine can recognize.

It works like INKEY(), in that it waits for a key to be pressed. The scan code consists of two bytes, which are returned as a two-character string.

For example, calling FT_SCANCODE() and pressing the Grey-minus key will return a two character string:

CHR(45) + CHR(74)

LASTKEY() is not updated by FT_SCANCODE(), so don't try to test LASTKEY() to see what was pressed during an FT_SCANCODE() call. Simply assign the return value to a variable and test that (see the test driver below).

* This was adapted from a short C routine posted by John Kaster on NANFORUM. It was written in Clipper to help demonstrate the FT_INT86 function of the Nanforum Toolkit.

This program requires FT_INT86().

 cKey := FT_SCANCODE()
 
 [grey-] returns:  CHR(45) + CHR(74)
 [-]     returns:  CHR(45) + CHR(12)
 [grey+] returns:  CHR(43) + CHR(78)
 [+]     returns:  CHR(43) + CHR(13)

Function INKEY()

 INKEY([<nSeconds>] [,<nEventMask>]) --> nInkeyCode

INKEY() is a keyboard function that extracts the next key pending in the keyboard buffer or the next mouse event and returns a value representing the appropriate event. The value is also saved internally and can be accessed using LASTKEY(). If the <nSeconds> argument is specified and there are no pending keys in the buffer, program execution pauses until a key appears in the keyboard buffer, or an appropriate mouse event occurs, or <nSeconds> has elapsed. The time INKEY() waits is based on the operating system clock and is not related to the microprocessor speed. If <nSeconds> is zero, program execution pauses until a key is pressed or an unmasked mouse event occurs. Note that INKEY() is not a wait state and, therefore, SET KEYs are not active.

INKEY() is similar to the NEXTKEY() function. Unlike INKEY(), however, NEXTKEY() reads, but does not extract the key or mouse event. This is useful when you need to test for a key or mouse event without processing it.

INKEY() is the basic primitive of the xClipper system for fetching keys and mouse events. It is used for polling the keyboard, polling the mouse, or pausing program execution. As an example, you can use INKEY() to terminate commands with a record scope such as LIST, LABEL FORM, and REPORT FORM by including it in a WHILE condition.

Function LASTKEY()

 LASTKEY() --> nInkeyCode

LASTKEY() is a function that reports the INKEY() value of the last key fetched from the keyboard buffer by the INKEY() function, or the next mouse event, or a wait state such as ACCEPT, INPUT, READ, WAIT, ACHOICE(), DBEDIT(), or MEMOEDIT(). The time LASTKEY() waits is based on the operating system clock and is not related to the microprocessor speed. LASTKEY() retains its current value until another key is fetched from the keyboard buffer.

LASTKEY() has a number of uses which include:

Determining the key that terminates a READ

Determining the key that exits the current Get object within a user-defined function, invoked by a VALID clause

Identifying an exception key in the user function of ACHOICE(), DBEDIT(), or MEMOEDIT()

LASTKEY() is also used with UPDATED() to determine if any Get object's buffer was changed during a READ.

LASTKEY() is related to NEXTKEY() and READKEY(). NEXTKEY() reads the current key pending in the keyboard buffer without removing it. Use NEXTKEY() instead of INKEY() when polling for a key.

For a complete list of INKEY() codes and Inkey.ch constants for each key, refer to the Error Messages and Appendices Guide.

  This example illustrates a typical application of LASTKEY() to
 test the key that exits a READ.  If the user exits with any key other
 than Esc and a GET was changed, the specified database file is
 updated:
 
 #include "Inkey.ch"
 //
 USE Customer NEW
 MEMVAR->balance = Customer->Balance
 @ 10, 10 SAY "Current Balance" GET MEMVAR->balance
 READ
 //
 IF (LASTKEY() != K_ESC) .AND. UPDATED()
 REPLACE Customer->Balance WITH MEMVAR->balance
 
 ENDIF
 
 

Function MCOL()

 MCOL() --> nCurrentMouseColumn

Function MDBLCLK()

 MDBLCLK([<nNewSpeed>]) --> nSpeed

Function MHIDE()

 MHIDE() --> NIL

MHIDE() hides the mouse pointer. This function should be used together with MSHOW() when updating the screen. It is important to hide the mouse pointer before changing the screen display and then show it again after the change.

Note: The MSETCURSOR() function should be used in place of MSHOW() and MHIDE(). It is kept here for compatibility.

 This example uses the mouse pointer:
 
 MHIDE()
 @ 10, 20 say "Hi there, folks!!!"
 MSHOW()
 
 You can automate calls to MHIDE()/MSHOW() by modifying parts
 of your header files (*.ch).  For example:
 
 #command @ <row>, <col> SAY <xpr>;[PICTURE <pic>];
 [COLOR <color>];
 => DEVPOS(<row>, <col>);
 DEVOUTPict(<xpr>, <pic> [, <color>])
 // Can be changed to
 #command @ <row>, <col> SAY <xpr>;
 [PICTURE <pic>];
 
 [COLOR <color>];
 
 => MHIDE();
 DEVPOS(<row>, <col>);
 DEVOUTPict(<xpr>, <pic> [, <color>]);
 MSHOW()

Function MLEFTDOWN()

 MLEFTDOWN() --> lIsPressed

Function MPRESENT()

 MPRESENT() --> lIsPresent

Function MRESTSTATE()

 MRESTSTATE( <cSaveState> ) --> NIL

Function MRIGHTDOWN()

 MRIGHTDOWN() --> lIsPressed

Function MROW()

 MROW() --> nCurrentMouseRow

Function MSAVESTATE()

 MSAVESTATE() --> cSaveState

Function MSETBOUNDS()

 MSETBOUNDS( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>] ) --> NIL

Function MSETCLIP()

 MSETCLIP([<nCoord list>], [<nMode>]) --> aRegions

MSETCLIP() controls mouse pointer movements. It allows you to restrict movement to a region. When an inclusion is defined and the user tries to move the mouse pointer out of the rectangle, it remains stuck at the edge of the area, but is still visible. This mode should be used to restrict the range of user choices for moving or clicking the mouse.

 Coordinate Type Constants
------------------------------------------------------------------------
Constant       Description
------------------------------------------------------------------------
LLM_COOR_TEXT  Specifies that the coordinates are given in lines and
columns of text
LLM_COOR_GRAPH Specifies that the coordinates are given in pixels
------------------------------------------------------------------------

 This example shows how the MSETCLIP() function works:
 
 // Define an inclusion region and save the current
 // inclusion region in the array aOldInc
 
 aOldInc := MSETCLIP(5, 5, 20, 75,LLM_COOR_TEXT)
 // Code for selecting objects and buttons
 // Restore old inclusion region
 MSETCLIP(aOldInc[5],;
 aOldInc[6],;
 aOldInc[7],;
 aOldInc[8],;
 LLG_VIDEO_TEXT)

Function MSETCURSOR()

 MSETCURSOR( [<lVisible>] ) --> lIsVisible

Function MSETPOS()

 MSETPOS( <nRow>, <nCol> ) --> NIL

Function MSHOW()

 MSHOW([<nCol>, <nRow>, <nStyle>]) --> nOldCursorShape
 MSHOW([<nCursorShape>]) --> nOldCursorShape
 MSHOW([<nCursorShape>] | [<nCol>, <nRow>, <nMode>]) --> nOldCursorShape

MSHOW() displays the mouse pointer. It is generally used without parameters to simply redisplay the mouse pointer at the position where MHIDE() hid it (assuming the user has not moved the mouse).

It is possible to use two sets of parameters with this function.

Specify the coordinates where the pointer should appear. In this case, three parameters must be passed: the mode and its coordinates. In text mode, coordinates are passed as row and column. In graphic mode, you can pass either text or graphic coordinates. Conversion is done automatically based on the font size of the current characters.

You can also specify the mouse cursor shape to be displayed when the mouse is visible. This feature is available in graphic mode only.

It is important to hide the mouse pointer before any new screen display, and then show it again. See MHIDE() for further information on how to do this.

Note: The MSETCURSOR() function should be used in place of MSHOW() and MHIDE(). It is kept here for compatibility.

 Text and Graph Constants
------------------------------------------------------------------------
Constant       Description
------------------------------------------------------------------------
LLM_COOR_TEXT  Specifies that the coordinates are passed in rows and
columns of text
LLM_COOR_GRAPH Specifies that the coordinates are passed in pixels
------------------------------------------------------------------------

 The following example hides the mouse pointer before using an
 @...SAY command and then redisplays it.  Next, the mouse pointer is
 repositioned, hidden, changed to an hour-glass, and then restored to
 its previous shape:
 
 LOCAL nOldShape := 0
 MHIDE()
 @ 10, 20 say "Hello world!!!"
 MSHOW()
 // Position the pointer at the center of the screen
 MSHOW(MAXCOL() / 2, MAXROW() / 2, LLM_COOR_TEXT)
 MHIDE()
 @ 10, 20 say "Please wait ..."
 // Display an hour glass cursor
 nOldShape := MSHOW(LLM_CURSOR_WAIT)
 // Your code
 // Restore previously used cursor
 MSHOW(nOldShape)

Function MSTATE()

 MSTATE() --> aState | 0

MSTATE() returns information on the mouse state, i.e., the current screen position of the pointer, the state of the left and right mouse buttons, the visibility status of the mouse pointer, and the version of the mouse driver.

 MSTATE() Return Array
 ------------------------------------------------------------------------
 Position                 Description
 ------------------------------------------------------------------------
 LLM_STATE_X              State of X position.
 LLM_STATE_Y              State of Y position.
 LLM_STATE_ROW            State of column position.
 LLM_STATE_COL            State of line position.
 LLM_STATE_LEFT           State of left mouse button.  LLM_BUTTON_DOWN
 means down and LLM_BUTTON_UP means up.
 LLM_STATE_RIGHT          State of right mouse button.  LLM_BUTTON_DOWN
 means down and LLM_BUTTON_UP means up.
 LLM_STATE_VISIBLE        State of mouse pointer.  True (.T) means
 visible and false (.F) means invisible.  (See
 MSHOW() and MHIDE() for more information.)
 LLM_STATE_DRIVER         Indicates version of mouse driver.
 LLM_STATE_SHAPE          Mouse cursor shape.  (See note below.)
 LLM_STATE_CLICKS_LEFT    Number of left clicks since last MSTATE() call.
 LLM_STATE_CLICKS_RIGHT   Number of right clicks since last MSTATE()
 call.
 ------------------------------------------------------------------------
 

 This example shows how to use MSTATE() function:
 
 // Show the mouse pointer
 MSHOW()
 DO WHILE INKEY() != K_ESC
 // Retrieve mouse state
 aState := MSTATE()
 // Line position
 @ 24,  0 SAY aState[LLM_STATE_ROW]
 // Column position
 @ 24, 10 SAY aState[LLM_STATE_COL]
 // State of left button
 @ 24, 20 SAY "Left" + If(aState[LLM_STATE_LEFT]==LLM_BUTTON_DOWN,;
 "Down"  ,;
 "Up")
 // State of right button
 @ 24, 40 SAY "Right " + If(aState[LLM_STATE_RIGHT]==    ;
 LLM_BUTTON_DOWN ,;
 "Down"  ,;
 "Up")
 ENDDO
 // Hide the mouse pointer
 MHIDE()

Function NEXTKEY()

 NEXTKEY() --> nInkeyCode

NEXTKEY() is a function that reads the keystroke pending in the keyboard buffer or the next mouse event without removing it. The value returned is the INKEY() code of the key pressed--the same value as returned by INKEY() and LASTKEY(). NEXTKEY() returns values for all ASCII characters as well as function, Alt+function, Ctrl+function, Alt+letter, and Ctrl+letter key combinations.

NEXTKEY() is like the INKEY() function but differs in one fundamental respect. INKEY() removes the pending key from the keyboard buffer and updates LASTKEY() with the value of the key. by contrast NEXTKEY() reads, but does not remove the key from the keyboard buffer, and does not update LASTKEY().

Since NEXTKEY() does not remove the key from the keyboard buffer, it can be used to poll the keyboard, and then pass control to a routine that uses a wait state or INKEY() to actually fetch the key from the buffer.

For a complete list of INKEY() codes and Inkey.ch constants.

  This example places an Esc key in the keyboard buffer, and
 then shows the differences between INKEY(), LASTKEY(), and NEXTKEY():
 
 #include "Inkey.ch"
 //
 CLEAR TYPEAHEAD
 KEYBOARD CHR(K_ESC)
 //
 ? NEXTKEY(), LASTKEY()            // Result: 27 0
 ? INKEY(), LASTKEY()              // Result: 27 27
 ? NEXTKEY()                       // Result: 0
 
 

Function SETKEY()

 SETKEY(<nInkeyCode>, [<bAction>]) --> bCurrentAction

SETKEY() is a keyboard function that sets or queries the automatic action associated with a particular key during a wait state. A wait state is any mode that extracts keys from the keyboard except for INKEY(), but including ACHOICE(), DBEDIT(), MEMOEDIT(), ACCEPT, INPUT, READ and WAIT. Up to 32 keys may be assigned at any one time. At startup, the system automatically assigns the F1 key to execute a procedure or user-defined function named Help.

When an assigned key is pressed during a wait state, the EVAL() function evaluates the associated <bAction> and the parameters, PROCNAME(), PROCLINE(), and READVAR(). It is, however, not necessary to list arguments when specifying <bAction> if you do not plan to use them within the action block.

SETKEY() is like the SET KEY command which associates a procedure invocation with a key.

 This code fragment associates an action block with a key, and
 then, after getting a key using INKEY(), executes it with the EVAL()
 function:
 
 #include "Inkey.ch"
 SETKEY(K_DN, {|cProc, nLine, cVar| MyProc(cProc, ;
 nLine, cVar)})
 .
 . <statements>
 .
 DO WHILE .T.
 nKey := INKEY(0)
 DO CASE
 CASE (bAction := SETKEY(nKey)) != NIL
 EVAL(bAction, PROCNAME(), PROCLINE(), READVAR())
 CASE nKey = K_PGUP
 Previous()
 CASE nKey = K_PGDN
 Next()
 CASE nKey = K_ESC
 EXIT
 ENDCASE
 ENDDO