Functions and Directives Functions and Directives

Function AppKeyState() Foundation

Determines and optionally changes the state of keys.

Syntax
AppKeyState( <nKeyDefine> [,<nMode>] ) --> nKeyState
AppKeyState( <nKeyDefine> [,<lGetToggleState>] ) --> nKeyState *)
*) Deprecated syntax.
Parameters
<nKeyDefine>
An xbeK_* Keyboard input Event Code #define constant from appevent.ch must be used for this parameter. Key combinations, such as xbeK_CTRL_F4 or xbeK_SH_TAB, are not supported.
Selected key constants for AppKeyState()
Constant Description
xbeK_ALT Determines the state of the Alt key
xbeK_CTRL Determines the state of the Ctrl key
xbeK_SHIFT Determines the state of the Shift key
xbeK_INS Determines the state of the Insert key
xbeK_NUM_LOCK Determines the state of the Num Lock key
xbeK_CAPS_LOCK Determines the state of the Caps Lock key
<nMode>
A numeric value that specifies the operational mode of the AppKeyState() function. One or more of the following #define constants from appevent.ch must be used for this parameter.
Operation modes of AppKeyState()
Constant Description
APPKEY_GET_PRESSED *) AppKeyState() returns APPKEY_DOWN if the key is currently pressed (held down)
APPKEY_GET_TOGGLED AppKeyState() returns APPKEY_TOGGLED if a key, such as Num Lock, is currently toggled (on)
APPKEY_SET_PRESSANDRELEASE Simulates a key-press of the specified key. Can be used to toggle the state of special keys such as Num Lock
  1. Default value
By default, APPKEY_SET_PRESSANDRELEASE returns the pressed key state. To retrieve the toggled state when simulating a key press, APPKEY_GET_TOGGLED and APPKEY_SET_PRESSANDRELEASE must be added together.
<lGetToggleState>
This parameter is deprecated and retained for compatibility reasons only. If .T. (true) is passed for <lGetToggleState>, AppKeyState() behaves as if the constant APPKEY_GET_TOGGLED was passed in the <nMode> parameter. If .F. (false) is passed, the behavior corresponds to that specified via APPKEY_GET_PRESSED.
Return

The function returns a numeric value equivalent to the following #define constants:

Return values of AppKeyState()
Constant Description
APPKEY_IDLE The key is not pressed (or toggled off)
APPKEY_DOWN The key is pressed
APPKEY_TOGGLED The key is toggled (on)

The return value is always the current state of the specified key. Even if the <nMode> parameter is set to APPKEY_SET_PRESSANDRELEASE, simulating a key press, the return value is always the state prior to the simulation of the key press.

Description

The function determines the current state of selected keys. The primary usage of AppKeyState() is to query special keys for which no events are generated by the AppEvent() function. For example, this allows testing whether or not the Ctrl key is pressed, while processing a Left Button Down (xbeM_LbDown) event.

By default (<nMode> is APPKEY_GET_PRESSED), the return value of AppKeyState() indicates whether the specified key is currently pressed/held down (APPKEY_DOWN) or not (APPKEY_IDLE). If APPKEY_GET_TOGGLED is used, the return value will be either APPKEY_IDLE or APPKEY_TOGGLED, alternating every time the key is pressed. By itself, this information is only meaningful for the three toggle keys (Caps Lock, Num Lock, and Scroll Lock), but it can also be used to assign an arbitrary status to any key. For example, the toggle state of the Insert key could be treated as an indicator for switching between Overwrite and Insert Mode.

If the #define constant APPKEY_SET_PRESSANDRELEASE is assigned to the <nMode>parameter, AppKeyState() simulates a key-press of the specified key. This can be used to programmatically modify the toggle state of special keys such as Num Lock, Caps Lock, or the Insert key.

AppKeyState() requires a program to be linked as a GUI application for the function to return correct results (by using the linker switch /PM:PM or GUI=yes in the project file).

Examples
Testing the state of special keys 
// The example displays the state of several special keys 
// along with the state of the left and right mouse button. 
// In addition, the Caps Lock key can be toggled by clicking 
// on a push button. 

#include "appevent.ch" 

#define KS_ALT   1 
#define KS_CTRL  2 
#define KS_SHIFT 3 
#define KS_LEFT  4 
#define KS_RIGHT 5 
#define KS_CLOCK 6 
#define KS_NLOCK 7 
#define KS_SLOCK 8 
#define KS_INS   9 

STATIC saKSold[9] 
STATIC saKSnew[9] 
STATIC saMsg := {" Alt "        , ; 
                 " Ctrl "       , ; 
                 " Shift "      , ; 
                 " Left "       , ; 
                 " Right "      , ; 
                 " Caps Lock "  , ; 
                 " Num Lock "   , ; 
                 " Scroll Lock ", ; 
                 " Insert"} 
PROCEDURE Main() 
   LOCAL nEvent := xbe_None 
   LOCAL nKS, mp1, mp2, oXbp 

   CLS 
   SetColor("W/N") 
   SetAppWindow():useShortCuts := .T. 
   SetAppWindow():setTitle("Click the mouse buttons and/or press " + ; 
                  "Shift, Ctrl, Alt, Insert, Caps/Num/Scroll Lock") 
   SetMouse(.T.) 

   AFill(saKSold, APPKEY_IDLE) 
   AFill(saKSnew, APPKEY_IDLE) 

   oXbp := XbpPushButton():new() 
   oXbp:caption  := "Toggle Caps Lock" 
   oXbp:create(, , {200, 220}, {250, 40}) 
   oXbp:activate := {|| AppKeyState(xbeK_CAPS_LOCK, APPKEY_SET_PRESSANDRELEASE)} 

   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent(@mp1, @mp2, @oXbp, 0.5) 
      IF nEvent <> xbe_None 
         oXbp:handleEvent(nEvent, mp1, mp2, oXbp) 
      ENDIF 

      DO CASE 
         CASE nEvent == xbeM_LbDown 
            saKSnew[KS_LEFT]  := APPKEY_DOWN 

         CASE nEvent == xbeM_LbUp 
            saKSnew[KS_LEFT]  := APPKEY_IDLE 

         CASE nEvent == xbeM_RbDown 
            saKSnew[KS_RIGHT] := APPKEY_DOWN 

         CASE nEvent == xbeM_RbUp 
            saKSnew[KS_RIGHT] := APPKEY_IDLE 
      ENDCASE 

      saKSnew[KS_ALT]   := AppKeyState(xbeK_ALT) 
      saKSnew[KS_CTRL]  := AppKeyState(xbeK_CTRL) 
      saKSnew[KS_SHIFT] := AppKeyState(xbeK_SHIFT) 
      saKSnew[KS_CLOCK] := AppKeyState(xbeK_CAPS_LOCK,   APPKEY_GET_TOGGLED) 
      saKSnew[KS_NLOCK] := AppKeyState(xbeK_NUM_LOCK,    APPKEY_GET_TOGGLED) 
      saKSnew[KS_SLOCK] := AppKeyState(xbeK_SCROLL_LOCK, APPKEY_GET_TOGGLED) 
      saKSnew[KS_INS]   := AppKeyState(xbeK_INS,         APPKEY_GET_TOGGLED) 

      FOR nKS := 1 TO 9 
         IF saKSold[nKS] <> saKSnew[nKS] 
            DisplayKeyState() 
            EXIT 
         ENDIF 
      NEXT 
      ACopy(saKSnew, saKSold) 
   ENDDO 
RETURN 

PROCEDURE DisplayKeyState() 
   LOCAL cMsg := "", nKS 

   FOR nKS := 1 TO 9 
      IF saKSNew[nKS] == APPKEY_DOWN .OR. saKSNew[nKS] == APPKEY_TOGGLED 
         cMsg += saMsg[nKS] 
      ELSE 
         cMsg += Space(Len(saMsg[nKS])) 
      ENDIF 
   NEXT 

   @ MaxRow(), 0 SAY cMsg 
RETURN
Feedback

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.