Keys Action

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

Description

The Keys action sends keyboard input to the object, that is, types the specified text in it. Before typing, Keys activates the application window that contains the object and gives that object the input focus.

Note that Keys starts typing at the current insertion point within the object. If you need to enter text at a specific position, you need to place the insertion point at the desired position first. You can do this by sending the required keyboard navigation shortcuts to the object as part of keyboard input (see Setting Insertion Point in an Edit Control).

To change the text in an edit control, you can also use the SetText action or the wText property.

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

All onscreen 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

function CtrlPlusEsc()
{
  var p, wnd, onscreenObj;

  p = Sys.Process("MyProcess");
  wnd = p.Window("MyWndClass", "MyWndCaption", -1);
  onscreenObj = wnd.Window("MyControlClass", "", -1);
  onscreenObj.Keys("^[Esc]");
}

Python

def CtrlPlusEsc():
  p = Sys.Process("MyProcess")
  wnd = p.Window("MyWndClass", "MyWndCaption", -1)
  onscreenObj = wnd.Window("MyControlClass", "", -1)
  onscreenObj.Keys("^[Esc]")

VBScript

Sub CtrlPlusEsc
  Set p = Sys.Process("MyProcess")
  Set wnd = p.Window("MyWndClass", "MyWndCaption", -1)
  Set onscreenObj = wnd.Window("MyControlClass", "", -1)
  onscreenObj.Keys "^[Esc]"
End Sub

DelphiScript

procedure CtrlPlusEsc();
var
  p, wnd, onscreenObj : OleVariant;
begin
  p := Sys.Process('MyProcess');
  wnd := p.Window('MyWndClass', 'MyWndCaption', -1);
  onscreenObj := wnd.Window('MyControlClass', '', -1);
  onscreenObj.Keys('^[Esc]');
end;

C++Script, C#Script

function CtrlPlusEsc()
{
  var p, wnd, onscreenObj;

  p = Sys["Process"]("MyProcess");
  wnd = p["Window"]("MyWndClass", "MyWndCaption", -1);
  onscreenObj = wnd["Window"]("MyControlClass", "", -1);
  onscreenObj["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

function CtrlAndEsc()
{
  var p, wnd, onscreenObj;

  p = Sys.Process("MyProcess");
  wnd = p.Window("MyWndClass", "MyWndCaption", -1);
  onscreenObj = wnd.Window("MyControlClass", "", -1);
  onscreenObj.Keys("^");
  onscreenObj.Keys("[Esc]");
}

Python

def CtrlAndEsc():
  p = Sys.Process("MyProcess")
  wnd = p.Window("MyWndClass", "MyWndCaption", -1)
  onscreenObj = wnd.Window("MyControlClass", "", -1)
  onscreenObj.Keys("^")
  onscreenObj.Keys("[Esc]")

VBScript

Sub CtrlAndEsc
  Set p = Sys.Process("MyProcess")
  Set wnd = p.Window("MyWndClass", "MyWndCaption", -1)
  Set onscreenObj = wnd.Window("MyControlClass", "", -1)
  onscreenObj.Keys "^"
  onscreenObj.Keys "[Esc]"
End Sub

DelphiScript

procedure CtrlAndEsc();
var
  p, wnd, onscreenObj : OleVariant;
begin
  p := Sys.Process('MyProcess');
  wnd := p.Window('MyWndClass', 'MyWndCaption', -1);
  onscreenObj := wnd.Window('MyControlClass', '', -1);
  onscreenObj.Keys('^');
  onscreenObj.Keys('[Esc]');
end;

C++Script, C#Script

function CtrlAndEsc()
{
  var p, wnd, onscreenObj;

  p = Sys["Process"]("MyProcess");
  wnd = p["Window"]("MyWndClass", "MyWndCaption", -1);
  onscreenObj = wnd["Window"]("MyControlClass", "", -1);
  onscreenObj["Keys"]("^");
  onscreenObj["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, see Simulating Keystrokes.

  • To control whether the Keys action should be used to record text input into edit controls, use the Record text input into simple editors as option.

    If you use the Keys action to record password input, password values will be recorded as text strings and displayed in tests. To keep password values encrypted, set the Record text input into simple editors as option to SetText. In this case, password values will be stored in your project as password variables and masked in tests.
  • TestComplete cannot send the Keys action to an application with higher elevated permissions than the ones of TestComplete. To avoid possible problems, run TestComplete as administrator. See the Restrictions section of the Keys Method topic.

Example

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

JavaScript, JScript

function KeysActionExample()
{
  var p, Edit, Find;
  // Run Notepad
  WshShell.Run("notepad.exe", SW_SHOWNORMAL);

  // Obtain the edit object and fill it with text
  p = Sys.Process("NOTEPAD");
  Edit = p.Window("Notepad").Window("Edit");
  Edit.Keys("That's very important");
  Edit.Keys("^f");
  Find = p.Window("#32770").Window("Edit");

  // Place the cursor to the specified position
  Find.Keys("vry");
  Find.Keys("[Left][Left]");
  Find.Keys("e");
}

Python

def KeysActionExample():
  # Run Notepad 
  WshShell.Run("notepad.exe", SW_SHOWNORMAL)

  # Obtain the edit object and fill it with text
  p = Sys.Process("NOTEPAD")
  Edit = p.Window("Notepad").Window("Edit")
  Edit.Keys("That's very important")
  Edit.Keys("^f")
  Find = p.Window("#32770").Window("Edit")

  # Place the cursor to the specified position
  Find.Keys("vry")
  Find.Keys("[Left][Left]")
  Find.Keys("e")

VBScript

Sub KeysActionExample
  Dim p, Edit, Find
  ' Run Notepad
  Call WshShell.Run("notepad.exe", SW_SHOWNORMAL)

  ' Obtain the edit object and fill it with text
  Set p = Sys.Process("NOTEPAD")
  Set Edit = p.Window("Notepad").Window("Edit")
  Edit.Keys "That's very important"
  Edit.Keys "^f"
  Set Find = p.Window("#32770").Window("Edit")

  ' Place the cursor to the specified position
  Find.Keys "vry"
  Find.Keys "[Left][Left]"
  Find.Keys "e"
End Sub

DelphiScript

procedure KeysActionExample;
  var p, Edit, Find: OleVariant;
begin
  // Run Notepad
  WshShell.Run('notepad.exe', SW_SHOWNORMAL);
  // Obtain the edit object and fill it with text
  p := Sys.Process('NOTEPAD');
  Edit := p.Window('Notepad').Window('Edit');
  Edit.Keys('That''s very important');
  Edit.Keys('^f');
  Find := p.Window('#32770').Window('Edit');

  // Place the cursor to the specified position
  Find.Keys('vry');
  Find.Keys('[Left][Left]');
  Find.Keys('e');
end;

C++Script, C#Script

function KeysActionExample()
{
  var p, Edit, Find;
  // Run Notepad
  WshShell["Run"]("notepad.exe", SW_SHOWNORMAL);

  // Obtain the edit object and fill it with text
  p = Sys["Process"]("NOTEPAD");
  Edit = p["Window"]("Notepad").Window("Edit");
  Edit["Keys"]("That's very important");
  Edit["Keys"]("^f");
  Find = p["Window"]("#32770").Window("Edit");

  // Place the cursor to the specified position
  Find["Keys"]("vry");
  Find["Keys"]("[Left][Left]");
  Find["Keys"]("e");
}

See Also

Simulating User Actions
SetText Action (Edit and Combo Box Controls)
Keys Method
KeyDown Method (Desktop Objects)
KeyUp Method (Desktop Objects)

Highlight search results