keyboardHandler module

Keyboard support

keyboardHandler.trappedKeys = {}

Keys which have been trapped by NVDA and should not be passed to the OS.

keyboardHandler.passKeyThroughCount = -1

Tracks the number of keys passed through by request of the user. If -1, pass through is disabled. If 0 or higher then key downs and key ups will be passed straight through.

keyboardHandler.lastPassThroughKeyDown = None

The last key down passed through by request of the user.

keyboardHandler.lastNVDAModifier = None

The last NVDA modifier key that was pressed with no subsequent key presses.

keyboardHandler.lastNVDAModifierReleaseTime = None

When the last NVDA modifier key was released.

keyboardHandler.bypassNVDAModifier = False

Indicates that the NVDA modifier’s special functionality should be bypassed until a key is next released.

keyboardHandler.currentModifiers = {}

The modifiers currently being pressed.

keyboardHandler.keyCounter = 0

A counter which is incremented each time a key is pressed. Note that this may be removed in future, so reliance on it should generally be avoided. @type: int

keyboardHandler.stickyNVDAModifier = None

The current sticky NVDa modifier key.

keyboardHandler.stickyNVDAModifierLocked = False

Whether the sticky NVDA modifier is locked.

keyboardHandler.ignoreInjection()

Context manager that allows ignoring injected keys temporarily by using a with statement.

keyboardHandler.passNextKeyThrough()
keyboardHandler.isNVDAModifierKey(vkCode: int, extended: bool) bool
keyboardHandler.getNVDAModifierKeys() List[Tuple[int, bool | None]]
keyboardHandler.shouldUseToUnicodeEx(focus: NVDAObject | None = None)

Returns whether to use ToUnicodeEx to determine typed characters.

keyboardHandler.internal_keyDownEvent(vkCode, scanCode, extended, injected)

Event called by winInputHook when it receives a keyDown.

keyboardHandler.internal_keyUpEvent(vkCode, scanCode, extended, injected)

Event called by winInputHook when it receives a keyUp.

keyboardHandler.initialize(watchdogObserver: WatchdogObserver)

Initialises keyboard support.

keyboardHandler.terminate()
keyboardHandler.getInputHkl()

Obtain the hkl currently being used for input. This retrieves the hkl from the thread of the focused window.

keyboardHandler.canModifiersPerformAction(modifiers)

Determine whether given generalized modifiers can perform an action if pressed alone. For example, alt activates the menu bar if it isn’t modifying another key.

class keyboardHandler.KeyboardInputGesture(*args, **kwargs)

Bases: InputGesture

A key pressed on the traditional system keyboard.

NORMAL_MODIFIER_KEYS = {'windows': None, 16: None, 160: 16, 161: 16, 162: 17, 163: 17, 164: 18, 165: 18, 17: None, 18: None, 91: 'windows', 92: 'windows'}

@type: dict

TOGGLE_KEYS = frozenset({20, 144, 145})

All possible toggle key vk codes. @type: frozenset

LAYOUTS = {'desktop': 'desktop', 'laptop': 'laptop'}

All possible keyboard layouts, where layout names are mapped to localised layout names. @type: dict

classmethod getVkName(vkCode, isExtended)
layout

The keyboard layout in which this gesture was created. @type: str

_get_bypassInputHelp()
_get_isNVDAModifierKey()
_get_isModifier()
_get_mainKeyName()
_get_modifierNames()
_get__keyNamesInDisplayOrder()
_get_displayName()

The name of this gesture as presented to the user. The base implementation calls L{getDisplayTextForIdentifier} for the first identifier. Subclasses need not override this unless they wish to provide a more optimal implementation. @return: The display name. @rtype: str

_get_identifiers()

The identifier(s) which will be used in input gesture maps to represent this gesture. These identifiers will be normalized and looked up in order until a match is found. A single identifier should take the form: C{source:id} where C{source} is a few characters representing the source of this gesture and C{id} is the specific gesture. An example identifier is: C{kb(desktop):NVDA+1}

This property should not perform normalization itself. However, please note the following regarding normalization. If C{id} contains multiple chunks separated by a + sign, they are considered to be ordered arbitrarily and may be reordered when normalized. Normalization also ensures that the entire identifier is lower case. For example, NVDA+control+f1 and control+nvda+f1 will match when normalized. See L{normalizeGestureIdentifier} for more details.

Subclasses must implement this method. @return: One or more identifiers which uniquely identify this gesture. @rtype: list or tuple of str

_get_shouldReportAsCommand()
_get_isCharacter()
_get_speechEffectWhenExecuted()
reportExtra()

Report any extra information about this gesture to the user. This is called just after command gestures are reported. For example, it could be used to report toggle states.

_reportToggleKey()
executeScript(script)

Executes the given script with this gesture, using scriptHandler.executeScript. This is only implemented so as to allow Gesture subclasses to perform an action directly before / after the script executes.

_INJECTION_WAIT_TIMEOUT: int = 10

The maximum amount of time (in ms) to wait for keys injected by NVDA to be received by NVDA.

send()

Send this gesture to the operating system. This is not possible for all sources. @raise NotImplementedError: If the source does not support sending of gestures.

classmethod fromName(name)

Create an instance given a key name. @param name: The key name. @type name: str @return: A gesture for the specified key. @rtype: L{KeyboardInputGesture}

RE_IDENTIFIER = re.compile('^kb(?:\\((.+?)\\))?:(.*)$')
classmethod getDisplayTextForIdentifier(identifier)

Get the text to be presented to the user describing a given gesture identifier. This should only be called with normalized gesture identifiers returned by the L{normalizedIdentifiers} property in the same subclass. For example, C{KeyboardInputGesture.getDisplayTextForIdentifier} should only be called for “kb:*” identifiers returned by C{KeyboardInputGesture.normalizedIdentifiers}. Most callers will want L{inputCore.getDisplayTextForIdentifier} instead. The display text consists of two strings: the gesture’s source (e.g. “laptop keyboard”) and the specific gesture (e.g. “alt+tab”). @param identifier: The normalized gesture identifier in question. @type identifier: str @return: A tuple of (source, specificGesture). @rtype: tuple of (str, str) @raise Exception: If no display text can be determined.

_abc_impl = <_abc._abc_data object>
_keyNamesInDisplayOrder
bypassInputHelp

Indicates that while in Input Help Mode, this gesture should be handled as if Input Help mode was currently off. @type: bool

displayName: str
identifiers: List[str] | Tuple[str, ...]
isCharacter

whether this gesture represents a character being typed (i.e. not a potential command) @type bool

isModifier

Whether this gesture is only a modifier, in which case it will not search for a script to execute. @type: bool

isNVDAModifierKey
mainKeyName
modifierNames
shouldReportAsCommand

Whether this gesture should be reported when reporting of command gestures is enabled. @type: bool

speechEffectWhenExecuted

The effect on speech when this gesture is executed; one of the SPEECHEFFECT_* constants or C{None}.

keyboardHandler.injectRawKeyboardInput(isPress, code, isExtended)

Inject raw input from a system keyboard that is not handled natively by Windows. For example, this might be used for input from a QWERTY keyboard on a braille display. NVDA will treat the key as if it had been pressed on a normal system keyboard. If it is not handled by NVDA, it will be sent to the operating system. @param isPress: Whether the key is being pressed. @type isPress: bool @param code: The scan code (PC set 1) of the key. @type code: int @param isExtended: Whether this is an extended key. @type isExtended: bool