xHarbour Reference Documentation > Function Reference

SetKey()

Associates a code block with a key.

Syntax

SetKey( <nInkeyCode>    , ;
       [<bNewCodeblock>], ;
       [<bCondition>]     ) --> bOldCodeblock

Arguments

<nInkeyCode>

This is a numeric value representing the key code of the key to associate <bNewCodeblock> with. The key code is returned by the Inkey() function. To specify values for this parameter use #define constants from the file INKEY.CH.

<bNewCodeblock>

This parameter optionally specifies a code block to be executed when the key <nInkeyCode> is pressed. Passing NIL explicitly for <bNewCodeblock> releases a previously assigned code block.

<bCondition>

Optionally, a code block returning a logical value can be passed. If specified, the code block <bNewCodeblock> is only evaluated in a wait state, when <bCondition> returns .T. (true).

Note:  this code block can only be queried with function HB_SetKeyGet().

Return

The function returns the code block associated with <nInkeyCode> before SetKey() is called. If no code block is associated with the key, the return value is NIL.

Description

SetKey() queries or changes associations between key codes and code blocks. When a code block is associated with a key and the user presses this key, the code block is automatically executed during a wait state. An application enters a wait state when user input is requested. This includes functions like AChoice(), Browse(), DbEdit(), MemeoEdit() and commands like ACCEPT, INPUT, READ and WAIT, but it does not include the Inkey() function. Inkey() does not monitor key/code block associations.

The associated code block receives three parameters: the return values of functions ProcName(), ProcLine() and ReadVar().

When an application starts, the F1 key is automatically associated with a code block calling the user-defined function or procedure named Help, if it exists.

Info

See also:	Eval(), HB_SetKeyArray(), HB_SetKeyCheck(), HB_SetKeyGet(), HB_SetKeySave(), Inkey(), SET KEY
Category:	Environment functions , Keyboard functions
Header:	inkey.ch
Source:	rtl\setkey.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example implements function SetKeys() which accepts a
// two column array holding data for key/code block associations.
// Passing the array for the first time, activates the
// associations. Passing it a second time, releases them.

   #include "Inkey.ch"

   PROCEDURE Main
      LOCAL cString := "Testing SetKey()"
      LOCAL aKey := { ;
          { K_F2, {|c1,n,c2| F2_Key(c1,n,c2) } }, ;
          { K_F3, {|c1,n,c2| F3_Key(c1,n,c2) } }  ;
        }

      CLS

      // associate keys with code blocks
      SetKeys( aKey )

      @ 10,10 SAY "Press F1, F2 or F3" GET cString
      READ

      // release code block associations
      SetKeys( aKey )
   RETURN


   PROCEDURE Help( cProcName, nProcLine, cReadVar )
      LOCAL cScreen := SaveScreen()
      LOCAL bBlock  := SetKey( K_F1, NIL ) // no recursive calls
      CLS
      ? "Help routine"
      ? "Called from:", cProcName, nProcLine, cReadVar
      WAIT
      SetKey( K_F1, bBlock )
      Restscreen(,,,, cScreen )
   RETURN


   PROCEDURE F2_Key( cProcName, nProcLine, cReadVar )
      LOCAL cScreen := SaveScreen()
      LOCAL bBlock  := SetKey( K_F2, NIL ) // no recursive calls
      CLS
      ? "F2 key pressed"
      ? "Called from:", cProcName, nProcLine, cReadVar 
      WAIT
      SetKey( K_F2, bBlock )
      Restscreen(,,,, cScreen )
   RETURN


   PROCEDURE F3_Key( cProcName, nProcLine, cReadVar )
      LOCAL cScreen := SaveScreen()
      LOCAL bBlock  := SetKey( K_F3, NIL ) // no recursive calls
      CLS
      ? "F3 key pressed"
      ? "Called from:", cProcName, nProcLine, cReadVar
      WAIT
      SetKey( K_F3, bBlock )
      Restscreen(,,,, cScreen )
   RETURN


   PROCEDURE SetKeys( aKeys )
      LOCAL i, imax := Len( aKeys )

      FOR i:=1 TO imax
         aKeys[i,2] := SetKey( aKeys[i,1], aKeys[i,2] )
      NEXT
   RETURN