Merge da686b8 into 6dd9002

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.
@@ -1871,11 +1876,53 @@ class BrailleHandler(baseObject.AutoPropertyObject):
 	queuedWriteLock: threading.Lock
 	ackTimerHandle: int
 
+	#: 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
+	#: @param currentCellCount: The current number of cells
+	#: @type currentCellCount: bool
+	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
+	filter_displaySize: extensionPoints.Filter
+	#: Action that allows components or add-ons to be notified of display size changes.
+	#: For example, when a system is controlled by a remote system and the remote system swaps displays,
+	#: The local system should be notified about display size changes at the remote system.
+	#: @param displaySize: The current display size used by the braille handler.
+	#: @type displaySize: int
+	displaySizeChanged: extensionPoints.Action
+	#: Action that allows components or add-ons to be notified of braille display changes.
+	#: For example, when a system is controlled by a remote system and the remote system swaps displays,
+	#: The local system should be notified about display parameters at the remote system,
+	#: e.g. name and cellcount.
+	#: @param display: The new braille display driver
+	#: @type display: L{BrailleDisplayDriver}
+	#: @param isFallback: Whether the display is set as fallback display due to another display's failure
+	#: @type isFallback: bool
+	#: @param detected: If the display was set by auto detection, the device match that matched the driver
+	#: @type detected: bdDetect.DeviceMatch or C{None}
+	displayChanged: extensionPoints.Action
+	#: 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.
+	decide_enabled: extensionPoints.Decider
+
 	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}
+		#: Internal cache for the displaySize property.
+		#: This attribute is used to compare the displaySize output by l{filterDisplaySize}
+		#: with its previous output.
+		#: If the value differs, L{displaySizeChanged} is notified.
 		self._displaySize: int = 0
 		self.mainBuffer = BrailleBuffer(self)
 		self.messageBuffer = BrailleBuffer(self)
@@ -1901,6 +1948,12 @@ def __init__(self):
 
 		brailleViewer.postBrailleViewerToolToggledAction.register(self._onBrailleViewerChangedState)
 
+		self.pre_writeCells = extensionPoints.Action()
+		self.filter_displaySize = extensionPoints.Filter()
+		self.displaySizeChanged = extensionPoints.Action()
+		self.displayChanged = extensionPoints.Action()
+		self.decide_enabled = extensionPoints.Decider()
+
 	def terminate(self):
 		self._disableDetection()
 		if self._messageCallLater:
@@ -1937,22 +1990,49 @@ def _get_shouldAutoTether(self) -> bool:
 		return self.enabled and config.conf["braille"]["tetherTo"] == TetherTo.AUTO.value
 
 	displaySize: int
+	_cache_displaySize = True
 
 	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.
+		"""
+		numCells = self.display.numCells if self.display else 0
+		currentDisplaySize = self.filter_displaySize.apply(numCells)
+		if self._displaySize != currentDisplaySize:
+			self.displaySizeChanged.notify(displaySize=currentDisplaySize)
+			self._displaySize = currentDisplaySize
+		return currentDisplaySize
+
+	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.
 		"""
-		self._displaySize = numCells
+		raise AttributeError(
+			f"Can't set displaySize to {value}, consider registering a handler to filter_displaySize"
+		)
 
 	enabled: bool
+	_cache_enabled = True
 
 	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,
@@ -1996,7 +2076,8 @@ def setDisplayByName(  # noqa: C901
 			oldDisplay = self.display
 			if detected and bdDetect._isDebug():
 				log.debug("Possibly detected display '%s'" % newDisplay.description)
-			if newDisplay == oldDisplay.__class__:
+			sameDisplayReinit = newDisplay == oldDisplay.__class__
+			if sameDisplayReinit:
 				# This is the same driver as was already set, so just re-initialise it.
 				log.debug("Reinitializing %s braille display"%name)
 				oldDisplay.terminate()
@@ -2021,7 +2102,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,
@@ -2036,6 +2116,12 @@ def setDisplayByName(  # noqa: C901
 			queueHandler.queueFunction(queueHandler.eventQueue, self.initialDisplay)
 			if detected and 'bluetoothName' in detected.deviceInfo:
 				self._enableDetection(bluetooth=False, keepCurrentDisplay=True, limitToDevices=[name])
+			# #14503: optimization, avoid notifications of unnecessary re-initialization
+			# of the noBraille display
+			# When setDisplayByName is refactored, ensure that braille display detection no longer triggers
+			# an unnecessary reinit of noBraille.
+			if not (sameDisplayReinit and newDisplay.name == "noBraille"):
+				self.displayChanged.notify(display=newDisplay, isFallback=isFallback, detected=detected)
 			return True
 		except:
 			# For auto display detection, logging an error for every failure is too obnoxious.
@@ -2068,7 +2154,26 @@ def _updateDisplay(self):
 			wx.CallAfter(self._cursorBlinkTimer.Start,blinkRate)
 
 	def _writeCells(self, cells: List[int]):
-		brailleViewer.update(cells, self._rawText)
+		handlerCellCount = self.displaySize
+		self.pre_writeCells.notify(cells=cells, rawText=self._rawText, currentCellCount=handlerCellCount)
+		displayCellCount = self.display.numCells
+		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
@@ -63,20 +62,16 @@ def isBrailleViewerActive() -> bool:
 	return bool(_brailleGui)
 
 
-def update(cells: List[int], rawText: str):
-	if _brailleGui:
-		_brailleGui.updateBrailleDisplayed(
-			cells,
-			rawText,
-			_getDisplaySize()
-		)
-
-
 def destroyBrailleViewer():
 	global _brailleGui
 	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.
+		updateBrailleDisplayedUnregistered = braille.handler.pre_writeCells.unregister(d.updateBrailleDisplayed)
+		assert updateBrailleDisplayedUnregistered
+		getDisplaySizeUnregistered = braille.handler.filter_displaySize.unregister(_getDisplaySize)
+		assert getDisplaySizeUnregistered
 		d.saveInfoAndDestroy()
 
 
@@ -91,9 +86,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,13 +98,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)
+
 	global _brailleGui
 	if _brailleGui:
 		destroyBrailleViewer()
 
 	_brailleGui = BrailleViewerFrame(
-		_getDisplaySize(),
+		braille.handler.displaySize,
 		_onGuiDestroyed
 	)
-
+	braille.handler.pre_writeCells.register(_brailleGui.updateBrailleDisplayed)
 	postBrailleViewerToolToggledAction.notify(created=True)

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)):