Table of Contents

Class Keyboard

Namespace
Ranorex
Assembly
Ranorex.Core.dll

Provides keyboard actions and events.

public class Keyboard
Inheritance
Keyboard
Inherited Members

Constructors

Keyboard() 

public Keyboard()

Fields

DefaultScanCode

Specify this value if you want to use the default hardware scan code corresponding to a specified virtual key code (see Keys).

public const int DefaultScanCode = 0

Field Value

int

Properties

AbortKey

Gets or sets a key-modifier combination that aborts the current thread if pressed.

public static Keys AbortKey { get; set; }

Property Value

Keys

Remarks

If the abort key is pressed, the thread that set the AbortKey is aborted; i.e. a ThreadAbortException is raised in the thread that set the AbortKey.

CharacterMappingEnabled

Gets or sets a value whether Unicode characters are tried to be mapped to virtual keyboard inputs.

public static bool CharacterMappingEnabled { get; set; }

Property Value

bool

True to enable Unicode character mapping, false to disable. Default is true.

Remarks

If this property is true, in the keyboard methods that take Unicode characters as input the Unicode characters are tried to be mapped to virtual keyboard inputs instead of being directly send to the system as Unicode character input.

If you are working with multiple input locales at the same time, it is usually better to turn character mapping off, i.e. to set this property to false.

DefaultKeyPressTime

Gets or sets the default time for a key press, i.e. the time elapsed between a key being pressed (KeyDown event) and released (KeyUp event) again.

public static Duration DefaultKeyPressTime { get; set; }

Property Value

Duration

Exceptions

ArgumentOutOfRangeException

If the value is negative.

Enabled

Gets or sets a value indicating whether physical keyboard actions are enabled.

public static bool Enabled { get; set; }

Property Value

bool

Remarks

If the keyboard is disabled, physical keyboard actions will be ignored, i.e. they are not passed on to the system. However, the Keyboard events (like KeyDown) will still be raised with the SuppressKeyPress property of the event arguments set to true. To re-enable specific keyboard events, set the SuppressKeyPress of the event arguments to false.

PauseKey

Gets or sets a key-modifier combination that pauses or resumes the current test execution if pressed.

public static Keys PauseKey { get; set; }

Property Value

Keys

Methods

Down(char)

Sets the state of the key associated with the specified character to pressed/down.

public static void Down(char character)

Parameters

character char

A character associated with a key.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Down(char, bool)

Sets the state of the key associated with the specified character to pressed/down.

public static void Down(char character, bool resetModifiers)

Parameters

character char

A character associated with a key.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Down(Keys)

Sets the state of the specified key to pressed/down.

public static void Down(Keys keyCode)

Parameters

keyCode Keys

The key.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Down(Keys, int, bool)

Sets the state of the specified key to pressed/down.

public static void Down(Keys key, int scanCode, bool setModifiers)

Parameters

key Keys

The key.

scanCode int

The hardware scan code for the key. Specify DefaultScanCode to use the default scan code for the specified virtual key.

setModifiers bool

A value specifying whether to set the modifiers specified in the key.

EscapeSequence(string)

Replaces escape characters in sequence by their escaped representation to be used with the Press(string) method.

public static string EscapeSequence(string sequence)

Parameters

sequence string

An unescaped sequence of characters.

Returns

string

An escaped sequence of characters.

Exceptions

ArgumentNullException

If sequence is a null reference.

GetSequenceFromKeyEvents(IList<KeyValuePair<KeyEventArgs, bool>>)

Gets a string that can be passed to Press(string) from a list of key events.

public static string GetSequenceFromKeyEvents(IList<KeyValuePair<KeyEventArgs, bool>> keyEvents)

Parameters

keyEvents IList<KeyValuePair<KeyEventArgs, bool>>

A list of key events. Each key event is a pair of KeyEventArgs and a bool that specifies whether the key was pressed (true) or released (false).

Returns

string

The key sequence represented as a string.

Remarks

The default upDownEventRearrangeMaxDistance is used.

GetSequenceFromKeyEvents(IList<KeyValuePair<KeyEventArgs, bool>>, int)

Gets a string that can be passed to Press(string) from a list of key events.

public static string GetSequenceFromKeyEvents(IList<KeyValuePair<KeyEventArgs, bool>> keyEvents, int upDownEventRearrangeMaxDistance)

Parameters

keyEvents IList<KeyValuePair<KeyEventArgs, bool>>

A list of key events. Each key event is a pair of KeyEventArgs and a bool that specifies whether the key was pressed (true) or released (false).

upDownEventRearrangeMaxDistance int

The maximum distance between up and down events of a single key to be merged into a key press.

Returns

string

The key sequence represented as a string.

PrepareFocus(Element)

Tries to set the focus to the specified element if necessary and also tries to make the element visible (if EnsureVisible is specified).

public static void PrepareFocus(Element focusTarget)

Parameters

focusTarget Element

The target element to set the focus to.

Press(Element, string)

Presses the keys specified by sequence.

public static void Press(Element focusTarget, string sequence)

Parameters

focusTarget Element

The element to set the focus to, if possible, before entering the sequence.

sequence string

A sequence of characters and escape groups that specify the keys to press.

Remarks

Each key is repesented by a single character or an escape group. To specify a single keyboard character, use the character itself (e.g. use "aBc" to press the keys A, B+Shift, and C after another). Only the '{' character has a special meaning and needs to be escaped by preceding it with another '{' (specify "{{" to issue a '{' key press).

Escape groups, signalled by braces "{}", may be used to produce a key action with any of the keys specified by the Keys enumeration. "{Z}" means that the 'z' key should be pressed, and "{return}" or "{enter}" that the Return key is to be pressed.

Additionally, in an escape group you can specify a modifier that determines whether the key should be hold down (e.g. {CONTROL down}), released (e.g. {shift up}), or pressed a number of times (e.g. {z 3}). In an escape group, key name and modifier must be separated by a single shift character.

The keys A to Z set the key modifiers (ALT, CTRL, SHIFT) and in particular the shift key depending on their case, even if used in an escape group. If these keys should not modify the shift key state, wrap them into an escape group and add "key" to the character, e.g. "{Rkey}" to press the R key without changing the shift key state.

Press(Element, string, Duration)

Presses the keys specified by sequence.

public static void Press(Element focusTarget, string sequence, Duration keyPressTime)

Parameters

focusTarget Element

The element to set the focus to, if possible, before entering the sequence.

sequence string

A sequence of characters and escape groups that specify the keys to press.

keyPressTime Duration

The key press time.

Remarks

Each key is repesented by a single character or an escape group. To specify a single keyboard character, use the character itself (e.g. use "aBc" to press the keys A, B+Shift, and C after another). Only the '{' character has a special meaning and needs to be escaped by preceding it with another '{' (specify "{{" to issue a '{' key press).

Escape groups, signalled by braces "{}", may be used to produce a key action with any of the keys specified by the Keys enumeration. "{Z}" means that the 'z' key should be pressed, and "{return}" or "{enter}" that the Return key is to be pressed.

Additionally, in an escape group you can specify a modifier that determines whether the key should be hold down (e.g. {CONTROL down}), released (e.g. {shift up}), or pressed a number of times (e.g. {z 3}). In an escape group, key name and modifier must be separated by a single shift character.

The keys A to Z set the key modifiers (ALT, CTRL, SHIFT) and in particular the shift key depending on their case, even if used in an escape group. If these keys should not modify the shift key state, wrap them into an escape group and add "key" to the character, e.g. "{Rkey}" to press the R key without changing the shift key state.

Press(char)

Presses the key associated with the specified character and releases it again.

public static void Press(char character)

Parameters

character char

A character associated with a key.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released. The original state of these modifier keys is restored by this method.

Press(char, Duration)

Presses the key associated with the specified character and releases it again after the specified time.

public static void Press(char character, Duration keyPressTime)

Parameters

character char

A character associated with a key.

keyPressTime Duration

The time between pressing and releasing the key.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released. The original state of these modifier keys is restored by this method.

Press(char, Duration, bool)

Presses the key associated with the specified character and releases it again after the specified time.

public static void Press(char character, Duration keyPressTime, bool resetModifiers)

Parameters

character char

A character associated with a key.

keyPressTime Duration

The time between pressing and releasing the key.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Press(char, Duration, int)

Presses and releases the key associated with the specified character for the specified number of times.

public static void Press(char character, Duration keyPressTime, int times)

Parameters

character char

A character associated with a key.

keyPressTime Duration

The time between pressing and releasing the key.

times int

The number of times to press the key.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released. The original state of these modifier keys is restored by this method.

Press(char, Duration, int, bool)

Presses and releases the key associated with the specified character for the specified number of times.

public static void Press(char character, Duration keyPressTime, int times, bool resetModifiers)

Parameters

character char

A character associated with a key.

keyPressTime Duration

The time between pressing and releasing the key.

times int

The number of times to press the key.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Press(char, bool)

Presses the key associated with the specified character and releases it again.

public static void Press(char character, bool resetModifiers)

Parameters

character char

A character associated with a key.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Press(string)

Presses the keys specified by sequence.

public static void Press(string sequence)

Parameters

sequence string

A sequence of characters and escape groups that specify the keys to press.

Remarks

Each key is represented by a single character or an escape group. To specify a single keyboard character, use the character itself (e.g. use "aBc" to press the keys A, B+Shift, and C after another). Only the '{' character has a special meaning and needs to be escaped by preceding it with another '{' (specify "{{" to issue a '{' key press).

Escape groups, signaled by braces "{}", may be used to produce a key action with any of the keys specified by the Keys enumeration. "{Z}" means that the 'z' key should be pressed, and "{return}" or "{enter}" that the Return key is to be pressed.

Additionally, in an escape group you can specify a modifier that determines whether the key should be hold down (e.g. {CONTROL down}), released (e.g. {shift up}), or pressed a number of times (e.g. {z 3}). In an escape group, key name and modifier must be separated by a single shift character.

The keys A to Z set the key modifiers (ALT, CTRL, SHIFT) and in particular the shift key depending on their case, even if used in an escape group. If these keys should not modify the shift key state, wrap them into an escape group and add "key" to the character, e.g. "{Rkey}" to press the R key without changing the shift key state.

Press(string, Duration)

Presses the keys specified by sequence.

public static void Press(string sequence, Duration keyPressTime)

Parameters

sequence string

A sequence of characters and escape groups that specify the keys to press.

keyPressTime Duration

The key press time.

Remarks

Each key is represented by a single character or an escape group. To specify a single keyboard character, use the character itself (e.g. use "aBc" to press the keys A, B+Shift, and C after another). Only the '{' character has a special meaning and needs to be escaped by preceding it with another '{' (specify "{{" to issue a '{' key press).

Escape groups, signaled by braces "{}", may be used to produce a key action with any of the keys specified by the Keys enumeration. "{Z}" means that the 'z' key should be pressed, and "{return}" or "{enter}" that the Return key is to be pressed.

Additionally, in an escape group you can specify a modifier that determines whether the key should be hold down (e.g. {CONTROL down}), released (e.g. {shift up}), or pressed a number of times (e.g. {z 3}). In an escape group, key name and modifier must be separated by a single shift character.

The keys A to Z set the key modifiers (ALT, CTRL, SHIFT) and in particular the shift key depending on their case, even if used in an escape group. If these keys should not modify the shift key state, wrap them into an escape group and add "key" to the character, e.g. "{Rkey}" to press the R key without changing the shift key state.

Press(Keys)

Presses the specified key and releases it again.

public static void Press(Keys keyCode)

Parameters

keyCode Keys

The key.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Press(Keys, Duration)

Presses the specified key and releases it again after the specified time.

public static void Press(Keys keyCode, Duration keyPressTime)

Parameters

keyCode Keys

The key.

keyPressTime Duration

The time between pressing and releasing the key.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Press(Keys, Duration, int)

Presses and releases the specified key for the specified number of times.

public static void Press(Keys keyCode, Duration keyPressTime, int times)

Parameters

keyCode Keys

The key.

keyPressTime Duration

The time between pressing and releasing the key.

times int

The number of times to press the key.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Press(Keys, int, Duration, int, bool)

Presses and releases the specified key for the specified number of times.

public static void Press(Keys key, int scanCode, Duration keyPressTime, int times, bool setModifiers)

Parameters

key Keys

The key.

scanCode int

The hardware scan code for the key. Specify DefaultScanCode to use the default scan code for the specified virtual key.

keyPressTime Duration

The time between pressing and releasing the key.

times int

The number of times to press the key.

setModifiers bool

A value specifying whether to set the modifiers specified in the key.

Set(char, bool)

Sets the state of the key associated with the specified character to either pressed/down or released/up.

public static void Set(char character, bool down)

Parameters

character char

A character associated with a key.

down bool

True to press the key, false to release it.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released. The original state of these modifier keys is restored by this method.

Set(char, bool, bool)

Sets the state of the key associated with the specified character to either pressed/down or released/up.

public static void Set(char character, bool down, bool resetModifiers)

Parameters

character char

A character associated with a key.

down bool

True to press the key, false to release it.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Set(Keys, bool)

Sets the state of the specified key to either pressed/down or released/up.

public static void Set(Keys keyCode, bool down)

Parameters

keyCode Keys

The key.

down bool

True to press the key, false to release it.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Set(Keys, int, bool, bool)

Sets the state of the specified key to either pressed/down or released/up.

public static void Set(Keys key, int scanCode, bool down, bool setModifiers)

Parameters

key Keys

The key.

scanCode int

The hardware scan code for the key. Specify DefaultScanCode to use the default scan code for the specified virtual key.

down bool

True to press the key, false to release it.

setModifiers bool

A value specifying whether to set the modifiers specified in the key.

ToKey(string)

Converts the specified string representation (see ToString(Keys)) to a Keys value.

public static Keys ToKey(string key)

Parameters

key string

The string representation of a key.

Returns

Keys

The key value.

Exceptions

ArgumentException

If the string representation of the key is invalid.

ToString(Keys)

Returns a string representation of the specified key.

public static string ToString(Keys key)

Parameters

key Keys

A key.

Returns

string

A string representation of the key.

Up(char)

Sets the state of the key associated with the specified character to released/up.

public static void Up(char character)

Parameters

character char

A character associated with a key.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released. The original state of these modifier keys is restored by this method.

Up(char, bool)

Sets the state of the key associated with the specified character to released/up.

public static void Up(char character, bool resetModifiers)

Parameters

character char

A character associated with a key.

resetModifiers bool

True to reset the state of modifier keys (e.g. the ShiftKey) to the original state before the call to this method.

Remarks

This method may cause modifier keys (like ControlKey or ShiftKey) to be pressed or released.

Up(Keys)

Sets the state of the specified key to released/up.

public static void Up(Keys keyCode)

Parameters

keyCode Keys

The key.

Remarks

This method does not consider modifier flags (like Control or Shift) in the keyCode.

Up(Keys, int, bool)

Sets the state of the specified key to released/up.

public static void Up(Keys key, int scanCode, bool setModifiers)

Parameters

key Keys

The key.

scanCode int

The hardware scan code for the key. Specify DefaultScanCode to use the default scan code for the specified virtual key.

setModifiers bool

A value specifying whether to set the modifiers specified in the key.

Events

KeyDown

Occurs when a key is pressed or hold down.

public static event KeyEventHandler KeyDown

Event Type

KeyEventHandler

KeyUp

Occurs when a key is released.

public static event KeyEventHandler KeyUp

Event Type

KeyEventHandler