Keyboard
Edit on GitHub| S | Return | Name | Parameters |
|---|---|---|---|
| Keyboard | (void) | ||
| void | Click | (Key keycode) const | |
| void | Press | (Key keycode) const | |
| void | Release | (Key keycode) const | |
| bool | Click | (const char* keys) const | |
| ✔ | bool | Compile | (const char* keys, KeyList& result) |
| ✔ | bool | GetState | (Key keycode) |
| ✔ | bool | GetState | (KeyState& result ) |
| Range | AutoDelay |
Description
Provides a simple interface for generating native keyboard events on the system. These events can be used for the purposes of test automation, self-running demos, and other applications where control of the keyboard is needed. Certain platforms require special privileges or extensions to access low-level keyboard controls. If the current platform configuration does not allow this, most of the functionality in the class will perform no operation or return otherwise invalid data. As an example, Linux depends on XTest 2.2 to carry out the majority of the low-level functionality, when missing, the class will not work.
Although keyboard events are system-wide, a keyboard object must still be created through the Constructor in order to support multiple auto delays. Once created, use the Press and Release functions to generate keyboard key press and release events. Use the Click function to generate both a press, followed by a release. Use the other Click function to produce multiple click events as specified by the input string. All these functions will block after generating an event, the amount of time blocked can be configured through the AutoDelay property.
The Keyboard class also offers a variety of non-blocking static functions. For instance, the compiler which transforms the input string for Click into basic click events is exposed through the Compile function. Additionally, the current down-state of one of more keyboard keys can be retrieved through the GetState functions.
Types
typedef vector<pair <bool, Key>> Robot::KeyList;
typedef unordered_map<Key, bool> Robot::KeyState;
Constructors
| Keyboard | (void) |
Constructs a keyboard with an AutoDelay between 40 and 90 milliseconds.
Functions
| void | Click | (Key keycode) const |
Presses and then releases keycode, blocking at each step.
| void | Press | (Key keycode) const |
| void | Release | (Key keycode) const |
Presses or releases a single keyboard key and blocks for AutoDelay milliseconds. The value of keycode can be any valid Key. Passing a keycode which is not part of the Key enumeration is supported, as long as the correct platform-dependent constant is used. A pressed key should always be released. Pressing or releasing the same key multiple times is not always guaranteed to generate respective press or release events on the target platform.
| bool | Click | (const char* keys) const |
Performs Press and Release functions on the data resulting from the compilation of keys. If the syntax of keys is incorrect or the compilation fails, this function will return false.
| static | bool | Compile | (const char* keys, KeyList& result) |
Compiles keys into a list of pairs describing the key and whether it should be pressed (or released if false). The list is saved into result, which will be cleared prior to compilation. However, if keys is null, this function will return false immediately, without clearing result. If the syntax of keys is correct and the compilation succeeds, this function will return true.
keys expects a string of case-insensitive codes representing keys, as illustrated by the table below. Codes consisting of single characters may be specified directly, one after the other. For example, setting keys to "abc" will compile into clicking a, b and then c, in that order. Codes longer than one character must be wrapped in curly braces: {left}, {tab}. Curly braces can also be used to specify the number of times a key should be repeated, up to a maximum of 99 times: {left 4}, {tab 2}. Uppercase and and other "shift-based" keys such as ampersand and double quotes must be prefaced with the shift modifier. Modifiers can be specified with special codes:
| Modifier | Code |
|---|---|
| ALT | % |
| CONTROL | ^ |
| SHIFT | + |
| SYSTEM | $ |
As an example, "+a" will compile into pressing and holding shift, clicking a and then releasing shift. To apply modifiers to multiple keys at once, specify the desired modifier followed by one or more codes within parentheses. For example, setting keys to "+(ab^c)" or "+(ab^(c))" will compile into pressing and holding shift, followed by clicking a and b, followed by pressing and holding control, followed by clicking c and then releasing both control and shift, in that order. Whitespace characters including \t, \n, \v, \f and \r are automatically ignored by the compiler.
| Key | Code |
|---|---|
| KeySpace | { } |
| KeySpace | {SPACE} |
| KeySpace | {SPC} |
| KeyEscape | {ESCAPE} |
| KeyEscape | {ESC} |
| KeyTab | {TAB} |
| KeyAlt | {ALT} |
| KeyLAlt | {LALT} |
| KeyRAlt | {RALT} |
| KeyControl | {CONTROL} |
| KeyLControl | {LCONTROL} |
| KeyRControl | {RCONTROL} |
| KeyControl | {CTRL} |
| KeyLControl | {LCTRL} |
| KeyRControl | {RCTRL} |
| KeyShift | {SHIFT} |
| KeyLShift | {LSHIFT} |
| KeyRShift | {RSHIFT} |
| KeySystem | {SYSTEM} |
| KeyLSystem | {LSYSTEM} |
| KeyRSystem | {RSYSTEM} |
| KeyF1 | {F1} |
| KeyF12 | {F12} |
| Key0 | {0} |
| Key9 | {9} |
| KeyA | {A} |
| KeyZ | {Z} |
| KeyGrave | {`} |
| KeyMinus | {-} |
| KeyEqual | {=} |
| KeyBackspace | {<} |
| KeyLBracket | {[} |
| KeyRBracket | {]} |
| KeyBackslash | {} |
| KeySemicolon | {;} |
| KeyQuote | {'} |
| KeyReturn | {~} |
| KeyComma | {,} |
| KeyPeriod | {.} |
| KeySlash | {/} |
| KeyGrave | {GRAVE} |
| KeyMinus | {MINUS} |
| KeyEqual | {EQUAL} |
| KeyBackspace | {BACKSPACE} |
| KeyBackspace | {BS} |
| KeyLBracket | {LBRACKET} |
| KeyRBracket | {RBRACKET} |
| KeyBackslash | {BACKSLASH} |
| KeySemicolon | {SEMICOLON} |
| KeyQuote | {QUOTE} |
| KeyReturn | {RETURN} |
| KeyComma | {COMMA} |
| KeyPeriod | {PERIOD} |
| KeySlash | {SLASH} |
| KeyLeft | {LEFT} |
| KeyUp | {UP} |
| KeyRight | {RIGHT} |
| KeyDown | {DOWN} |
| KeyPrint | {PRINT} |
| KeyPause | {PAUSE} |
| KeyPause | {BREAK} |
| KeyInsert | {INSERT} |
| KeyInsert | {INS} |
| KeyDelete | {DELETE} |
| KeyDelete | {DEL} |
| KeyHome | {HOME} |
| KeyEnd | {END} |
| KeyPageUp | {PAGEUP} |
| KeyPageUp | {PGUP} |
| KeyPageDown | {PAGEDOWN} |
| KeyPageDown | {PGDN} |
| KeyAdd | {NUM+} |
| KeySubtract | {NUM-} |
| KeyMultiply | {NUM*} |
| KeyDivide | {NUM/} |
| KeyDecimal | {NUM.} |
| KeyEnter | {NUM~} |
| KeyAdd | {ADD} |
| KeySubtract | {SUBTRACT} |
| KeyMultiply | {MULTIPLY} |
| KeyDivide | {DIVIDE} |
| KeyDecimal | {DECIMAL} |
| KeyEnter | {ENTER} |
| KeyNum0 | {NUM0} |
| KeyNum9 | {NUM9} |
| KeyCapsLock | {CAPSLOCK} |
| KeyScrollLock | {SCROLLLOCK} |
| KeyNumLock | {NUMLOCK} |
| static | bool | GetState | (Key keycode) |
Returns true if keycode is currently pressed system-wide, regardless of whether or not the calling application has focus. The value of keycode can be any valid Key. Passing a keycode which is not part of the Key enumeration will also cause this function to return false. If two of more key states need to be checked, consider using the other GetState function for improved performance.
| static | bool | GetState | (KeyState& result ) |
Checks the pressed state of all keys system-wide, regardless of whether or not the calling application has focus. If an error occurs, this function will return false, however, result will always be cleared regardless of whether or not this function succeeds. If only one key state needs to be checked, consider using the other GetState function for improved performance.
Properties
| Range | AutoDelay |
Provides direct access to the automatic delay range in milliseconds.
Key
Represents the keyboard keys supported by this class. These keys map to platform-dependent values. On Linux, keys map to the XK_* series of constants which get translated into key codes with XKeysymToKeycode. On Mac, keys map to the kVK_* series of constants, as defined by CGKeyCode. On Windows, keys map to the standard VK_* series of constants.
enum Key
{
KeySpace,
KeyEscape,
KeyTab,
KeyAlt, KeyControl,
KeyLAlt, KeyLControl,
KeyRAlt, KeyRControl,
KeyShift, KeySystem,
KeyLShift, KeyLSystem,
KeyRShift, KeyRSystem,
KeyF1, KeyF2, KeyF3,
KeyF4, KeyF5, KeyF6,
KeyF7, KeyF8, KeyF9,
KeyF10, KeyF11, KeyF12,
Key0, Key1, Key2, Key3,
Key4, Key5, Key6, Key7,
Key8, Key9,
KeyA, KeyB, KeyC, KeyD,
KeyE, KeyF, KeyG, KeyH,
KeyI, KeyJ, KeyK, KeyL,
KeyM, KeyN, KeyO, KeyP,
KeyQ, KeyR, KeyS, KeyT,
KeyU, KeyV, KeyW, KeyX,
KeyY, KeyZ,
KeyGrave,
KeyMinus,
KeyEqual,
KeyBackspace,
KeyLBracket,
KeyRBracket,
KeyBackslash,
KeySemicolon,
KeyQuote,
KeyReturn,
KeyComma,
KeyPeriod,
KeySlash,
KeyLeft,
KeyUp,
KeyRight,
KeyDown,
KeyPrint,
KeyPause,
KeyInsert,
KeyDelete,
KeyHome,
KeyEnd,
KeyPageUp,
KeyPageDown,
KeyAdd,
KeySubtract,
KeyMultiply,
KeyDivide,
KeyDecimal,
KeyEnter,
KeyNum0, KeyNum1, KeyNum2,
KeyNum3, KeyNum4, KeyNum5,
KeyNum6, KeyNum7, KeyNum8,
KeyNum9,
KeyCapsLock,
KeyScrollLock,
KeyNumLock,
};
Examples
// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;
int main (void)
{
Keyboard keyboard;
// Type a capital H character
keyboard.Press (KeyShift);
keyboard.Click (KeyH );
keyboard.Release (KeyShift);
// Change default auto delay
keyboard.AutoDelay.Min = 100;
keyboard.AutoDelay.Max = 200;
// Finish typing the fancy "Hello ROBOT!"
keyboard.Click ("ELLO +Robo<<<+(obot)+1");
KeyState s;
while (true)
{
// Press the H and R
// keys to exit loop
Keyboard::GetState (s);
if (s[KeyH] && s[KeyR])
break;
// Avoid busy wait
Timer::Sleep (15);
}
return 0;
}
// Node
var robot = require ("robot-js");
var keyboard = robot.Keyboard();
// Type a capital H character
keyboard.press (robot.KEY_SHIFT);
keyboard.click (robot.KEY_H );
keyboard.release (robot.KEY_SHIFT);
// Change default auto delay
keyboard.autoDelay.min = 100;
keyboard.autoDelay.max = 200;
// Finish typing the fancy "Hello ROBOT!"
keyboard.click ("ELLO +Robo<<<+(obot)+1");
while (true)
{
// Press H and R keys to exit loop
var s = robot.Keyboard.getState();
if (s[robot.KEY_H] && s[robot.KEY_R])
break;
// Avoid busy waiting
robot.Timer.sleep (15);
}