Pass the injected flag to the decide_handleRawKey extension point

[LeonarddeR]

Link to issue number:

Closes #20714

Summary of the issue:

NVDA's low level keyboard hook knows whether a key event was injected. However, the extension point that lets code veto a raw key event only passes vkCode, scanCode, extended and pressed to its handlers. injected is missing.

Description of user facing changes:

None.

Description of developer facing changes:

Handlers of inputCore.decide_handleRawKey now also receive injected.
It is True when the key event was injected by software rather than generated by the keyboard.
The two hook callbacks in keyboardHandler, internal_keyDownEvent and internal_keyUpEvent, gained type annotations and docstrings.

Description of development approach:

The low level keyboard hook already passes the injected flag to keyboardHandler.internal_keyDownEvent and internal_keyUpEvent.
Both functions now forward it to decide_handleRawKey.decide as the injected keyword argument.

Extension point handlers only receive the keyword arguments they declare, so existing handlers keep working unchanged.
A handler that must also run on older NVDA versions can declare the parameter with a default, such as injected: bool | None = None.

Testing strategy:

Manual, with caps lock set as NVDA modifier key on both ends of a full screen mstsc session and an add-on handler on decide_handleRawKey that logs injected:

• Press caps lock+down arrow twice within half a second.
  The echoed caps lock events arrive with injected=True; the keys forwarded to the server never reach the client's hook.
• A handler that returns False for injected caps lock events stops the local caps lock from toggling.

Known issues with pull request:

None.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

[Copilot]

Pull request overview

This PR extends NVDA’s raw keyboard veto extension point to include whether the underlying low-level hook flagged an event as software-injected, enabling add-ons to precisely filter injected key echoes (e.g., in full-screen Remote Desktop scenarios) while remaining backward compatible for existing handlers.

Changes:

• Forward the low-level hook’s injected flag through keyboardHandler.internal_keyDownEvent / internal_keyUpEvent into inputCore.decide_handleRawKey.decide(...).
• Document the new injected kwarg for inputCore.decide_handleRawKey, and add type annotations/docstrings to the hook callbacks.
• Add a developer changelog entry describing the new kwarg and compatibility guidance for handlers.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
user_docs/en/changes.md	Documents the new injected kwarg for the decide_handleRawKey extension point and notes backward-compatible handler signatures.
source/keyboardHandler.py	Forwards injected into decide_handleRawKey and adds annotations/docstrings to the hook callbacks.
source/inputCore.py	Updates decide_handleRawKey extension point documentation to include the injected kwarg.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.