Add new extension points for keyboard input and speech pause

[ctoth]

Add new extension points for raw keyboard events and speech pause state

This commit introduces two new extension points:

1. inputCore.decide_handleRawKey

• Called before any NVDA processing of raw keyboard events
• Allows add-ons to intercept and optionally block keyboard events
• Provides full context: vkCode, scanCode, extended flag, and press/release state
• Implemented in both keyDown and keyUp event handlers
• Returns True to allow normal processing, False to block the key

2. speech.extensions.speechPaused

• Notifies when speech is paused or resumed
• Provides boolean 'switch' parameter (True=paused, False=resumed)
• Added corresponding unit tests to verify functionality
• Integrated into existing pauseSpeech() function

Technical Details:

• Added documentation for both extension points in developerGuide.md
• Updated speech/init.py to expose the new speechPaused extension point
• Added test case in test_speech.py to verify extension point behavior
• Maintains backwards compatibility with existing extensions

These additions enable add-ons to:

• Implement advanced keyboard interception/modification
• React to speech pause state changes

Link to issue number:

N/A - New feature addition for extensibility

Summary of the issue:

NVDA needed additional extension points to allow add-ons to:

1. Intercept and control raw keyboard events before NVDA processing
2. Monitor and react to speech pause state changes

Description of user facing changes

• No direct user-facing changes
• Enables add-on developers to create more sophisticated keyboard handling and speech feedback features
• All changes are API-level additions that maintain backwards compatibility

Description of development approach

1. Raw Keyboard Extension Point:

   • Added decide_handleRawKey extension point in inputCore.py
   • Integrated into both keyDown and keyUp event handlers in keyboardHandler.py
   • Full keyboard event context provided (vkCode, scanCode, extended, pressed)
   • Boolean return value controls event propagation

2. Speech Pause Extension Point:

   • Added speechPaused extension point in speech/extensions.py
   • Integrated into existing pauseSpeech() function
   • Provides pause state through boolean parameter

3. Documentation:

   • Added entries in developerGuide.md
   • Updated relevant module documentation
   • Added changelog entry

Testing strategy:

1. Unit Tests:

   • Added test cases in test_speech.py for speechPaused extension point
   • Tests verify extension point notification on pause/resume
   • Tests ensure correct parameter passing

2. Manual Testing:

   • Verified keyboard extension point with test add-on
   • Confirmed speech pause notifications work as expected

Known issues with pull request:

None identified - straightforward API additions with full test coverage

Code Review Checklist:

• Documentation:

  • Change log entry added in changes.md
  • Developer documentation updated in developerGuide.md
  • Technical documentation added in module docstrings
  • No GUI changes, so no context help needed

• Testing:

  • Unit tests added for speechPaused
  • Manual testing performed with test add-on
  • System tests not required (API-level changes)

• UX of all users considered:

  • No direct user impact
  • Enables better add-on support for all output methods
  • No localization impact (API only)

• API is compatible with existing add-ons

  • New extension points are additive only
  • No breaking changes to existing APIs
  • Follows established extension point patterns

• Security precautions taken:

  • Discussed raw keystroke decider security implications with NV Access.

@coderabbitai summary

[seanbudd]

Thanks @ctoth - this seems almost ready

[seanbudd]

Does this close #14520?

[CyrilleB79]

Is this PR triggered by the need to remove monkey patching in NVDA remote?
Or have you other add-ons, usages or projects in mind? If yes, would you mind to share it with us? It's of course not mandatory; just my curiosity...

[nvdaes]

Just to say that I'plan to use the keyboard extension point in the pcKbBrl add-on. Thanks for this PR. Hope this is merged when possible to test it.

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: License check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/bbjfqnucm6edp5k1/artifacts/output/l10nUtil.exe nvda_snapshot_pr17428-34659,2777ea2c.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 1.3,
  INSTALL_END 0.9,
  BUILD_START 0.0,
  BUILD_END 23.3,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 18.1,
  FINISH_END 0.2

See test results for failed build of commit 2777ea2c3c

[ctoth]

@seanbudd Re #14520 we still need one more extension point for speech either directly inside or directly before speech.manager.speak

Unfortunately existing Remote monkeypatches speech.manager.speak rather than speech.speak (for which we could trivially use pre_speech) and to maintain backwards compatibility with existing Remote clients we'll need one more there
Still, very close now. #17429 is also almost the functionality we need, though I don't know if it quite does the job in its current form.