Keyboard

Provides classes for monitoring keyboard activity and modifying how iTerm2 handles keystrokes.

class KeystrokeMonitor(connection: iterm2.connection.Connection, session: Optional[str] = None, advanced: Optional[bool] = False)

Monitors keystrokes in one or all sessions.

Parameters

  • connection – The Connection to use.

  • session – The session ID to affect, or None meaning all sessions.

  • advanced – If false only key-down events are reported. If true, key-up and flags-changed events are also reported.

See also

Example:

async with iterm2.KeystrokeMonitor(connection) as mon:
    while True:
        keystroke = await mon.async_get()
        DoSomething(keystroke)
async async_get() → iterm2.keyboard.Keystroke

Wait for and return the next keystroke.

class KeystrokeFilter(connection: iterm2.connection.Connection, patterns: List[iterm2.keyboard.KeystrokePattern], session: Optional[str] = None)

An async context manager that disables the regular handling of keystrokes matching patterns during its lifetime.

Parameters

  • connection – The Connection to use.

  • patterns – A list of KeystrokePattern objects specifying keystrokes whose regular handling should be disabled.

  • session – The session ID to affect, or None meaning all.

See also

Example:

# Prevent iTerm2 from handling all control-key combinations.
ctrl = iterm2.KeystrokePattern()
ctrl.required_modifiers = [iterm2.Modifier.CONTROL]
ctrl.keycodes = [keycode for keycode in iterm2.Keycode]

filter = iterm2.KeystrokeFilter(connection, [ctrl])
async with filter as mon:
    await iterm2.async_wait_forever()
class Keystroke(notification)

Describes a keystroke.

Do not create instances of this class. They will be passed to you when you use a KeystrokeMonitor.

property characters: str

A string giving the characters that would be generated by the keystroke ordinarily.

Returns

A string.

property characters_ignoring_modifiers: str

A string giving the characters that would be generated by the keystroke as if no modifiers besides shift were pressed.

Returns

A string.

property keycode: iterm2.keyboard.Keycode

The ANSI keycode that was pressed.

Returns

A Keycode object.

property modifiers: List[iterm2.keyboard.Modifier]

The modifiers that were pressed.

Returns

A list of Modifier objects.

class KeystrokePattern

Describes attributes that select keystrokes.

Keystrokes contain modifiers (e.g., command or option), characters (what characters are generated by the keypress), and characters ignoring modifiers (what characters would be generated if no modifiers were pressed, excepting the shift key).

property characters: List[str]

List of strings. Each string has a character.

The pattern matches if the modifier constraints are satisfied and a keystroke has any of these characters.

property characters_ignoring_modifiers: List[str]

List of strings. Each string has a character.

The pattern matches if the modifier constraints are satisfied and a keystroke has any of these characters, ignoring modifiers.

“Ignoring modifiers” mostly means ignoring modifiers other than Shift. It has a lot of surprising edge cases which Apple did not document, so experiment to find how it works.

property forbidden_modifiers: List[iterm2.keyboard.Modifier]

List of modifiers whose presence prevents the pattern from being matched.

A list of type Modifier.

property keycodes: List[iterm2.keyboard.Keycode]

List of keycodes that match the pattern.

The pattern matches if the modifier constraints are satisfied and a keystroke has any of these keycodes.

A list of type Keycode.

property required_modifiers: List[iterm2.keyboard.Modifier]

List of modifiers that are required to match the pattern.

A list of type Modifier.

class Modifier(value)

Enumerated list of modifier keys.

COMMAND = 3

The command key modifier

CONTROL = 1

The control key modifier

FUNCTION = 5

Indicates the key is a function key.

NUMPAD = 6

Indicates the key is on the numeric keypad.

OPTION = 2

The option (or Alt) key modifier

SHIFT = 4

The shift key modifier

static from_cocoa()
to_cocoa() → int
class Keycode(value)

Enumerated list of virtual keycodes. These repesent physical keys on a keyboard regardless of its actual layout.

ANSI_0 = 29
ANSI_1 = 18
ANSI_2 = 19
ANSI_3 = 20
ANSI_4 = 21
ANSI_5 = 23
ANSI_6 = 22
ANSI_7 = 26
ANSI_8 = 28
ANSI_9 = 25
ANSI_A = 0
ANSI_B = 11
ANSI_BACKSLASH = 42
ANSI_C = 8
ANSI_COMMA = 43
ANSI_D = 2
ANSI_E = 14
ANSI_EQUAL = 24
ANSI_F = 3
ANSI_G = 5
ANSI_GRAVE = 50
ANSI_H = 4
ANSI_I = 34
ANSI_J = 38
ANSI_K = 40
ANSI_KEYPAD0 = 82
ANSI_KEYPAD1 = 83
ANSI_KEYPAD2 = 84
ANSI_KEYPAD3 = 85
ANSI_KEYPAD4 = 86
ANSI_KEYPAD5 = 87
ANSI_KEYPAD6 = 88
ANSI_KEYPAD7 = 89
ANSI_KEYPAD8 = 91
ANSI_KEYPAD9 = 92
ANSI_KEYPAD_CLEAR = 71
ANSI_KEYPAD_DECIMAL = 65
ANSI_KEYPAD_DIVIDE = 75
ANSI_KEYPAD_ENTER = 76
ANSI_KEYPAD_EQUALS = 81
ANSI_KEYPAD_MINUS = 78
ANSI_KEYPAD_MULTIPLY = 67
ANSI_KEYPAD_PLUS = 69
ANSI_L = 37
ANSI_LEFT_BRACKET = 33
ANSI_M = 46
ANSI_MINUS = 27
ANSI_N = 45
ANSI_O = 31
ANSI_P = 35
ANSI_PERIOD = 47
ANSI_Q = 12
ANSI_QUOTE = 39
ANSI_R = 15
ANSI_RIGHT_BRACKET = 30
ANSI_S = 1
ANSI_SEMICOLON = 41
ANSI_SLASH = 44
ANSI_T = 17
ANSI_U = 32
ANSI_V = 9
ANSI_W = 13
ANSI_X = 7
ANSI_Y = 16
ANSI_Z = 6
CAPS_LOCK = 57
COMMAND = 55
CONTROL = 59
DELETE = 51
DOWN_ARROW = 125
END = 119
ESCAPE = 53
F1 = 122
F10 = 109
F11 = 103
F12 = 111
F13 = 105
F14 = 107
F15 = 113
F16 = 106
F17 = 64
F18 = 79
F19 = 80
F2 = 120
F20 = 90
F3 = 99
F4 = 118
F5 = 96
F6 = 97
F7 = 98
F8 = 100
F9 = 101
FORWARD_DELETE = 117
FUNCTION = 63
HELP = 114
HOME = 115
LEFT_ARROW = 123
MUTE = 74
OPTION = 58
PAGE_DOWN = 121
PAGE_UP = 116
RETURN = 36
RIGHT_ARROW = 124
RIGHT_COMMAND = 54
RIGHT_CONTROL = 62
RIGHT_OPTION = 61
RIGHT_SHIFT = 60
SHIFT = 56
SPACE = 49
TAB = 48
UP_ARROW = 126
VOLUME_DOWN = 73
VOLUME_UP = 72

Indices and tables