# node-key-sender

Use this lib to send keyboard events to the operational system. 

It uses a jar file (Java), so Java Run Time is required on the operational system you are running your node project (version 8 or above).

**Bugs and issues**: Please, post any issues to https://github.com/garimpeiro-it/node-key-sender/issues. 

# Main features

- Send raw keyboard key codes to the operational system;
- Send one key;
- Send multiple keys pressed one after the other;
- Send multiple keys pressed together (combination);
- Delay between keys;
- Delay for each pressed key or each combination;
- Possibility to map key codes;
- Case correction for text;
- Multi platform (it will work in all operation systems that Java can run);
- It will send the key to the current focused application in the operational system;
- It is sensitive to the operational system, keyboard driver and phisical keyboard installed on the running platform.

# Installation

Install it using npm:

    npm install --save-dev node-key-sender

The command above will install and add the lib into your "package.json" file.

# How it works

Each key in your keyboard is mapped with a key code. Although a physical keyboard key may have printed above its surface more than one key (for example ':' and ';'), both generate the same key code. So, do not confuse key codes with ASCII or UNICODE values, they are different things.

To make it clear, lets see an example: In american keyboard, the 16 value is the key code for Shift and the 59 value is the key code for the key ":;". So, in this scenario, to send ':' to the operational system, you should use key code 56. To send ';' you should send 16 + 56 as a combination (pressed together). 

In languages that have accents (for example: portuguese and spanish), usually more than one key must be pressed one after another to make the letter with an accent. So 'õ' is the result of sending '~' and 'o'.

While you can send the key codes as numbers, the lib also have labels mapped for most of the keys. So, for key A you may send 'a' or 65. For Shift key you may send 'shift' or 16.

It is possible to change this mapping to convert accents automatically (if you are using a keyboard that supports it). Later in this doc I show how to do that.

Note that key codes may vary according to your running physical keyboard model, keyboard driver and operational system.

# Usage

Sending one key:

    var ks = require('node-key-sender');
    ks.sendKey('a');

Send multiple keys one after the other:

    var ks = require('node-key-sender');
    ks.sendKeys(['a', 'b', 'c']);

Send combination (pressed at the same time):

    var ks = require('node-key-sender');
    ks.sendCombination(['control', 'shift', 'v']);

Mapping accents:

    var accentsMap = {
        'ã': '@514 a',
        'ẽ': '@514 e',
        'ĩ': '@514 i',
        'õ': '@514 o',
        'ũ': '@514 u',
        'Ã': '@514 A',
        'Ẽ': '@514 E',
        'Ĩ': '@514 I',
        'Õ': '@514 O',
        'Ũ': '@514 U',
        'â': 'shift-@514 a',
        'ê': 'shift-@514 e',
        'î': 'shift-@514 i',
        'ô': 'shift-@514 o',
        'û': 'shift-@514 u',
        'Â': 'shift-@514 A',
        'Ê': 'shift-@514 E',
        'Î': 'shift-@514 I',
        'Ô': 'shift-@514 O',
        'Û': 'shift-@514 U',
        'à': 'shift-@192 a',
        'è': 'shift-@192 e',
        'ì': 'shift-@192 i',
        'ò': 'shift-@192 o',
        'ù': 'shift-@192 u',
        'À': 'shift-@192 A',
        'È': 'shift-@192 E',
        'Ì': 'shift-@192 I',
        'Ò': 'shift-@192 O',
        'Ù': 'shift-@192 U',
        'á': '@192 a',
        'é': '@192 e',
        'í': '@192 i',
        'ó': '@192 o',
        'ú': '@192 u',
        'Á': '@192 A',
        'É': '@192 E',
        'Í': '@192 I',
        'Ó': '@192 O',
        'Ú': '@192 U',
        'ç': '@192 c',
        'Ç': '@192 C',
        'ä': 'shift-@54 a',
        'ë': 'shift-@54 e',
        'ï': 'shift-@54 i',
        'ö': 'shift-@54 o',
        'ü': 'shift-@54 u',
        'Ä': 'shift-@54 A',
        'Ë': 'shift-@54 E',
        'Ï': 'shift-@54 I',
        'Ö': 'shift-@54 O',
        'Ü': 'shift-@54 O'
    };
    
    var ks = require('node-key-sender');
    ks.aggregateKeyboardLayout(accentsMap);
    ks.sendText("Héllõ Wíth Áçcents");

Sending batch:

    var ks = require('node-key-sender');

    ks.startBatch()
        .batchTypeKey('N')
        .batchTypeKey('o')
        .batchTypeKey('d')
        .batchTypeKey('e')
        .batchTypeKeys(['N', 'o', 'd', 'e'])
        .batchTypeText('Node')
        .batchTypeKey('N', 1000)
        .batchTypeKey('o', 1000)
        .batchTypeKey('d', 1000)
        .batchTypeKey('e', 1000)
        .sendBatch();

Setting global press delay (in milliseconds):

    ks.setOption('globalDelayPressMillisec', 1000);
    
Setting global delay between keys (in milliseconds):

    ks.setOption('globalDelayBetweenMillisec', 1000);
    
Setting start delay (in milliseconds):

    ks.setOption('startDelayMillisec', 1000);
    
Turning off case correction:

    ks.setOption('caseCorrection', false);
    
# List of methods

## Economic methods

Use this methods if you want to send just a small amount of keys. Note that the jar file is called each time one of these methods are called:  

**sendKey(keyCode: string): Promise**

Sends one key code.

**sendKeys(arrKeyCodes: array): Promise**

Sends multiple key codes.

**sendLetter(letter: char): Promise**

Sends a letter. A letter will be automatically converted to key code according to the keyboard layout configuration. You may set this configuration with `cleanKeyboardLayout`, `setKeyboardLayout` or `aggregateKeyboardLayout`.

**sendText(text: string): Promise**

Sends a text. A text will have its letters automatically converted to key codes according to the keyboard layout configuration. You may set this configuration with `cleanKeyboardLayout`, `setKeyboardLayout` or `aggregateKeyboardLayout`.

**sendCombination(arrKeyCodes: array): Promise**

Sends multiple key codes pressed together.

## Batch methods

Use this methods to send a large amount of keys. The jar file is executed each time you call `sendBatch`. You should start with `startBatch` and end with `sendBatch`:
 
**startBatch()**
 
Starts a batch.

**sendBatch(): Promise**

Sends the batch.

**batchTypeKey(keyCode: string, waitMillisec: int, batchEvent: int)**

Sends a key code. You may pass a delay it will wait until it presses the next key and also the type of event. Type of event is `ks.BATCH_EVENT_KEY_PRESS`, `ks.BATCH_EVENT_KEY_UP` and `ks.BATCH_EVENT_KEY_DOWN`.

**batchTypeKeys(arrKeyCodes: array)**

Sends a list of key codes, pressed one after the other.

**batchTypeCombination(arrKeys: array, waitMillisec: int, batchEvent: int)**

Sends a combination - list of key codes that will be pressed together. You may pass a delay it will wait until it presses the next key and also the type of event. Type of event is `ks.BATCH_EVENT_KEY_PRESS`, `ks.BATCH_EVENT_KEY_UP` and `ks.BATCH_EVENT_KEY_DOWN`.

**batchTypeText(text: string)**

Sends a text. A text will have its letters automatically converted to key codes according to the keyboard layout configuration. You may set this configuration with `cleanKeyboardLayout`, `setKeyboardLayout` or `aggregateKeyboardLayout`.


## Keyboard layout methods

Keyboard layout methods affects translation of letter to key code. They affect `sendLetter`, `sendText`, `batchTypeText` and `getKeyCode` methods. 

**cleanKeyboardLayout(): void**

Resets the keyboard layout configuration.

**setKeyboardLayout(newKeyMap: object): void**

Sets a new keyboard layout. For example:

    var keyboardLayout = {
        'ç': '@192 c',
        'Ç': '@192 C'
    };
        
    var ks = require('node-key-sender');
    ks.aggregateKeyboardLayout(keyboardLayout);
    ks.sendText("Ç");

This keyboard layout converts letter 'Ç' to key codes '@192' and 'C'.
 
**aggregateKeyboardLayout(objKeyMap: object): void**

Appends the new mapping to the current mapping.

**getKeyboardLayout(): object**

Returns the current keyboard layout.


## Other methods

**getKeyCode(letter: string)**

Gets the key code of a letter. A letter will be automatically converted to key code according to the keyboard layout configuration. You may set this configuration with `cleanKeyboardLayout`, `setKeyboardLayout` or `aggregateKeyboardLayout`.

**setOption(optionName: string, optionValue: string)**

Options that are passed as arguments to the jar. This is the list of valid options names:

- startDelayMillisec (int): Delay in milliseconds it will wait to press the first key.
- globalDelayPressMillisec (int): Global delay in milliseconds it will keep the key pressed.
- globalDelayBetweenMillisec (int): Global delay in milliseconds it will wait until it presses the next key.
- caseCorrection (boolean): When it is on, if you send key 'A' (in upper case), the jar will automatically hold Shift, so resulting key is 'A'.
- extra (string): Use may use it to send raw arguments to the jar file. Example: ' -c 1 -d 1000'.

**execute(arrParams: array): Promise**

Use this method if you want to directly call the jar file.

## Promises

Some methods of this lib returns a promise:

    ks.sendKey('a').then(
        function(stdout, stderr) {
            // For success
        },        
        function(error, stdout, stderr) {
            // For error
        }
    );

The promise is resolved or rejected right after the jar finishes its execution.  

List of methods that returns this promise: `sendCombination`, `sendKey`, `sendKeys`, `sendLetter`, `sendText`, `execute`, `sendBatch`.


# List of key codes

We recommend you search for key codes in the Java [java.awt.event.KeyEvent](https://docs.oracle.com/javase/7/docs/api/java/awt/event/KeyEvent.html) class doc. The key codes are the constants starting with "VK_". To use it with this lib, just take out these three letters and you can use the rest of the constant name in lowercase. For example, VK_SHIFT constant you use "shift". VK_A constant you use 'a'. The constant numerical value can also be used with an "@" in the beginning. So "@16" for VK_SHIFT and "@65" for VK_A.

Use this website to get an idea of what key code is bound to each key of your current keyboard: https://www.w3.org/2002/09/tests/keys.html.

Below, the list of key codes:

| Keyboard key | Label key code | Numerical key code |
|---|---|---|
| Enter | "enter" | "@10" |
| Backspace | "back_space" | "@8" |
| Tab | "tab" | "@9" |
| Shift | "shift" | "@16" |
| Control | "control" | "@17" |
| Alt | "alt" | "@18" |
| Pause | "pause" | "@19" |
| Caps Lock | "caps_lock" | "@20" |
| Esc | "escape" | "@27" |
| Space | "space" | "@32" |
| Page Up | "page_up" | "@33" |
| Page Down | "page_down" | "@34" |
| End | "end" | "@35" |
| Home | "home" | "@36" |
| Left | "left" | "@37" |
| Up | "up" | "@38" |
| Right | "right" | "@39" |
| Down | "down" | "@40" |
| Comma | "comma" | "@44" |
| Minus | "minus" | "@45" |
| Period | "period" | "@46" |
| Slash | "slash" | "@47" |
| 0 | "0" | "@48" |
| 1 | "1" | "@49" |
| 2 | "2" | "@50" |
| 3 | "3" | "@51" |
| 4 | "4" | "@52" |
| 5 | "5" | "@53" |
| 6 | "6" | "@54" |
| 7 | "7" | "@55" |
| 8 | "8" | "@56" |
| 9 | "9" | "@57" |
| Semicolon | "semicolon" | "@59" |
| Equals | "equals" | "@61" |
| A | "a" | "@65" |
| B | "b" | "@66" |
| C | "c" | "@67" |
| D | "d" | "@68" |
| E | "e" | "@69" |
| F | "f" | "@70" |
| G | "g" | "@71" |
| H | "h" | "@72" |
| I | "i" | "@73" |
| J | "j" | "@74" |
| K | "k" | "@75" |
| L | "l" | "@76" |
| M | "m" | "@77" |
| N | "n" | "@78" |
| O | "o" | "@79" |
| P | "p" | "@80" |
| Q | "q" | "@81" |
| R | "r" | "@82" |
| S | "s" | "@83" |
| T | "t" | "@84" |
| U | "u" | "@85" |
| V | "v" | "@86" |
| W | "w" | "@87" |
| X | "x" | "@88" |
| Y | "y" | "@89" |
| Z | "z" | "@90" |
| Open bracket | "open_bracket" | "@91" |
| Numpad 0 | "numpad0" | "@96" |
| Numpad 1 | "numpad1" | "@97" |
| Numpad 2 | "numpad2" | "@98" |
| Numpad 3 | "numpad3" | "@99" |
| Numpad 4 | "numpad4" | "@100" |
| Numpad 5 | "numpad5" | "@101" |
| Numpad 6 | "numpad6" | "@102" |
| Numpad 7 | "numpad7" | "@103" |
| Numpad 8 | "numpad8" | "@104" |
| Numpad 9 | "numpad9" | "@105" |
| Multiply | "multiply" | "@106" |
| Add | "add" | "@107" |
| Subtract | "subtract" | "@109" |
| Decimal | "decimal" | "@110" |
| Divide | "divide" | "@111" |
| Delete | "delete" | "@127" |
| Num Lock | "num_lock" | "@144" |
| Scroll Lock | "scroll_lock" | "@145" |
| F1 | "f1" | "@112" |
| F2 | "f2" | "@113" |
| F3 | "f3" | "@114" |
| F4 | "f4" | "@115" |
| F5 | "f5" | "@116" |
| F6 | "f6" | "@117" |
| F7 | "f7" | "@118" |
| F8 | "f8" | "@119" |
| F9 | "f9" | "@120" |
| F10 | "f10" | "@121" |
| F11 | "f11" | "@122" |
| F12 | "f12" | "@123" |
| F13 | "f13" | "@61440" |
| F14 | "f14" | "@61441" |
| F15 | "f15" | "@61442" |
| F16 | "f16" | "@61443" |
| F17 | "f17" | "@61444" |
| F18 | "f18" | "@61445" |
| F19 | "f19" | "@61446" |
| F20 | "f20" | "@61447" |
| F21 | "f21" | "@61448" |
| F22 | "f22" | "@61449" |
| F23 | "f23" | "@61450" |
| F24 | "f24" | "@61451" |
| Print Screen | "print_screen" | "@154" |
| Insert | "insert" | "@155" |
| Help | "help" | "@156" |
| Meta | "meta" | "@157" |
| Block Quote | "block_quote" | "@192" |
| Quote | "quote" | "@222" |
| Numeric Key Pad Up | "kp_up" | "@224" |
| Numeric Key Pad Down | "kp_down" | "@225" |
| Numeric Key Pad Left | "kp_left" | "@226" |
| Numeric Key Pad Right | "kp_right" | "@227" |
| Grave accent | "dead_grave" | "@128" |
| Acute accent | "dead_acute" | "@129" |
| Circumflex accent | "dead_circumflex" | "@130" |
| Tilde accent | "dead_tilde" | "@131" |
| Macron accent | "dead_macron" | "@132" |
| Breve accent | "dead_breve" | "@133" |
| Above dot accent | "dead_abovedot" | "@134" |
| Diaeresis accent | "dead_diaeresis" | "@135" |
| Abovering accent | "dead_abovering" | "@136" |
| Double acute accent | "dead_doubleacute" | "@137" |
| Caron accent | "dead_caron" | "@138" |
| Cedilla accent | "dead_cedilla" | "@139" |
| Ogonek accent | "dead_ogonek" | "@140" |
| Iota accent | "dead_iota" | "@141" |
| Voiced sound accent | "dead_voiced_sound" | "@142" |
| Semi voiced sound accent | "dead_semivoiced_sound" | "@143" |
| Ampersand | "ampersand" | "@150" |
| Asterisk | "asterisk" | "@151" |
| Double quote | "quotedbl" | "@152" |
| Less | "less" | "@153" |
| Greater | "greater" | "@160" |
| Brace left | "braceleft" | "@161" |
| Brace right | "braceright" | "@162" |
| At | "at" | "@512" |
| Colon | "colon" | "@513" |
| Circumflex | "circumflex" | "@514" |
| Dollar | "dollar" | "@515" |
| Euro Sign | "euro_sign" | "@516" |
| Exclamation Mark | "exclamation_mark" | "@517" |
| Inverted exclamation mark | "inverted_exclamation_mark" | "@518" |
| Left parenthesis | "left_parenthesis" | "@519" |
| Right parenthesis | "right_parenthesis" | "@522" |
| Number sign | "number_sign" | "@520" |
| Plus | "plus" | "@521" |
| Underscore | "underscore" | "@523" |
| Windows | "windows" | "@524" |
| Context menu | "context_menu" | "@525" |
| Japanese PC 106 henkan | "convert" | "@28" |
| Japanese PC 106 muhenkan | "nonconvert" | "@29" |
| Japanese PC 106 eisu | "alphanumeric" | "@240" |
| Japanese PC 106 katakana | "katakana" | "@241" |
| Japanese PC 106 hiragana | "hiragana" | "@242" |
| Japanese PC 106 zenkaku | "full_width" | "@243" |
| Japanese PC 106 hankaku | "half_width" | "@244" |
| Japanese PC 106 rouman-ji | "roman_characters" | "@245" |
| Japanese PC 106 zenkouho | "all_candidates" | "@256" |
| Japanese PC 106 maekouho | "previous_candidate" | "@257" |
| Japanese PC 106 kanji bangou | "code_input" | "@258" |
| Japanese PC 106 kana lock | "kana_lock" | "@262" |
| Japanese PC 106 nihongo | "input_method_on_off" | "@263" |
| Japanese Solaris kakutei | "accept" | "@30" |
| Japanese Solaris kana lock | "kana" | "@21" |
| Japanese kanji  | "kanji" | "@25" |
| Japanese Macintosh katakana | "japanese_katakana" | "@259" |
| Japanese Macintosh hiragana | "japanese_hiragana" | "@260" |
| Japanese Macintosh rouman-ji | "japanese_roman" | "@261" |
| Sun cut | "cut" | "@65489" |
| Sun copy | "copy" | "@65485" |
| Sun paste | "paste" | "@65487" |
| Sun undo | "undo" | "@65483" |
| Sun again | "again" | "@65481" |
| Sun find | "find" | "@65488" |
| Sun props | "props" | "@65482" |
| Sun stop | "stop" | "@65480" |
| Compose | "compose" | "@65312" |
| Alt GR | "alt_graph" | "@65406" |

Note that this is an incomplete list and that the key code may vary according to your physical keyboard, keyboard driver and operational system.