Keys Method

Applies to TestComplete 14.71, last modified on April 22, 2021

Description

Keys both enters the string specified at the “keyboard” for the active window, and inserts an Executing keys event into the test log.

Declaration

TestObj.Keys(Keys)

TestObj A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
Keys [in]    Required    String    
Result None

Applies To

The method is applied to the following objects:

View Mode

This method is available in the Object Browser panel and in other panels and dialogs in both Basic and Advanced view modes.

Parameters

The method has the following parameter:

Keys

Specifies the keystroke to be simulated.

To simulate the pressing of system keys, such as Ctrl, Alt, Shift, F1, Tab and others, use the following constants:

Constant Simulated Key
^ Ctrl
! Shift
~ Alt
^^ ^
!! !
~~ ~
[[ [
[Apps] Application key
[BS] Backspace
[Caps] Caps Lock
[Clear] Clear
[Del] Delete
[Down] Down
[End] End
[Enter] Enter
[Esc] Esc
[F1] F1
[F2] F2
[F3] F3
[F4] F4
[F5] F5
[F6] F6
[F7] F7
[F8] F8
[F9] F9
[F10] F10
[F11] F11
[F12] F12
Constant Simulated Key
[Home] Home
[Ins] Insert
[Left] Left
[NumAsterisk] Num * (* on the numeric keyboard)
[NumLock] Num Lock
[NumMinus] Num - (- on the numeric keyboard)
[NumPlus] Num + (+ on the numeric keyboard)
[NumSlash] Num / (/ on the numeric keyboard)
[PageDown] PageDown
[PageUp] PageUp
[Pause] Pause
[PrtSc] PrintScreen
[Right] Right
[ScrollLock] Scroll Lock
[Tab] Tab
[Up] Up
[Win] Windows key
[Pnnn] Pauses typing for nnn milliseconds.
[Xnn] Specifies a key by its virtual-key code. nn is the decimal virtual-key code of the desired key. For example, [X107] corresponds to the Num Plus key. To learn more about virtual-key codes, see the Virtual-Key Codes article in the MSDN Library.

If the Win32API plugin is installed and enabled in TestComplete, you can refer to the virtual-key codes using the corresponding VK_xxxx constants without the need to define them in your tests. For example, you can use the VK_ADD constant to specify the Num Plus key. The available VK_xxxx constants are listed under the Win32API node in the Code Completion window.

[Dnn] Presses a dead key specified by its key code nn.
[Altnn…] Simulates pressing Alt and typing numeric keys on the numeric keypad (that is, Alt+the character code). nn… is a sequence of numeric keys to be pressed, for instance, [Alt119] will simulate pressing Alt and typing the 1, 1 and 9 keys on the numeric keypad.
All constants (F1, PageDown, X, P, etc.) are case-sensitive.

Shift codes (^, ~ and !) in the Keys parameter do not press Ctrl, Alt or Shift. Instead, the next key in the string will be pressed under the indicated shift conditions. That is, the shift codes influence on the first non-shift key that follows them in the Keys string. For instance, the following code presses Ctrl+ESC (this shortcut shows the Start menu):

JavaScript, JScript

Obj.Keys("^[Esc]");

Python

Obj.Keys("^[Esc]")

VBScript

Obj.Keys "^[Esc]"

DelphiScript

Obj.Keys('^[Esc]');

C++Script, C#Script

Obj["Keys"]("^[Esc]");

To separate shift-key presses from combined key presses like the above, use two consecutive calls of the Keys method. For example, the following code first presses Ctrl and then ESC (this operation does not call the Start menu, since the key presses are separated). Another way to achieve this effect is to use the [Release] constant (more below).

JavaScript, JScript

Obj.Keys("^");
Obj.Keys("[Esc]");

Python

Obj.Keys("^")
Obj.Keys("[Esc]")

VBScript

Obj.Keys "^"
Obj.Keys "[Esc]"

DelphiScript

Obj.Keys('^');
Obj.Keys('[Esc]');

C++Script, C#Script

Obj["Keys"]("^");
Obj["Keys"]("[Esc]");

To simulate simultaneous pressing of several keys, use the [Hold] constant. For instance, [Hold][Win]e will launch Windows Explorer.

To deactivate [Hold], use the [Release] and [ReleaseLast] constants. [ReleaseLast] signals to TestComplete that it should simulate the releasing of the last pressed key. For instance, the string [Hold]^f[ReleaseLast]U indicates the following sequence of keypresses: pressing of Ctrl, pressing of f, releasing of f, pressing of U, releasing of U and Ctrl.

[Release] simulates the release of all pressed keys. For example, the string [Hold]^fU[Release] (or [Hold]^fU) indicates that TestComplete should press Ctrl, then press f, then press U and then release all these keys.

You can also simulate a keystroke using virtual-key code of the desired character. To do this, use the X or D tags. X simulates pressing of a key with the specified code using the current keyboard layout. D is typically used for simulating dead-key characters (accent or diacritic). This feature is especially useful if you need to type some national characters (for instance, a with circumflex). When the Keys method finds the D tag, it checks whether the specified key is supported by keyboard layouts installed in the operating system. If the check is successful, the method switches the keyboard layout to the appropriate layout and then simulates the keystroke. Else, the tag is ignored.

The X and D tags can be used along with Ctrl, Alt and Shift constants. For instance, [D221]a will simulate a with circumflex, [D221]!a - A with circumflex.

Result Value

None.

Remarks

  • To simulate capital letters in the string passed through the Keys parameter, the Keys method “presses” Shift tacitly. That is, the simulation of tEst is performed by keystrokes of the following: t, Shift-e, s and t.

  • The keystroke simulation ignores the current state of Caps Lock. The method “types” the text as it is specified by the Keys parameter regardless of whether the Caps Lock mode is active or not. For instance, if you pass the string Test and Caps Lock is active, the method will simulate typing of the string Test rather than TEST.

  • TestComplete recognizes native-language characters in the Keys string and automatically changes the keyboard layout in order to simulate the typing of these characters. In order for TestComplete to be able to switch layouts, the appropriate keyboard layout must be installed in the system. If the required layout is not installed, the keystrokes simulations will be incorrect.

    To force the system to change the keyboard layout for a process, use the aqEnvironment.SetKeyboardLayout method.

    To obtain the identifier of the keyboard layout that is currently set for a window, use the aqEnvironment.GetKeyboardLayout method.

  • TestComplete uses a slower keystroke simulation speed for controls that reside on web pages shown in Internet Explorer. For more information on this, see Simulating Keystrokes in Browsers.

  • TestComplete includes more methods for simulating keystrokes. For more information on the differences between them and simulating keystrokes, see Simulating Keystrokes.

Restrictions

  • Sometimes the Keys method may simulate keystrokes incorrectly. This typically occurs when the active foreground window is TestComplete itself. In this case, the routine does not simulate key presses.

  • Due to the internal workings of Windows, TestComplete will stop recording when you press Ctrl+Esc or Ctrl+Alt+Del. You can use the Keys method to simulate Ctrl+Esc in script code.

  • To simulate global Windows shortcuts that use the [Win] or [Apps] keys, you should also use the [Hold] and release constant. For example, to simulate the [Win]+E shortcut that launches Windows Explorer, use [Hold][Win]e.

  • The use of the method is restricted by an application’s elevated permissions. If the tested application has higher elevated permissions than those of TestComplete, the method will not work. This also applies to running TestComplete under a user account. If you run your tested application with administrator privileges, TestComplete will not send a command to enter text in the tested application. To solve the problem, you need to run TestComplete as an administrator.

  • In the latest Windows 10 version, Task Manager always runs with administrator privileges, which makes it impossible to simulate keystrokes in it. A workaround is to run TestComplete with elevated permissions or with the Test Windows Store Applications option enabled.

Example

The following example demonstrates how to use the Keys method in scripts:

JavaScript, JScript

Sys.Process("notepad").Window("Notepad", "*").SetFocus();
Sys.Desktop.Keys("John Watts" + "[Tab]" + "Manager");

Python

Sys.Process("notepad").Window("Notepad", "*").SetFocus()
Sys.Desktop.Keys("John Watts" + "[Tab]" + "Manager")

VBScript

Sys.Process("notepad").Window("Notepad", "*").SetFocus()
Sys.Desktop.Keys ("John Watts" + "[Tab]" + "Manager")

DelphiScript

Sys.Process('notepad').Window('Notepad', '*').SetFocus();
Sys.Desktop.Keys('John Watts' + '[Tab]' + 'Manager');

C++Script, C#Script

Sys["Process"]("notepad")["Window"]("Notepad", "*")["SetFocus"]();
Sys["Desktop"]["Keys"]("John Watts" + "[Tab]" + "Manager");

See Also

Simulating User Actions
KeyDown Method (Desktop Objects)
KeyUp Method (Desktop Objects)
Keys Action

Highlight search results