feerrenrut · Oct 13, 2021 · Oct 8, 2021 · Oct 8, 2021 · Oct 8, 2021 · Oct 8, 2021
@@ -702,8 +702,10 @@ def getControlFieldBraille(  # noqa: C901
 	_descriptionIsContent: bool = field.get("descriptionIsContent", False)
 	if (
 		not _descriptionIsContent
-		and config.conf["presentation"]["reportObjectDescriptions"]
-		or (
+		# Note "reportObjectDescriptions" is not a reason to include description,
+		# "Object" implies focus/object nav, getControlFieldBraille calculates text for Browse mode.
+		# There is no way to identify getControlFieldBraille being called for reason focus, as is done in speech.
+		and (
 			config.conf["annotations"]["reportAriaDescription"]
 			and _descriptionFrom == controlTypes.DescriptionFrom.ARIA_DESCRIPTION
 		)

@@ -46,6 +46,7 @@
 import keyboardHandler
 import characterProcessing
 from . import guiHelper
+
 try:
 	import updateCheck
 except RuntimeError:
@@ -61,6 +62,10 @@
 import keyLabels
 from .dpiScalingHelper import DpiScalingHelperMixinWithoutInit
 
+#: The size that settings panel text descriptions should be wrapped at.
+# Ensure self.scaleSize is used to adjust for OS scaling adjustments.
+PANEL_DESCRIPTION_WIDTH = 544
+
 class SettingsDialog(
 		DpiScalingHelperMixinWithoutInit,
 		gui.contextHelp.ContextHelpMixin,
@@ -1908,6 +1913,14 @@ def onSave(self):
 
 
 class ObjectPresentationPanel(SettingsPanel):
+
+	panelDescription = _(
+		# Translators: This is a label appearing on the Object Presentation settings panel.
+		"Configure how much information NVDA will present about controls."
+		" These options apply to focus reporting and NVDA object navigation,"
+		" but not when reading text content e.g. web content with browse mode."
+	)
+
 	# Translators: This is the label for the object presentation panel.
 	title = _("Object Presentation")
 	helpId = "ObjectPresentationSettings"
@@ -1932,6 +1945,12 @@ class ObjectPresentationPanel(SettingsPanel):
 
 	def makeSettings(self, settingsSizer):
 		sHelper = guiHelper.BoxSizerHelper(self, sizer=settingsSizer)
+
+		self.windowText = sHelper.addItem(
+			wx.StaticText(self, label=self.panelDescription)
+		)
+		self.windowText.Wrap(self.scaleSize(PANEL_DESCRIPTION_WIDTH))
+
 		# Translators: This is the label for a checkbox in the
 		# object presentation settings panel.
 		reportToolTipsText = _("Report &tooltips")
@@ -2975,7 +2994,7 @@ def makeSettings(self, settingsSizer):
 		warningGroup.addItem(warningText)
 
 		self.windowText = warningGroup.addItem(wx.StaticText(warningBox, label=self.warningExplanation))
-		self.windowText.Wrap(self.scaleSize(544))
+		self.windowText.Wrap(self.scaleSize(PANEL_DESCRIPTION_WIDTH))
 
 		enableAdvancedControlslabel = _(
 			# Translators: This is the label for a checkbox in the Advanced settings panel.

@@ -115,6 +115,10 @@ def __contains__(self, obj):
 		"""
 		raise NotImplementedError
 
+	#: Typing for autoproperty _get_passThrough
+	# Whether most scripts should temporarily pass through this interceptor without being intercepted.
+	passThrough: bool
+
 	def _get_passThrough(self):
 		"""Whether most scripts should temporarily pass through this interceptor without being intercepted.
 		"""

@@ -12,28 +12,38 @@
 # In Robot libraries, class name must match the name of the module. Use caps for both.
 class AssertsLib:
 	@staticmethod
-	def strings_match(actual, expected, ignore_case=False):
+	def strings_match(actual, expected, ignore_case=False, comparison="speech", message=""):
+		message += '\n' if message else ''
 		# Include expected text in robot test report so that the actual behavior
 		# can be determined entirely from the report, even when the test passes.
 		builtIn.log(
-			f"assert string matches (ignore case: {ignore_case}):  '{expected}'",
+			f"{message}assert {comparison} string matches (ignore case: {ignore_case}):  '{expected}'",
 			level="INFO"
 		)
 		try:
 			builtIn.should_be_equal_as_strings(
 				actual,
 				expected,
-				msg="Actual speech != Expected speech",
+				msg=f"{message}{comparison} Actual != Expected",
 				ignore_case=ignore_case
 			)
 		except AssertionError:
 			# Occasionally on assert failure the repr of the string makes it easier to determine the differences.
 			builtIn.log(
-				"repr of actual vs expected (ignore_case={}):\n{}\nvs\n{}".format(
+				"repr of ({}) actual vs expected (ignore_case={}):\n{}\nvs\n{}".format(
+					comparison,
 					ignore_case,
 					repr(actual),
 					repr(expected)
 				),
 				level="DEBUG"
 			)
 			raise
+
+	@staticmethod
+	def speech_matches(actual, expected, ignore_case=False, message=""):
+		AssertsLib.strings_match(actual, expected, ignore_case, comparison="speech", message=message)
+
+	@staticmethod
+	def braille_matches(actual, expected, ignore_case=False, message=""):
+		AssertsLib.strings_match(actual, expected, ignore_case, comparison="braille", message=message)
@@ -22,7 +22,10 @@
 	splitext as _splitext,
 )
 import tempfile as _tempFile
-from typing import Optional as _Optional
+from typing import (
+	Optional as _Optional,
+	Tuple as _Tuple,
+)
 from urllib.parse import quote as _quoteStr
 
 from robotremoteserver import (
@@ -405,3 +408,25 @@ def getSpeechAfterKey(key) -> str:
 	spy.wait_for_speech_to_finish(speechStartedIndex=nextSpeechIndex)
 	speech = spy.get_speech_at_index_until_now(nextSpeechIndex)
 	return speech
+
+
+def getSpeechAndBrailleAfterKey(key) -> _Tuple[str, str]:
+	"""Ensure speech has stopped, press key, and get speech until it stops, report the status of the
+	braille display.
+	@return: Tuple of Speech then Braille.
+	"""
+	spy = getSpyLib()
+	spy.wait_for_speech_to_finish()
+
+	nextSpeechIndex = spy.get_next_speech_index()
+	nextBrailleIndex = spy.get_next_braille_index()
+
+	spy.emulateKeyPress(key)
+
+	spy.wait_for_speech_to_finish(speechStartedIndex=nextSpeechIndex)
+	speech = spy.get_speech_at_index_until_now(nextSpeechIndex)
+
+	spy.wait_for_braille_update(nextBrailleIndex)
+	braille = spy.get_last_braille()
+
+	return speech, braille
@@ -26,6 +26,7 @@ def _blockUntilConditionMet(
 	"""Repeatedly tries to get a value up until a time limit expires. Tries are separated by
 	a time interval. The call will block until shouldStopEvaluator returns True when given the value,
 	the default evaluator just returns the value converted to a boolean.
+	@param errorMessage Use 'None' to suppress the exception.
 	@return A tuple, (True, value) if evaluator condition is met, otherwise (False, None)
 	@raises RuntimeError if the time limit expires and an errorMessage is given.
 	"""

@@ -11,6 +11,7 @@
 import typing
 from typing import Optional
 
+import extensionPoints
 import globalPluginHandler
 import threading
 from .blockUntilConditionMet import _blockUntilConditionMet
@@ -37,6 +38,32 @@ def _importRobotRemoteServer() -> typing.Type:
 	return RobotRemoteServer
 
 
+class BrailleViewerSpy:
+	postBrailleUpdate = extensionPoints.Action()
+
+	def __init__(self):
+		self._last = ""
+
+	def updateBrailleDisplayed(
+			self,
+			cells,  # ignored
+			rawText,
+			currentCellCount,  # ignored
+	):
+		rawText = rawText.strip()
+		if rawText and rawText != self._last:
+			self._last = rawText
+			self.postBrailleUpdate.notify(rawText=rawText)
+
+	isDestroyed: bool = False
+
+	def saveInfoAndDestroy(self):
+		if not self.isDestroyed:
+			self.isDestroyed = True
+			import brailleViewer
+			brailleViewer._onGuiDestroyed()
+
+
 class NVDASpyLib:
 	""" Robot Framework Library to spy on NVDA during system tests.
 	Used to determine if NVDA has finished starting, and various ways of getting speech output.
@@ -50,10 +77,20 @@ def __init__(self):
 			[""],  # initialise with an empty string, this allows for access via [-1]. This is equiv to no speech.
 		]
 		self._lastSpeechTime_requiresLock = _timer()
-		#: Lock to protect members written in _onNvdaSpeech.
+		#: Lock to protect members that are written to in _onNvdaSpeech.
 		self._speechLock = threading.RLock()
+
+		# braille raw text (not dots) cache is ordered temporally,
+		# oldest at low indexes, most recent at highest index.
+		self._nvdaBraille_requiresLock = [  # requires thread locking before read/write
+			"",  # initialise with an empty string, this allows for access via [-1]. This is equiv to no braille.
+		]
+		#: Lock to protect members that are written to in _onNvdaBraille.
+		self._brailleLock = threading.RLock()
+
 		self._isNvdaStartupComplete = False
 		self._allSpeechStartIndex = self.get_last_speech_index()
+		self._allBrailleStartIndex = self.get_last_braille_index()
 		self._maxKeywordDuration = 30
 		self._registerWithExtensionPoints()
 
@@ -67,6 +104,9 @@ def _registerWithExtensionPoints(self):
 		from synthDrivers.speechSpySynthDriver import post_speech
 		post_speech.register(self._onNvdaSpeech)
 
+		self._brailleSpy = BrailleViewerSpy()
+		self._brailleSpy.postBrailleUpdate.register(self._onNvdaBraille)
+
 	def set_configValue(self, keyPath: typing.List[str], val: typing.Union[str, bool, int]):
 		import config
 		if not keyPath or len(keyPath) < 1:
@@ -92,6 +132,16 @@ def queueNVDAUIAHandlerThreadCrash(self):
 	# callbacks for extension points
 	def _onNvdaStartupComplete(self):
 		self._isNvdaStartupComplete = True
+		import brailleViewer
+		brailleViewer._brailleGui = self._brailleSpy
+		self.setBrailleCellCount(120)
+		brailleViewer.postBrailleViewerToolToggledAction.notify(created=True)
+
+	def _onNvdaBraille(self, rawText: str):
+		if not rawText:
+			return
+		with self._brailleLock:
+			self._nvdaBraille_requiresLock.append(rawText)
 
 	def _onNvdaSpeech(self, speechSequence=None):
 		if not speechSequence:
@@ -143,6 +193,27 @@ def _hasSpeechFinished(self, speechStartedIndex: Optional[int] = None):
 			finished = self.SPEECH_HAS_FINISHED_SECONDS < _timer() - self._lastSpeechTime_requiresLock
 			return started and finished
 
+	def setBrailleCellCount(self, brailleCellCount: int):
+		import brailleViewer
+		brailleViewer.DEFAULT_NUM_CELLS = brailleCellCount
+
+	def _getBrailleAtIndex(self, brailleIndex: int) -> str:
+		with self._brailleLock:
+			return self._nvdaBraille_requiresLock[brailleIndex]
+
+	def get_braille_at_index_until_now(self, brailleIndex: int) -> str:
+		""" All raw braille text from (and including) the index until now.
+		@param brailleIndex:
+		@return: The raw text, each update on a new line
+		"""
+		with self._brailleLock:
+			rangeOfInterest = self._nvdaBraille_requiresLock[brailleIndex:]
+			return "\n".join(rangeOfInterest)
+
+	def get_last_braille_index(self) -> int:
+		with self._brailleLock:
+			return len(self._nvdaBraille_requiresLock) - 1
+
 	def _devInfoToLog(self):
 		import api
 		obj = api.getNavigatorObject()
@@ -163,6 +234,14 @@ def dump_speech_to_log(self):
 			except Exception:
 				log.error("Unable to log speech")
 
+	def dump_braille_to_log(self):
+		log.debug("dump_braille_to_log.")
+		with self._brailleLock:
+			try:
+				log.debug(f"All braille:\n{repr(self._nvdaBraille_requiresLock)}")
+			except Exception:
+				log.error("Unable to log braille")
+
 	def _minTimeout(self, timeout: float) -> float:
 		"""Helper to get the minimum value, the timeout passed in, or self._maxKeywordDuration"""
 		return min(timeout, self._maxKeywordDuration)
@@ -237,6 +316,28 @@ def wait_for_speech_to_finish(
 			errorMessage="Speech did not finish before timeout"
 		)
 
+	def wait_for_braille_update(
+			self,
+			nextBrailleIndex: int,
+			maxWaitSeconds=5.0,
+	):
+		"""Wait until there is at least a single update.
+		@note there may be subsequent braille updates. This method does not confirm updates are finished.
+		"""
+		_blockUntilConditionMet(
+			getValue=lambda: self.get_last_braille_index() == nextBrailleIndex,
+			giveUpAfterSeconds=self._minTimeout(maxWaitSeconds),
+			errorMessage=None
+		)
+
+	def get_last_braille(self) -> str:
+		return self._getBrailleAtIndex(-1)
+
+	def get_next_braille_index(self) -> int:
+		""" @return: the next index that will be used.
+		"""
+		return self.get_last_braille_index() + 1
+
 	def emulateKeyPress(self, kbIdentifier: str, blockUntilProcessed=True):
 		"""
 		Emulates a key press using NVDA's input gesture framework.