Functions and Directives

Function SetKey() Foundation

Associates a code block with a specific key.

SetKey( <nInkey>, [<bNewBlock>] ) --> bOldBlock
<nInkey> is the numeric key code returned from the function Inkey() when the key or key combination is pressed.
<bNewBlock> is a code block attached to the key with the Inkey() code <nInkey>. The code block is automatically executed during a wait state situation like READ or MemoEdit(), when the applicable key is pressed. The key ceases to activate a code block when NIL is explicitly specified for <bNewBlock>.

SetKey() works like the function Set(). When SetKey() is called without the argument <bNewBlock>, the function returns the code block currently associated with the key. When no code block is set for the key, NIL is returned. If <bNewBlock> is specified, the new block is attached to the key and the old code block or NIL is returned.


The function SetKey() is a compatibility function which attaches a code block to keys registered by the function Inkey(). In the Xbase++ system, the function SetAppEvent() should be used instead of SetKey(). SetAppEvent() allows a code block to be attached to a specific event. Code blocks can also be associated with mouse events. Also, SetAppEvent() supports keyboard events not recognized by Inkey().

The environment function SetKey() attaches a code block to a specific key or retrieves the currently attached code block. Specific commands and functions, which do not read the keyboard with Inkey(), automatically execute the code block. These include the commands ACCEPT, INPUT, READ and WAIT as well as the functions AChoice(), DbEdit() and MemoEdit(). When the code block is automatically evaluated by these commands or functions, three arguments are passed to it. These arguments are the return values of the functions ProcName(), ProcLine() and ReadVar().

the function ReadVar() returns a character string only if READ, ReadModal() or MENU TO is being executed. In all other situations a null string ("") is returned.

Instead of SetKey(), the command SET KEY can be used. When SET KEY is used to attach a code block to the key, it does not allow the code block previously attached to the key to be saved.

SetKey() is a compatibility function used with the Get system and functions such as AChoice(). Such functions require a console window and hence can only be used in text and hybrid mode applications.

// In the example, three input fields are shown and a code 
// block is attached to the insert key which changes the 
// cursor shape when the key is pressed during the execution 
// of READ. 

#include "" 
#include "" 
#include "" 

   LOCAL cVar1 := Space(10) 
   LOCAL cVar2 := Space(20) 
   LOCAL cVar3 := Space(30) 
   LOCAL bBlock 
                                // save and set 
                                // code block for insert key 
   bBlock := SetKey( K_INS, {|| ChangeCursor() } ) 

   @ 10,10 SAY "Value 1:" GET cVar1 
   @ 11,10 SAY "Value 2:" GET cVar2 
   @ 12,10 SAY "Value 3:" GET cVar3 

   SetKey( K_INS, bBlock )      // reset old value 


PROCEDURE ChangeCursor() 
   Set( _SET_INSERT, ! Set(_SET_INSERT) ) 
   SetCursor( IIf(Set(_SET_INSERT), SC_SPECIAL1, SC_NORMAL ) ) 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.