Xbase++ - Function AppKeyState()

Determines and optionally changes the state of keys.

AppKeyState( <nKeyDefine> [,<nMode>] ) --> nKeyState
AppKeyState( <nKeyDefine> [,<lGetToggleState>] ) --> nKeyState *)
*) Deprecated syntax.

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.

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.

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
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.

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.

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

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.

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).

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

Function AppKeyState() Foundation