Merge f8c3c50 into a34da14

Author: LeonarddeR

source/braille.py

@@ -1,7 +1,7 @@
 # A part of NonVisual Desktop Access (NVDA)
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-# Copyright (C) 2008-2022 NV Access Limited, Joseph Lee, Babbage B.V., Davy Kager, Bram Duvigneau,
+# Copyright (C) 2008-2023 NV Access Limited, Joseph Lee, Babbage B.V., Davy Kager, Bram Duvigneau,
 # Leonard de Ruijter
 
 import itertools
@@ -304,6 +304,11 @@
 )
 SELECTION_SHAPE = 0xC0 #: Dots 7 and 8
 
+#: The braille shape shown on a braille display when
+#: the number of cells used by the braille handler is lower than the actual number of cells.
+#: The 0 based position of the shape is equal to the number of cells used by the braille handler.
+END_OF_BRAILLE_OUTPUT_SHAPE = 0xFF  # All dots
+
 #: Unicode braille indicator at the start of untranslated braille input.
 INPUT_START_IND = u"⣏"
 #: Unicode braille indicator at the end of untranslated braille input.
@@ -1874,9 +1879,6 @@ class BrailleHandler(baseObject.AutoPropertyObject):
 	def __init__(self):
 		louisHelper.initialize()
 		self.display: Optional[BrailleDisplayDriver] = None
-		#: Number of cells the connected device (or if no device connected, what braille viewer has)
-		#: Zero cells disables braille. See L{_get_enabled}
-		self._displaySize: int = 0
 		self.mainBuffer = BrailleBuffer(self)
 		self.messageBuffer = BrailleBuffer(self)
 		self._messageCallLater = None
@@ -1901,6 +1903,29 @@ def __init__(self):
 
 		brailleViewer.postBrailleViewerToolToggledAction.register(self._onBrailleViewerChangedState)
 
+		#: Notifies when cells are about to be written to a braille display.
+		#: This allows components and add-ons to perform an action.
+		#: For example, when a system is controlled by a braille enabled remote system,
+		#: the remote system should know what cells to show on its display.
+		#: @param cells: The list of braille cells.
+		#: @type cells: [int]
+		#: @param rawText: The raw text that corresponds with the cells.
+		#: @type rawText: str
+		self.pre_writeCells = extensionPoints.Action()
+
+		#: Filter that allows components or add-ons to change the display size used for braille output.
+		#: For example, when a system is controlled by a remote system while having a 80 cells display connected,
+		#: the display size should be lowered to 40 whenever the remote system has a 40 cells display connected.
+		#: @param value: the number of cells of the current display.
+		#: @type value: int
+		self.filter_displaySize = extensionPoints.Filter()
+
+		#: Allows components or add-ons to decide whether the braille handler should be forcefully disabled.
+		#: For example, when a system is controlling a remote system with braille,
+		#: the local braille handler should be disabled as long as the system is in control of the remote system.
+		#: Handlers are called without arguments.
+		self.decide_enabled = extensionPoints.Decider()
+
 	def terminate(self):
 		self._disableDetection()
 		if self._messageCallLater:
@@ -1939,20 +1964,41 @@ def _get_shouldAutoTether(self) -> bool:
 	displaySize: int
 
 	def _get_displaySize(self):
-		if self._displaySize == 0 and brailleViewer.isBrailleViewerActive():
-			return brailleViewer.DEFAULT_NUM_CELLS
-		return self._displaySize
-
-	def _set_displaySize(self, numCells):
-		"""The display size can be changed while a display is connected, for instance
-			see L{brailleDisplayDrivers.alva.BrailleDisplayDriver} split point feature.
+		"""Returns the display size to use for braille output.
+		Handlers can register themselves to L{filter_displaySize} to change this value on the fly.
+		Therefore, this is a read only property and can't be set.
 		"""
-		self._displaySize = numCells
+		numCells = self.display.numCells if self.display else 0
+		return self.filter_displaySize.apply(numCells)
+
+	def _set_displaySize(self, value):
+		"""While the display size can be changed while a display is connected
+		(for instance see L{brailleDisplayDrivers.alva.BrailleDisplayDriver} split point feature),
+		it is not possible to override the display size using this property.
+		Consider registering a handler to L{filter_displaySize} instead.
+		"""
+		raise AttributeError(
+			f"Can't set displaySize to {value}, consider registering a handler to filter_displaySize"
+		)
 
 	enabled: bool
 
 	def _get_enabled(self):
-		return bool(self.displaySize)
+		"""Returns whether braille is enabled.
+		Handlers can register themselves to L{decide_enabled} and return C{False}
+		to forcefully disable the braille handler.
+		If components need to change the state from disabled to enabled instead,
+		they should register to L{filter_displaySize}.
+		By default, the enabled/disabled state is based on the boolean value of L{displaySize},
+		and thus is C{True} when the display size is greater than 0.
+		This is a read only property and can't be set.
+		"""
+		return bool(self.displaySize) and self.decide_enabled.decide()
+
+	def _set_enabled(self, value):
+		raise AttributeError(
+			f"Can't set enabled to {value}, consider registering a handler to decide_enabled or filter_displaySize"
+		)
 
 	_lastRequestedDisplayName = None
 	"""The name of the last requested braille display driver with setDisplayByName,
@@ -2021,7 +2067,6 @@ def setDisplayByName(  # noqa: C901
 						log.error("Error terminating previous display driver", exc_info=True)
 				self.display = newDisplay
 			newDisplay.initSettings()
-			self._displaySize = newDisplay.numCells
 			if isFallback:
 				if self._detectionEnabled and not self._detector:
 					# As this is the fallback display, which is usually noBraille,
@@ -2068,7 +2113,26 @@ def _updateDisplay(self):
 			wx.CallAfter(self._cursorBlinkTimer.Start,blinkRate)
 
 	def _writeCells(self, cells: List[int]):
-		brailleViewer.update(cells, self._rawText)
+		self.pre_writeCells.notify(cells=cells, rawText=self._rawText)
+		displayCellCount = self.display.numCells
+		handlerCellCount = self.displaySize
+		if not displayCellCount:
+			# No physical display to write to
+			return
+		# Braille displays expect cells to be padded up to displayCellCount.
+		# However, the braille handler uses handlerCellCount to calculate the number of cells.
+		cellCountDif = displayCellCount - len(cells)
+		if cellCountDif < 0:
+			# There are more cells than the connected display could take.
+			log.warning(
+				f"Connected display {self.display.name!r} has {displayCellCount} cells, "
+				f"while braille handler is using {handlerCellCount} cells"
+			)
+			cells = cells[:displayCellCount]
+		elif cellCountDif > 0:
+			# The connected display could take more cells than the braille handler produces.
+			# Displays expect cells to be padded up to the number of cells.
+			cells += [END_OF_BRAILLE_OUTPUT_SHAPE] + [0] * (cellCountDif - 1)
 		if not self.display.isThreadSafe:
 			try:
 				self.display.display(cells)

source/brailleDisplayDrivers/alva.py

@@ -124,7 +124,6 @@ def _get_model(self):
 		return self.model
 
 	def _updateSettings(self):
-		oldNumCells = self.numCells
 		if self.isHid:
 			displaySettings = self._dev.getFeature(ALVA_DISPLAY_SETTINGS_REPORT)
 			if displaySettings[ALVA_DISPLAY_SETTINGS_STATUS_CELL_SIDE_POS] > 1:
@@ -152,9 +151,6 @@ def _updateSettings(self):
 			self._ser6SendMessage(b"H", b"?")
 			# Get HID keyboard input state
 			self._ser6SendMessage(b"r", b"?")
-		if oldNumCells not in (0, self.numCells):
-			# In case of splitpoint changes, we need to update the braille handler as well
-			braille.handler.displaySize = self.numCells
 
 	def __init__(self, port="auto"):
 		super(BrailleDisplayDriver,self).__init__()

source/brailleViewer/__init__.py

@@ -1,6 +1,5 @@
-# brailleViewer.py
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2014-2019 NV Access Limited
+# Copyright (C) 2014-2023 NV Access Limited, Leonard de Ruijter
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 from typing import Optional, List
@@ -65,10 +64,11 @@ def isBrailleViewerActive() -> bool:
 
 def update(cells: List[int], rawText: str):
 	if _brailleGui:
+		import braille  # imported late to avoid a circular import.
 		_brailleGui.updateBrailleDisplayed(
 			cells,
 			rawText,
-			_getDisplaySize()
+			braille.handler.displaySize
 		)
 
 
@@ -77,6 +77,9 @@ def destroyBrailleViewer():
 	d: Optional[BrailleViewerFrame] = _brailleGui
 	_brailleGui = None  # protect against re-entrance
 	if d and not d.isDestroyed:
+		import braille  # imported late to avoid a circular import.
+		braille.handler.pre_writeCells.unregister(update)
+		braille.handler.filter_displaySize.unregister(_getDisplaySize)
 		d.saveInfoAndDestroy()
 
 
@@ -91,9 +94,7 @@ def _onGuiDestroyed():
 	postBrailleViewerToolToggledAction.notify(created=False)
 
 
-def _getDisplaySize():
-	import braille  # imported late to avoid a circular import.
-	numCells = braille.handler.displaySize
+def _getDisplaySize(numCells: int):
 	return numCells if numCells > 0 else DEFAULT_NUM_CELLS
 
 
@@ -105,12 +106,15 @@ def createBrailleViewerTool():
 	if not braille.handler:
 		raise RuntimeError("Can not initialise the BrailleViewerGui: braille.handler not yet initialised")
 
+	braille.handler.filter_displaySize.register(_getDisplaySize)
+	braille.handler.pre_writeCells.register(update)
+
 	global _brailleGui
 	if _brailleGui:
 		destroyBrailleViewer()
 
 	_brailleGui = BrailleViewerFrame(
-		_getDisplaySize(),
+		braille.handler.displaySize,
 		_onGuiDestroyed
 	)
 

source/extensionPoints/__init__.py

@@ -80,7 +80,7 @@ class Filter(HandlerRegistrar):
 	>>> messageFilter.register(filterMessage)
 
 	When filtering is desired, all registered handlers are called to filter the data, see L{util.callWithSupportedKwargs}
-	for how args passed to notify are mapped to the handler:
+	for how args passed to apply are mapped to the handler:
 
 	>>> messageFilter.apply("This is a message", someArg=42)
 	'This is a message which has been filtered'
@@ -125,7 +125,7 @@ class Decider(HandlerRegistrar):
 
 	When the decision is to be made, registered handlers are called until
 	a handler returns False, see L{util.callWithSupportedKwargs}
-	for how args passed to notify are mapped to the handler:
+	for how args passed to decide are mapped to the handler:
 
 	>>> doSomething.decide(someArg=42)
 	False
@@ -175,9 +175,9 @@ class AccumulatingDecider(HandlerRegistrar):
 	...
 	>>> doSomething.register(shouldDoSomething)
 
-	When the decision is to be made registered handlers are called and they return values are collected,
+	When the decision is to be made registered handlers are called and their return values are collected,
 	see L{util.callWithSupportedKwargs}
-	for how args passed to notify are mapped to the handler:
+	for how args passed to decide are mapped to the handler:
 
 	>>> doSomething.decide(someArg=42)
 	False

source/inputCore.py

@@ -40,6 +40,7 @@
 import languageHandler
 import controlTypes
 import winKernel
+import extensionPoints
 
 
 InputGestureBindingClassT = TypeVar("InputGestureBindingClassT")
@@ -253,19 +254,21 @@ def clear(self):
 		self._map.clear()
 		self.lastUpdateContainedError = False
 
-	def add(self, gesture, module, className, script,replace=False):
+	def add(
+			self,
+			gesture: str,
+			module: str,
+			className: str,
+			script: Optional[str],
+			replace: bool = False
+	):
 		"""Add a gesture mapping.
 		@param gesture: The gesture identifier.
-		@type gesture: str
 		@param module: The name of the Python module containing the target script.
-		@type module: str
 		@param className: The name of the class in L{module} containing the target script.
-		@type className: str
 		@param script: The name of the target script
 			or C{None} to unbind the gesture for this class.
-		@type script: str
 		@param replace: if true replaces all existing bindings for this gesture with the given script, otherwise only appends this binding.
-		@type replace: boolean
 		"""
 		gesture = normalizeGestureIdentifier(gesture)
 		try:
@@ -449,6 +452,15 @@ def __init__(self):
 		self.loadUserGestureMap()
 		self._lastInputTime = None
 
+		#: Notifies when a gesture is about to be executed,
+		#: and allows components or add-ons to decide whether or not to execute a gesture.
+		#: For example, when controlling a remote system with a connected local braille display,
+		#: braille display gestures should not be executed locally.
+		#: Handlers are called with one argument:
+		#: @param gesture: The gesture that is about to be executed.
+		#: @type gesture: L{InputGesture}
+		self.decide_executeGesture = extensionPoints.Decider()
+
 	def executeGesture(self, gesture):
 		"""Perform the action associated with a gesture.
 		@param gesture: The gesture to execute.
@@ -461,6 +473,15 @@ def executeGesture(self, gesture):
 			# as well as stopping a flood of actions when the core revives.
 			raise NoInputGestureAction
 
+		if not self.decide_executeGesture.decide(gesture=gesture):
+			# A registered handler decided that this gesture shouldn't be executed.
+			# Purposely do not raise a NoInputGestureAction here, as that could
+			# lead to unexpected behavior for gesture emulation.
+			log.debug(
+				"Gesture execution canceled by handler registered to decide_executeGesture extension point"
+			)
+			return
+
 		script = gesture.script
 		focus = api.getFocusObject()
 		if focus.sleepMode is focus.SLEEP_FULL or (focus.sleepMode and not getattr(script, 'allowInSleepMode', False)):

source/nvwave.py

@@ -1,5 +1,6 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2007-2021 NV Access Limited, Aleksey Sadovoy, Cyrille Bougot, Peter Vágner
+# Copyright (C) 2007-2021 NV Access Limited, Aleksey Sadovoy, Cyrille Bougot, Peter Vágner, Babbage B.V.,
+# Leonard de Ruijter
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
@@ -37,16 +38,30 @@
 import config
 from logHandler import log
 import os.path
+import extensionPoints
+
 
 __all__ = (
-	"WavePlayer", "getOutputDeviceNames", "outputDeviceIDToName", "outputDeviceNameToID",
+	"WavePlayer",
+	"getOutputDeviceNames",
+	"outputDeviceIDToName",
+	"outputDeviceNameToID",
+	"decide_playWaveFile",
 )
 
 winmm = windll.winmm
 
 HWAVEOUT = HANDLE
 LPHWAVEOUT = POINTER(HWAVEOUT)
 
+#: Notifies when a wave file is about to be played,
+#: and allows components or add-ons to decide whether the wave file should be played.
+#: For example, when controlling a remote system,
+#: the remote system must be notified of sounds played on the local system.
+#: Also, registrars should be able to suppress playing sounds if desired.
+#: Handlers are called with the same arguments as L{playWaveFile} as keyword arguments.
+decide_playWaveFile = extensionPoints.Decider()
+
 class WAVEFORMATEX(Structure):
 	_fields_ = [
 		("wFormatTag", WORD),
@@ -627,16 +642,31 @@ def outputDeviceNameToID(name: str, useDefaultIfInvalid=False) -> int:
 fileWavePlayerThread = None
 
 
-def playWaveFile(fileName, asynchronous=True):
+def playWaveFile(
+		fileName: str,
+		asynchronous: bool = True,
+		isSpeechWaveFileCommand: bool = False
+):
 	"""plays a specified wave file.
+	@param fileName: the path to the wave file, usually absolute.
 	@param asynchronous: whether the wave file should be played asynchronously
-	@type asynchronous: bool
+		If C{False}, the calling thread is blocked until the wave has finished playing.
+	@param isSpeechWaveFileCommand: whether this wave is played as part of a speech sequence.
 	"""
 	global fileWavePlayer, fileWavePlayerThread
 	f = wave.open(fileName,"r")
 	if f is None: raise RuntimeError("can not open file %s"%fileName)
 	if fileWavePlayer is not None:
 		fileWavePlayer.stop()
+	if not decide_playWaveFile.decide(
+		fileName=fileName,
+		asynchronous=asynchronous,
+		isSpeechWaveFileCommand=isSpeechWaveFileCommand
+	):
+		log.debug(
+			"Playing wave file canceled by handler registered to decide_playWaveFile extension point"
+		)
+		return
 	fileWavePlayer = WavePlayer(
 		channels=f.getnchannels(),
 		samplesPerSec=f.getframerate(),