Merge 6158795 into 0c0d88a

Author: feerrenrut

source/braille.py

@@ -36,7 +36,7 @@
 import extensionPoints
 import hwPortUtils
 import bdDetect
-import winUser
+import brailleViewer
 import queueHandler
 
 roleLabels = {
@@ -1205,7 +1205,6 @@ def _get_regionsWithPositions(self):
 			yield RegionWithPositions(region, start, end)
 			start = end
 
-	_cache_rawToBraillePos=True
 	def _get_rawToBraillePos(self):
 		"""@return: a list mapping positions in L{rawText} to positions in L{brailleCells} for the entire buffer.
 		@rtype: [int, ...]
@@ -1215,7 +1214,8 @@ def _get_rawToBraillePos(self):
 			rawToBraillePos.extend(p+regionStart for p in region.rawToBraillePos)
 		return rawToBraillePos
 
-	_cache_brailleToRawPos=True
+	brailleToRawPos: List[int]
+
 	def _get_brailleToRawPos(self):
 		"""@return: a list mapping positions in L{brailleCells} to positions in L{rawText} for the entire buffer.
 		@rtype: [int, ...]
@@ -1250,7 +1250,25 @@ def regionPosToBufferPos(self, region, pos, allowNearest=False):
 		raise LookupError("No such position")
 
 	def bufferPositionsToRawText(self, startPos, endPos):
-		return self.rawText[self.brailleToRawPos[startPos]:self.brailleToRawPos[endPos-1]+1]
+		brailleToRawPos = self.brailleToRawPos
+		if not brailleToRawPos or not self.rawText:
+			# if either are empty, just return an empty string.
+			return ""
+		try:
+			lastIndex = len(brailleToRawPos) - 1
+			rawTextStart = brailleToRawPos[min(lastIndex, startPos)]
+			rawTextEnd = brailleToRawPos[min(lastIndex, endPos)] + 1
+			lastIndex = len(self.rawText)
+			return self.rawText[rawTextStart:min(lastIndex, rawTextEnd)]
+		except IndexError:
+			log.debugWarning(
+				f"Unable to get raw text for buffer positions"
+				f"(startPos-endPos): {startPos}-{endPos}, "
+				f"for rawText: {self.rawText}, "
+				f"with brailleToRawPos: {brailleToRawPos}",
+				exc_info=True
+			)
+			return ""
 
 	def bufferPosToWindowPos(self, bufferPos):
 		if not (self.windowStartPos <= bufferPos < self.windowEndPos):
@@ -1589,14 +1607,13 @@ class BrailleHandler(baseObject.AutoPropertyObject):
 	def __init__(self):
 		louisHelper.initialize()
 		self.display: Optional[BrailleDisplayDriver] = None
-		self.displaySize = 0
+		#: 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
 		self.buffer = self.mainBuffer
-		#: Whether braille is enabled.
-		#: @type: bool
-		self.enabled = False
 		self._keyCountForLastMessage=0
 		self._cursorPos = None
 		self._cursorBlinkUp = True
@@ -1606,6 +1623,8 @@ def __init__(self):
 		self._tether = config.conf["braille"]["tetherTo"]
 		self._detectionEnabled = False
 		self._detector = None
+		self._rawText = u""
+		brailleViewer.postBrailleViewerToolToggledAction.register(self._onBrailleViewerChangedState)
 
 	def terminate(self):
 		bgThreadStopTimeout = 2.5 if self._detectionEnabled else None
@@ -1639,6 +1658,24 @@ def setTether(self, tether, auto=False):
 	def _get_shouldAutoTether(self):
 		return self.enabled and config.conf["braille"]["autoTether"]
 
+	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.
+		"""
+		self._displaySize = numCells
+
+	enabled: bool
+
+	def _get_enabled(self):
+		return bool(self.displaySize)
+
 	_lastRequestedDisplayName=None #: the name of the last requested braille display driver with setDisplayByName, even if it failed and has fallen back to no braille.
 	def setDisplayByName(self, name, isFallback=False, detected=None):
 		if not isFallback:
@@ -1666,13 +1703,14 @@ def setDisplayByName(self, name, isFallback=False, detected=None):
 
 		try:
 			newDisplay = _getDisplayDriver(name)
+			oldDisplay = self.display
 			if detected and bdDetect._isDebug():
 				log.debug("Possibly detected display '%s'" % newDisplay.description)
-			if newDisplay == self.display.__class__:
+			if newDisplay == oldDisplay.__class__:
 				# This is the same driver as was already set, so just re-initialise it.
 				log.debug("Reinitializing %s braille display"%name)
-				self.display.terminate()
-				newDisplay = self.display
+				oldDisplay.terminate()
+				newDisplay = oldDisplay
 				try:
 					newDisplay.__init__(**kwargs)
 				except TypeError:
@@ -1697,8 +1735,7 @@ def setDisplayByName(self, name, isFallback=False, detected=None):
 						log.error("Error terminating previous display driver", exc_info=True)
 				self.display = newDisplay
 			newDisplay.initSettings()
-			self.displaySize = newDisplay.numCells
-			self.enabled = bool(self.displaySize)
+			self._displaySize = newDisplay.numCells
 			if isFallback:
 				if self._detectionEnabled and not self._detector:
 					# As this is the fallback display, which is usually noBraille,
@@ -1723,6 +1760,11 @@ def setDisplayByName(self, name, isFallback=False, detected=None):
 			self.setDisplayByName("noBraille", isFallback=True)
 			return False
 
+	def _onBrailleViewerChangedState(self, created):
+		if created:
+			self._updateDisplay()
+		log.debug("Braille Viewer enabled: {}".format(self.enabled))
+
 	def _updateDisplay(self):
 		if self._cursorBlinkTimer:
 			self._cursorBlinkTimer.Stop()
@@ -1740,6 +1782,7 @@ def _updateDisplay(self):
 			wx.CallAfter(self._cursorBlinkTimer.Start,blinkRate)
 
 	def _writeCells(self, cells):
+		brailleViewer.update(cells, self._rawText)
 		if not self.display.isThreadSafe:
 			try:
 				self.display.display(cells)
@@ -1775,6 +1818,7 @@ def _blink(self):
 
 	def update(self):
 		cells = self.buffer.windowBrailleCells
+		self._rawText = self.buffer.windowRawText
 		if log.isEnabledFor(log.IO):
 			log.io("Braille window dots: %s" % formatCellsForLog(cells))
 		# cells might not be the full length of the display.

source/brailleViewer/__init__.py

@@ -0,0 +1,122 @@
+# brailleViewer.py
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2014-2019 NV Access Limited
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+from typing import Optional, List
+
+import gui
+import extensionPoints
+from .brailleViewerGui import BrailleViewerFrame
+
+"""
+### Overview
+This package contains the components for a "Braille Viewer". A window, that shows the braille dots that
+would be displayed on a hardware device. The raw text for each cell is also shown.
+This tool consists of:
+- A GUI for the viewer.
+- Construction / destruction / update helpers.
+
+The current intention is to be able to support a physical braille device while using the "Braille Viewer".
+Due to limitations in the design of brailleHandler, the number of cells in the "Braille Viewer" must match any
+connected physical device.
+
+### Life-cycle
+- Constructing / showing the BrailleViewer
+	- On startup via L{core.doStartupDialogs}
+	- Via NVDA (tools) menu via L{Mainframe.onToggleSpeechViewerCommand}
+- Hiding / destroying the BrailleViewer
+	- On exit of NVDA.
+	- Via NVDA (tools) menu via L{Mainframe.onToggleSpeechViewerCommand}
+	- When the Window receives a close event. This means the GUI must be able to call-back to clean up
+	BrailleHandler and the NVDA tools menu. This callback happens via the L{postBrailleViewerToolToggledAction}
+
+### Number of cells shown
+The default (40) is set in L{createBrailleViewerTool}.
+
+### Routing
+Currently not supported.
+In order to support routing the user must be able to click on the cells. This means that the BrailleViewer
+window gains focus, and the braille values are changed. To avoid this would require substantial changes to
+brailleHandler.
+
+### Scrolling
+Scrolling is supported by binding a gesture to the braille_scroll_forward and braille scroll_back commands.
+For the same reason that Routing is not supported, scrolling via button clicks on the braille viewer window
+is not supported.
+
+"""
+
+# global braille viewer driver:
+_brailleGui: Optional[BrailleViewerFrame] = None
+
+# Extension points action:
+# Triggered every time the Braille Viewer is created / shown or hidden / destroyed.
+# Callback definition: Callable(created: bool) -> None
+#   created - True for created/shown, False for hidden/destructed.
+postBrailleViewerToolToggledAction = extensionPoints.Action()
+# Devices with 40 cells are quite common.
+DEFAULT_NUM_CELLS = 40
+
+
+def isBrailleViewerActive() -> bool:
+	return bool(_brailleGui)
+
+
+def update(cells: List[int], rawText: str):
+	if _brailleGui:
+		_brailleGui.updateBrailleDisplayed(
+			cells,
+			rawText,
+			_getDisplaySize()
+		)
+
+
+def _destroyGUI():
+	global _brailleGui
+	d: Optional[BrailleViewerFrame] = _brailleGui
+	_brailleGui = None
+	if d and not d.isDestroyed:
+		d.Destroy()
+
+
+def destroyBrailleViewer():
+	_destroyGUI()
+	postBrailleViewerToolToggledAction.notify(created=False)
+
+
+def _onGuiDestroyed():
+	""" Used as a callback from L{BrailleViewerFrame}, lets us know that the GUI initiated a destruction.
+	"""
+	global _brailleGui
+	if _brailleGui:
+		# Destruction wasn't initiated from L{_destroyGUI} ie not through direct user action.
+		# It's likely that the window received a shutdown event that could not be skipped.
+		# Continue to destroy the braille viewer.
+		destroyBrailleViewer()
+
+
+def _getDisplaySize():
+	import braille  # imported late to avoid a circular import.
+	numCells = braille.handler.displaySize
+	return numCells if numCells > 0 else DEFAULT_NUM_CELLS
+
+
+def createBrailleViewerTool():
+	if not gui.mainFrame:
+		raise RuntimeError("Can not initialise the BrailleViewerGui: gui.mainFrame not yet initialised")
+
+	import braille  # imported late to avoid a circular import.
+	if not braille.handler:
+		raise RuntimeError("Can not initialise the BrailleViewerGui: braille.handler not yet initialised")
+
+	global _brailleGui
+	if _brailleGui:
+		_destroyGUI()
+
+	_brailleGui = BrailleViewerFrame(
+		_getDisplaySize(),
+		_onGuiDestroyed
+	)
+
+	postBrailleViewerToolToggledAction.notify(created=True)