gpii-windows/gpii/node_modules/gpii-userInput/README.md

Components of the GPII personalization infrastructure for use on Microsoft's "Windows" ™

# User Input

This module deals with things related to user input devices

## gpii.windows.sendKeys

Simulate key presses. The sequence of keys is almost the same as [AutoHotKey's Send command](https://hotkeyit.github.io/v2/docs/commands/Send.htm) 

### Key sequence syntax:

Each character in the string is a key to press.

Special (non-character) keys are surrounded by curly braces (`{` and `}`). For example, `{Enter}`. Character letters can
optionally be surrounded in braces (eg, `{a}`). To type curly braces, surround it with braces (eg, `{{}` for `{`, and
`{}}` for `}`).

#### Modifiers

Normally, keys are pressed and released. To hold down a key, use `{keyname down}` and to release, `{keyname up`}. For
example, `{Shift down}abc1{Shift up}` would type the text `ABC!`.

Alternatively, to hold down a modifier key while pressing another key, prefix with one or more of `!`, `+`, `^`, and
`#`. For example, `^C` holds `Ctrl` while pressing `C`. This will affect the next key only - so to send `Ctrl + A` then
`Ctrl + X` use `^A^X`.

|Modifier prefix|Modifier key| Example   |
|---------------|------------|-----------|
|     `!`       | `Alt`      | `!{F4}` sends `Alt + F4`  |
|     `+`       | `Shift`    | `+hel+lo` types the text `HelLo`   |
|     `^`       | `Ctrl`     | `^o` sends `Ctrl + O`  |
|     `'`       | `LWin`     | `#r` holds the Windows key while pressing `r` |

Modifiers can be combined, for example: `^!{Del}`.

To send the modifier symbols as a key stroke, surround with curly braces like `{!}`.

If the current layout requires a modifier to press a key (eg, typing `%` could require `shift + 5`), then that is what
is simulated. This is also the case for uppercase letters. `a` (or `{a}`) will send just the `a` keystroke, but `A` (or
`{A}`) will be equivalent to `{Shift down}a{Shift up}`.

#### Examples

`Hello`, `+hello`, `{H}el{l}o`, `{Shift down}h{Shift up}ello` all type `Hello`.

`#r{Wait window}notepad{enter}` will start notepad.

`!{space}x` maximise the current window.

#### Repetition

Key presses can be repeated by adding a number after the name. For example, `{Enter 10}` will press and release the
`Enter` key 10 times, then `a` for 5 times.

#### Delay

Delay can be introduced between each key press using `{Wait n}`, which causes a pause for `n` seconds. For example,
`abc{Wait 5}xyz` will type `abc`, pause for 5 seconds, then `xyz`.

The `{Wait window}` keyword can be used to wait for a new window to be activated.

#### Key names

|Key name| Keystroke |
|-----|-----|
|Single character, `{a}`, `{+}`, `{}}`, etc.|The literal character|
|`{Back}`,`{BS}`,`{BackSpace}`| BACKSPACE key |
|`{Tab}`| TAB key |
|`{Clear}`| CLEAR key |
|`{Enter}`, `{Return}`| ENTER key |
|`{Enter}`, `{Return}`| ENTER key |
|`{Ctrl}`, `{Control}`| CTRL key |
|`{LCtrl}`, `{LControl}`| Left CTRL key |
|`{RCtrl}`, `{RControl}`| Right CTRL key |
|`{Alt}`, `{Menu}`| ALT key |
|`{LAlt}`| Left ALT key |
|`{RAlt}`| Right ALT key |
|`{Shift}`| SHIFT key |
|`{LShift}`| Left SHIFT key |
|`{RShift}`| Right SHIFT key |
|`{Win}`, `{LWin}`| Left Windows key (Natural keyboard) |
|`{RWin}`| Right Windows key (Natural keyboard) |
|`{Pause}`| PAUSE key |
|`{Capital}`| CAPS LOCK key |
|`{Escape}`| ESC key |
|`{Accept}`| IME accept |
|`{Space}`| SPACEBAR |
|`{PageUp}`, `{PgUp}`, `{Prior}`| PAGE UP key |
|`{PageDown}`, `{PgDown}`, `{Next}`| PAGE DOWN key |
|`{End}`| END key |
|`{Home}`| HOME key |
|`{Left}`| LEFT ARROW key |
|`{Up}`| UP ARROW key |
|`{Right}`| RIGHT ARROW key |
|`{Down}`| DOWN ARROW key |
|`{Select}`| SELECT key |
|`{Print}`| PRINT key |
|`{Execute}`| EXECUTE key |
|`{Snapshot}`| PRINT SCREEN key |
|`{Insert}`, `{Ins}`| INS key |
|`{Delete}`, `{Del}`| DEL key |
|`{Help}`| HELP key |
|`{CtrlBreak}`, `{Cancel}`| Control-break processing |
|`{Apps}`| Applications key (Natural keyboard) |
|`{Sleep}`| Computer Sleep key |
|`{Numpad0}`| Numeric keypad 0 key |
|`{Numpad1}`| Numeric keypad 1 key |
|`{Numpad2}`| Numeric keypad 2 key |
|`{Numpad3}`| Numeric keypad 3 key |
|`{Numpad4}`| Numeric keypad 4 key |
|`{Numpad5}`| Numeric keypad 5 key |
|`{Numpad6}`| Numeric keypad 6 key |
|`{Numpad7}`| Numeric keypad 7 key |
|`{Numpad8}`| Numeric keypad 8 key |
|`{Numpad9}`| Numeric keypad 9 key |
|`{Multiply}`| Multiply key |
|`{Add}`| Add key |
|`{Separator}`| Separator key |
|`{Subtract}`| Subtract key |
|`{Decimal}`| Decimal key |
|`{Divide}`| Divide key |
|`{F1}` to `{F24}`| 'F' keys `{F1}` to `{F24}` |
|`{Numlock}`| NUM LOCK key |
|`{Scroll}`| SCROLL LOCK key |
|||
|`{U+###}`|The unicode character, where `###` is the code point in hex. For example, `{U+29ac}`, `{U+7e}` |
|||
|`{Browser_Back}`| Browser Back key |
|`{Browser_Forward}`| Browser Forward key |
|`{Browser_Refresh}`| Browser Refresh key |
|`{Browser_Stop}`| Browser Stop key |
|`{Browser_Search}`| Browser Search key |
|`{Browser_Favorites}`| Browser Favorites key |
|`{Browser_Home}`| Browser Start and Home key |
|`{Volume_Mute}`| Volume Mute key |
|`{Volume_Down}`| Volume Down key |
|`{Volume_Up}`| Volume Up key |
|`{Media_Next}`, `{Media_Next_Track}`| Next Track key |
|`{Media_Prev}`, `{Media_Prev_Track}`| Previous Track key |
|`{Media_Stop}`| Stop Media key |
|`{Media_Play_Pause}`| Play/Pause Media key |
|`{Launch_Mail}`| Start Mail key |
|`{Launch_Media_Select}`| Select Media key |
|`{Launch_App1}`| Start Application 1 key |
|`{Launch_App2}`| Start Application 2 key |
|||
|`{Lbutton}`| Left mouse button |
|`{Rbutton}`| Right mouse button |
|`{Mbutton}`| Middle mouse button (three-button mouse) |
|`{Xbutton1}`| X1 mouse button |
|`{Xbutton2}`| X2 mouse button |
|||
|`{Oem_1}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the ';:' key |
|`{Oem_Plus}`| For any country/region, the '+' key |
|`{Oem_Comma}`| For any country/region, the ',' key |
|`{Oem_Minus}`| For any country/region, the '-' key |
|`{Oem_Period}`| For any country/region, the '.' key |
|`{Oem_2}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the '/?' key |
|`{Oem_3}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the '`~' key |
|`{Oem_4}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the '[{' key |
|`{Oem_5}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the '\|' key |
|`{Oem_6}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the ']}' key |
|`{Oem_7}`| Used for miscellaneous characters; it can vary by keyboard. For the US standard keyboard, the 'single-quote/double-quote' key |
|`{Oem_8}`| Used for miscellaneous characters; it can vary by keyboard. |
|`{Oem_102}`| Either the angle bracket key or the backslash key on the RT 102-key keyboard |
|`{Processkey}`| IME PROCESS key |
|`{Packet}`| Used to pass Unicode characters as if they were keystrokes. The VK_PACKET key is the low word of a 32-bit Virtual Key value used for non-keyboard input methods. For more information, see Remark in KEYBDINPUT, SendInput, WM_KEYDOWN, and WM_KEYUP: -, // 0xE8 |
|`{Attn}`| Attn key |
|`{Crsel}`| CrSel key |
|`{Exsel}`| ExSel key |
|`{Ereof}`| Erase EOF key |
|`{Play}`| Play key |
|`{Zoom}`| Zoom key |
|`{Noname}`| Reserved |
|`{Pa1}`| PA1 key |
|`{Oem_Clear}`| lear key |
|`{Kana}`| IME Kana mode |
|`{Hangul}`| IME Hangul mode |
|`{Hanguel}`| IME Hanguel mode (maintained for compatibility; use VK_HANGUL) |
|`{Junja}`| IME Junja mode |
|`{Final}`| IME final mode |
|`{Hanja}`| IME Hanja mode |
|`{Kanji}`| IME Kanji mode |
|`{Convert}`| IME convert |
|`{Nonconvert}`| IME nonconvert |
|`{Modechange}`| IME mode change request |