Add new extension points for keyboard input and speech pause

projectDocs/dev/developerGuide/developerGuide.md

@@ -1361,6 +1361,7 @@ For examples of how to define and use new extension points, please see the code
 
 | Type |Extension Point |Description|
 |---|---|---|
+|`Decider` |`decide_handleRawKey` |Notifies when a raw keyboard event is received, before any NVDA processing, allowing other code to decide if it should be handled.|
 |`Decider` |`decide_executeGesture` |Notifies when a gesture is about to be executed, allowing other code to decide if it should be.|
 
 ### logHandler {#logHandlerExtPts}
@@ -1382,6 +1383,7 @@ For examples of how to define and use new extension points, please see the code
 |`Action` |`speechCanceled` |Triggered when speech is canceled.|
 |`Action` |`pre_speechCanceled` |Triggered before speech is canceled.|
 |`Action` |`pre_speech` |Triggered before NVDA handles prepared speech.|
+|`Action` |`post_speechPaused` |Triggered when speech is paused or resumed.|
 |`Filter` |`filter_speechSequence` |Allows components or add-ons to filter speech sequence before it passes to the synth driver.|
 
 ### synthDriverHandler {#synthDriverHandlerExtPts}

source/inputCore.py

@@ -452,6 +452,22 @@ def __eq__(self, other: Any) -> bool:
 		return NotImplemented
 
 
+decide_handleRawKey = extensionPoints.Decider()
+"""
+Notifies when a raw keyboard event is received, before any NVDA processing.
+Handlers can decide whether the key should be processed by NVDA and/or passed to the OS.
+:param vkCode: The virtual key code
+:type vkCode: int
+:param scanCode: The scan code
+:type scanCode: int
+:param extended: Whether this is an extended key
+:type extended: bool
+:param pressed: Whether this is a key press or release
+:type pressed: bool
+:return: True to allow normal processing, False to block the key
+:rtype: bool
+"""
+
 decide_executeGesture = extensionPoints.Decider()
 """
 Notifies when a gesture is about to be executed,

source/keyboardHandler.py

@@ -165,6 +165,13 @@ def shouldUseToUnicodeEx(focus: Optional["NVDAObject"] = None):
 
 def internal_keyDownEvent(vkCode, scanCode, extended, injected):
 	"""Event called by winInputHook when it receives a keyDown."""
+	if not inputCore.decide_handleRawKey.decide(
+		vkCode=vkCode,
+		scanCode=scanCode,
+		extended=extended,
+		pressed=True,
+	):
+		return False
 	gestureExecuted = False
 	try:
 		global \
@@ -313,6 +320,13 @@ def internal_keyDownEvent(vkCode, scanCode, extended, injected):
 
 def internal_keyUpEvent(vkCode, scanCode, extended, injected):
 	"""Event called by winInputHook when it receives a keyUp."""
+	if not inputCore.decide_handleRawKey.decide(
+		vkCode=vkCode,
+		scanCode=scanCode,
+		extended=extended,
+		pressed=False,
+	):
+		return False
 	try:
 		global \
 			lastNVDAModifier, \

source/speech/__init__.py

@@ -63,7 +63,7 @@
 	spellTextInfo,
 	splitTextIndentation,
 )
-from .extensions import speechCanceled
+from .extensions import speechCanceled, post_speechPaused
 from .priorities import Spri
 
 from .types import (
@@ -142,6 +142,7 @@
 	"spellTextInfo",
 	"splitTextIndentation",
 	"speechCanceled",
+	"post_speechPaused",
 ]
 
 import synthDriverHandler

source/speech/extensions.py

@@ -22,6 +22,14 @@
 Handlers are called without arguments.
 """
 
+post_speechPaused = Action()
+"""
+Notifies when speech is paused.
+
+:param switch: True if speech is paused, False if speech is resumed.
+:type switch: bool
+"""
+
 pre_speech = Action()
 """
 Notifies when code attempts to speak text.

source/speech/speech.py

@@ -27,7 +27,7 @@
 from textUtils import unicodeNormalize
 from textUtils.uniscribe import splitAtCharacterBoundaries
 from . import manager
-from .extensions import speechCanceled, pre_speechCanceled, pre_speech
+from .extensions import speechCanceled, post_speechPaused, pre_speechCanceled, pre_speech
 from .extensions import filter_speechSequence
 from .commands import (
 	# Commands that are used in this file.
@@ -211,6 +211,7 @@ def cancelSpeech():
 
 def pauseSpeech(switch):
 	getSynth().pause(switch)
+	post_speechPaused.notify(switch=switch)
 	_speechState.isPaused = switch
 	_speechState.beenCanceled = False
 

tests/unit/test_speech.py

@@ -16,7 +16,9 @@
 	_getSpellingSpeechAddCharMode,
 	_getSpellingSpeechWithoutCharMode,
 	cancelSpeech,
+	pauseSpeech,
 	speechCanceled,
+	post_speechPaused,
 )
 from speech.commands import (
 	BeepCommand,
@@ -591,3 +593,10 @@ def test_speechCanceledExtensionPoint(self):
 			speechCanceled,
 		):
 			cancelSpeech()
+
+	def test_post_speechPausedExtensionPoint(self):
+		with actionTester(self, post_speechPaused, switch=True):
+			pauseSpeech(True)
+
+		with actionTester(self, post_speechPaused, switch=False):
+			pauseSpeech(False)

user_docs/en/changes.md

@@ -111,7 +111,9 @@ Add-ons will need to be re-tested and have their manifest updated.
 * Retrieving the `labeledBy` property now works for:
   * objects in applications implementing the `labelled-by` IAccessible2 relation. (#17436, @michaelweghorn)
   * UIA elements supporting the corresponding `LabeledBy` UIA property. (#17442, @michaelweghorn)
-
+* Added the following extension points (#17428, @ctoth):
+  * `inputCore.decide_handleRawKey`: called on each keypress
+  * `speech.extensions.post_speechPaused`: called when speech is paused or unpaused
 
 #### API Breaking Changes