Press

3.1.8 Press

DESCRIPTION

Press - Send a key to the desktop. It is analogical to pressing a key on the keyboard.

SYNOPSIS

* Red colour indicates obligatory parameters

OPTIONS

key

- Name of the keyboard key to press. Most key names correspond to what is written on the keyboard, e.g. 'A', 'Insert', 'Tab' etc. The key may also consist of modifiers only. Keys are not case sensitive and may be specified in any character case.

Key names are internally derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string after the VK_ prefix. For example, as there is a VK_ENTER constant, the key name may be "ENTER", "Enter" or "enter". As the names are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute T-Plan Robot. A complete map of the supported key names may be obtained through the Supported Keys Window.

The key may be optionally preceded by any combination of the Shift, Alt and Ctrl modifiers separated by the plus '+' sign, for example, "Ctrl+Alt+Delete". Modifier names are not case sensitive.

Be aware that the names map rather to particular physical keys and not to the characters they represent. For example, the pressing of the standard '-' minus key generates a different internal keycode than the one on numpad. These two cases may be also represented by two Press commands, "Press -" (standard) and "Press SUBTRACT location=numpad" (numpad). In most cases, the target system interprets them in the same way but there may be situations when it fails. For example, control plus ("Press Ctrl++") is generated as a sequence of \[press Ctrl, press '+', release '+', release Ctrl\]. As such a key combination is impossible to create on a US keyboard where one needs to press Shift as well to get the standard '+' ASCII character (0x2b), this sequence may or may not be interpreted correctly by the desktop. If the key is not recognized try using the numpad one instead ("Press Ctrl+ADD location=numpad"). To get the key name for your particular Numpad key open the Supported Keys Window and press it while the focus is on the "Press a key.." text field. It is recommended to specify the location=numpad parameter though it may also work without it.

The command accepts besides key names also most plain ASCII characters since 2.0.3. It is possible to use commands like "Press * " or "Press @". In addition, it supports the mapping of these characters onto the numeric keyboard through the localion="numpad" parameter. For example, pressing of the "0" key on the numeric keypad required to call "Press NUMPAD0" while the new version also supports more intuitive "Press 0 location=numpad". This also applies to other numpad keys such as ADD (mapped to plus, '+'), SUBTRACT (minus, '-'), MULTIPLY (asterisk, '*' ), DIVIDE (slash, '/'), DECIMAL (period, '.') and SEPARATOR (comma ',' ).

Transferable keys and key combinations are further on subject to limitations applied by the desktop client (protocol). For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set and support of Windows native keys such as Win and ContextMenu is supported just by some products. On the contrary, the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to. Read the Release Notes and particular client documentation for more information.

location=<standard|numpad|left|right>

- Key location. This option makes sense only with keys which are present on a typical keyboard more than once. Examples of such keys are the digit keys '0'-'9' (standard location and num pad) or modifier keys (Ctrl and Alt on the keyboard left and right). Supported location values are standard (default), numpad, left and right. Note that the command doesn't verify whether the \[key,location\] pair makes sense. For example, alphabet characters are present on most keyboards just once and the only logically valid location is the default standard one. Most clients, however, use the location only as a hint and ignore it by keys where it is not applicable.

release=<true|false>

- Supported since 2.3.4. When this parameter is present the command performs just a keypress (release=false) or a key release (release=true) instead of the full pres-release sequence. This allows to automate long keypresses and/or composed press and mouse events. If you use this parameter to simulate a press make sure that you release the key properly when it is not needed any more.

count=<number>

- How many times the key should be sent. The default value is 1. Delays among multiple press actions are defined by a value in the Press Command user preferences.

wait=<time>

- Time to wait after the events are sent. This parameter is useful if the server needs some time to react on the pressed key/keys. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _PRESS_WAIT variable with the desired delay, for example "Var _PRESS_WAIT=1s".

RETURNS
The command returns 0 (zero) on success or 1 when it fails.

EXAMPLES
Press Ctrl+Alt+Del

- Press the Ctrl+Alt+Del key on the desktop.

Press Tab count=5 wait=2s

- Simulate pressing of the Tab key five times and then wait for two seconds before proceeding to the next command.

Press Ctrl location=right

- Press the right Ctrl key.

Var KEY_TO_PRESS=Alt+F4 <...> Waitfor update area=x:340,y:220,w:240,h:160 extent=80% timeout=10s ontimeout="Var KEY_TO_PRESS=Right" Press {KEY_TO_PRESS} wait=2s

- This example illustrates how to solve unwanted popup windows. If a window pops up at the given coordinates, the 'Press {KEY_TO_PRESS}' command ensures that it gets closed using Alt+F4. If the window doesn't show up, the Alt key gets pressed which usually doesn't cause any harm to the window.