Query Key Status Strawman

by Jacob Rossi, June 2009, send feedback to travil AT microsoft dot com

I’ve read through the Win32 documentation on MSDN surrounding GetKeyState and GetAsyncKeyState (and other relevant APIs). Here’s my suggestion for a similar implementation for the DOM. There’s some significant differences between the Win32 APIs and my suggestion. First, my most closely resembles GetAsyncKeyState (which returns key status at invocation time rather than retrieve the status from the message queue, this is an easier model for us to implement since it would be hard for us to track when key messages get eaten off the queue by other parts of the application).

Syntax:

short window.getKeyState(string keyValue)

Parameters:

keyValue: the string key value as explained in Appendix 2 of the DOM L3 spec (see also A.1.5). Examples: “A”, “Spacebar”, “$”, “Backspace”, etc.

Return Value:

MSB: 1 if the key is currently down, otherwise it is up. LSB: 1 if the key is a toggle key (like CAPS LOCK) and it is currently toggled on, otherwise the key is either toggled off or doesn’t toggle if it is 0.

Returns Null if the caller does not currently meet the security requirements (see below).

Security Requirements:

• The script’s ownerDocument must be in focus
  • This does not include if an iframe has focus
  • Does this mean that the API should actually be attached to the document and not the window?
• More rules?
• I’m testing what the current restrictions are related to key events. I’m hoping this will help drive a similar security policy.

Other interesting stuff:

• Win32 also has APIs for getting the entire keyboard state (fills a 256 byte array with the status for each virtual key): getKeyboardState()
• Win32 only sends the WM_KEYDOWN message to the window with the “keyboard focus” when a “nonsystem” key is pressed. Nonsystem key means any key that is pressed when the ALT key is not pressed.
• Win32 does have a RegisterHotKey function which defines a system-wide hot key. It takes in the hWnd of the window that should receive the WM_HOTKEY message. However, it only lets you specify a combination that is ALT, CONTROL, SHIFT, or WIN plus some other virtual key.