GetKeyboardState function (Windows)

Switch View :

Classic

Lightweight

ScriptFree

Site Feedback

GetKeyboardState function

Applies to: desktop apps only

Copies the status of the 256 virtual keys to the specified buffer.

Syntax

BOOL WINAPI GetKeyboardState(
  __out  PBYTE lpKeyState
);

Parameters

lpKeyState [out]

Type: PBYTE

The 256-byte array that receives the status data for each virtual key.

Return value

Type: BOOL

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can call this function to retrieve the current status of all the virtual keys. The status changes as a thread removes keyboard messages from its message queue. The status does not change as keyboard messages are posted to the thread's message queue, nor does it change as keyboard messages are posted to or retrieved from message queues of other threads. (Exception: Threads that are connected through AttachThreadInput share the same keyboard state.)

When the function returns, each member of the array pointed to by the lpKeyState parameter contains status data for a virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the key is a toggle key, for example CAPS LOCK, then the low-order bit is 1 when the key is toggled and is 0 if the key is untoggled. The low-order bit is meaningless for non-toggle keys. A toggle key is said to be toggled when it is turned on. A toggle key's indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

To retrieve status information for an individual key, use the GetKeyState function. To retrieve the current state for an individual key regardless of whether the corresponding keyboard message has been retrieved from the message queue, use the GetAsyncKeyState function.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL and VK_MENU as indices into the array pointed to by lpKeyState. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as indices to distinguish between the left and right instances of those keys:

VK_LSHIFT

VK_RSHIFT

VK_LCONTROL

VK_RCONTROL

VK_LMENU

VK_RMENU

These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll

It doesn't work. They say "The status changes as a thread removes keyboard messages from its message queue." I haven't quite figured out how it actually works, but this 256-byte array only changes after the first call your application makes to GetMessageW, and then remains the same no matter how hard you push it. Consider this code which displays "displaykey" key state when user hits "testkey": int main() { int displaykey = VK_RETURN, testkey = VK_SPACE; BYTE keys[256]; MSG msg; RegisterHotKey( NULL, testkey, 0, testkey ); while (GetMessageW(&msg, (HWND) NULL, 0, 0)) { //GetKeyState(displaykey); // <-- uncomment to make it work if (!GetKeyboardState(keys)) // <-- doesn't work like they say! puts("ERROR"); int state = keys[displaykey]; printfln( "key %i is %s and toggled %s (value %x)\t\t\n", displaykey, ((state & 128) ? "down" : "up"), ((state & 1) ? "on" : "off"), state ); DispatchMessageW(&msg); } UnregisterHotKey( null, testkey ); return 0; } Now press Space and then press Enter without releasing Space. You'll notice no changes. Then uncomment the line with GetKeyState and it will work fine. I suppose MS wanted to say that the status changes as you call GetKeyState or fetch a WM_*KEY message FOR THAT KEY, but if your thread simply scans the keyboard by GetKeyboardState, it will never detect anything. In other words, if you wanna scan all the 255 keys you'll have to storm the kernel with 255 subsequent calls to GetKeyState! What a waste of resources!

dmex

C# syntax

[DllImport("user32.dll", CharSet=CharSet.Auto, ExactSpelling=true)]
public static extern int GetKeyboardState(byte[] keystate);