Merge b133520 into 2077431

davidacm · web-flow · commit 2303847532ea · 2022-07-18T14:48:52.000+10:00
diff --git a/source/config/configSpec.py b/source/config/configSpec.py
@@ -1,6 +1,6 @@
 # -*- coding: UTF-8 -*-
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2006-2021 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
+# Copyright (C) 2006-2022 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
 # Joseph Lee, Dawid Pieper, mltony
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
@@ -45,6 +45,7 @@
 	outputDevice = string(default=default)
 	autoLanguageSwitching = boolean(default=true)
 	autoDialectSwitching = boolean(default=false)
+	delayedCharacterDescriptions = boolean(default=false)
 
 	[[__many__]]
 		capPitchChange = integer(default=30,min=-100,max=100)
diff --git a/source/gui/settingsDialogs.py b/source/gui/settingsDialogs.py
@@ -1,6 +1,6 @@
 # -*- coding: UTF-8 -*-
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2006-2021 NV Access Limited, Peter Vágner, Aleksey Sadovoy,
+# Copyright (C) 2006-2022 NV Access Limited, Peter Vágner, Aleksey Sadovoy,
 # Rui Batista, Joseph Lee, Heiko Folkerts, Zahari Yurukov, Leonard de Ruijter,
 # Derek Riemer, Babbage B.V., Davy Kager, Ethan Holliger, Bill Dengler, Thomas Stivers,
 # Julien Cochuyt, Peter Vágner, Cyrille Bougot, Mesar Hameed, Łukasz Golonka, Aaron Cannon,
@@ -1560,6 +1560,8 @@ def makeSettings(self, settingsSizer):
 		)
 		self.includeCLDRCheckbox.SetValue(config.conf["speech"]["includeCLDR"])
 
+		self._appendDelayedCharacterDescriptions(settingsSizerHelper)
+
 		minPitchChange = int(config.conf.getConfigValidation(
 			("speech", self.driver.name, "capPitchChange")
 		).kwargs["min"])
@@ -1618,6 +1620,17 @@ def makeSettings(self, settingsSizer):
 			config.conf["speech"][self.driver.name]["useSpellingFunctionality"]
 		)
 
+	def _appendDelayedCharacterDescriptions(self, settingsSizerHelper: guiHelper.BoxSizerHelper) -> None:
+		# Translators: This is the label for a checkbox in the voice settings panel.
+		delayedCharacterDescriptionsText = _("&Delayed descriptions for characters on cursor movement")
+		self.delayedCharacterDescriptionsCheckBox = settingsSizerHelper.addItem(
+			wx.CheckBox(self, label=delayedCharacterDescriptionsText)
+		)
+		self.bindHelpEvent("delayedCharacterDescriptions", self.delayedCharacterDescriptionsCheckBox)
+		self.delayedCharacterDescriptionsCheckBox.SetValue(
+			config.conf["speech"]["delayedCharacterDescriptions"]
+		)
+
 	def onSave(self):
 		AutoSettingsMixin.onSave(self)
 
@@ -1632,10 +1645,12 @@ def onSave(self):
 		if currentIncludeCLDR is not newIncludeCldr:
 			# Either included or excluded CLDR data, so clear the cache.
 			characterProcessing.clearSpeechSymbols()
+		config.conf["speech"]["delayedCharacterDescriptions"] = delayedDescriptions
 		config.conf["speech"][self.driver.name]["capPitchChange"]=self.capPitchChangeEdit.Value
 		config.conf["speech"][self.driver.name]["sayCapForCapitals"]=self.sayCapForCapsCheckBox.IsChecked()
 		config.conf["speech"][self.driver.name]["beepForCapitals"]=self.beepForCapsCheckBox.IsChecked()
 		config.conf["speech"][self.driver.name]["useSpellingFunctionality"]=self.useSpellingFunctionalityCheckBox.IsChecked()
+		delayedDescriptions = self.delayedCharacterDescriptionsCheckBox.IsChecked()
 
 class KeyboardSettingsPanel(SettingsPanel):
 	# Translators: This is the label for the keyboard settings panel.
diff --git a/source/speech/speech.py b/source/speech/speech.py
@@ -2,7 +2,7 @@
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 # Copyright (C) 2006-2022 NV Access Limited, Peter Vágner, Aleksey Sadovoy, Babbage B.V., Bill Dengler,
-# Julien Cochuyt
+# Julien Cochuyt, Derek Riemer
 
 """High-level functions to speak information.
 """ 
@@ -26,6 +26,7 @@
 from . import manager
 from .commands import (
 	# Commands that are used in this file.
+	BreakCommand,
 	SpeechCommand,
 	PitchCommand,
 	LangChangeCommand,
@@ -338,6 +339,48 @@ def _getSpellingSpeechWithoutCharMode(
 		yield EndUtteranceCommand()
 
 
+def getSingleCharDescriptionDelayMS() -> int:
+	"""
+	@returns: 1 second, a default delay.
+	In the future, this should fetch its value from a user defined NVDA idle time.
+	Blocked by: https://github.com/nvaccess/nvda/issues/13915
+	"""
+	return 1000
+
+
+def getSingleCharDescription(
+		text: str,
+		locale: Optional[str] = None,
+) -> Generator[SequenceItemT, None, None]:
+	# This should only be used for single chars.
+	if not len(text) == 1:
+		return
+	synth = getSynth()
+	synthConfig = config.conf["speech"][synth.name]
+	if synth.isSupported("pitch"):
+		capPitchChange = synthConfig["capPitchChange"]
+	else:
+		capPitchChange = 0
+	defaultLanguage = getCurrentLanguage()
+	if not locale or (
+		not config.conf['speech']['autoDialectSwitching']
+		and locale.split('_')[0] == defaultLanguage.split('_')[0]
+	):
+		locale = defaultLanguage
+	# If the description for the locale is unknown, we yield nothing.
+	char, description = getCharDescListFromText(text, locale=locale)[0]
+	uppercase = char.isupper()
+	if description is None:
+		return
+	yield BreakCommand(getSingleCharDescriptionDelayMS())
+	yield from _getSpellingCharAddCapNotification(
+		description[0],
+		sayCapForCapitals=uppercase and synthConfig["sayCapForCapitals"],
+		capPitchChange=(capPitchChange if uppercase else 0),
+		beepForCapitals=uppercase and synthConfig["beepForCapitals"],
+	)
+
+
 def getSpellingSpeech(
 		text: str,
 		locale: Optional[str] = None,
@@ -1169,7 +1212,6 @@ def getTextInfoSpeech(  # noqa: C901
 		onlyInitialFields: bool = False,
 		suppressBlanks: bool = False
 ) -> Generator[SpeechSequence, None, bool]:
-	onlyCache = reason == OutputReason.ONLYCACHE
 	if isinstance(useCache,SpeakTextInfoState):
 		speakTextInfoState=useCache
 	elif useCache:
@@ -1209,8 +1251,8 @@ def getTextInfoSpeech(  # noqa: C901
 		except KeyError:
 			pass
 
-	#Make a new controlFieldStack and formatField from the textInfo's initialFields
-	newControlFieldStack=[]
+	# Make a new controlFieldStack and formatField from the textInfo's initialFields
+	newControlFieldStack: List[textInfos.ControlField] = []
 	newFormatField=textInfos.FormatField()
 	initialFields=[]
 	for field in textWithFields:
@@ -1340,32 +1382,29 @@ def getTextInfoSpeech(  # noqa: C901
 		language=newFormatField.get('language')
 		speechSequence.append(LangChangeCommand(language))
 		lastLanguage=language
-
-	def isControlEndFieldCommand(x):
-		return isinstance(x, textInfos.FieldCommand) and x.command == "controlEnd"
-
 	isWordOrCharUnit = unit in (textInfos.UNIT_CHARACTER, textInfos.UNIT_WORD)
 	if onlyInitialFields or (
 		isWordOrCharUnit
 		and len(textWithFields) > 0
 		and len(textWithFields[0].strip() if not textWithFields[0].isspace() else textWithFields[0]) == 1
-		and all(isControlEndFieldCommand(x) for x in itertools.islice(textWithFields, 1, None))
+		and all(_isControlEndFieldCommand(x) for x in itertools.islice(textWithFields, 1, None))
 	):
-		if not onlyCache:
-			if onlyInitialFields or any(isinstance(x, str) for x in speechSequence):
-				yield speechSequence
-			if not onlyInitialFields:
-				spellingSequence = list(getSpellingSpeech(
-					textWithFields[0],
-					locale=language
-				))
-				logBadSequenceTypes(spellingSequence)
-				yield spellingSequence
+		if reason != OutputReason.ONLYCACHE:
+			yield from list(_getTextInfoSpeech_considerSpelling(
+				unit,
+				onlyInitialFields,
+				textWithFields,
+				reason,
+				speechSequence,
+				language,
+			))
 		if useCache:
-			speakTextInfoState.controlFieldStackCache=newControlFieldStack
-			speakTextInfoState.formatFieldAttributesCache=formatFieldAttributesCache
-			if not isinstance(useCache,SpeakTextInfoState):
-				speakTextInfoState.updateObj()
+			_getTextInfoSpeech_updateCache(
+				useCache,
+				speakTextInfoState,
+				newControlFieldStack,
+				formatFieldAttributesCache,
+			)
 		return False
 
 	# Similar to before, but If the most inner clickable is exited, then we allow announcing clickable for the next lot of clickable fields entered.
@@ -1511,12 +1550,14 @@ def isControlEndFieldCommand(x):
 		# Translators: This is spoken when the line is considered blank.
 		speechSequence.append(_("blank"))
 
-	#Cache a copy of the new controlFieldStack for future use
+	# Cache a copy of the new controlFieldStack for future use
 	if useCache:
-		speakTextInfoState.controlFieldStackCache=list(newControlFieldStack)
-		speakTextInfoState.formatFieldAttributesCache=formatFieldAttributesCache
-		if not isinstance(useCache,SpeakTextInfoState):
-			speakTextInfoState.updateObj()
+		_getTextInfoSpeech_updateCache(
+			useCache,
+			speakTextInfoState,
+			newControlFieldStack,
+			formatFieldAttributesCache,
+		)
 
 	if reason == OutputReason.ONLYCACHE or not speechSequence:
 		return False
@@ -1525,6 +1566,51 @@ def isControlEndFieldCommand(x):
 	return True
 
 
+def _isControlEndFieldCommand(command: Union[str, textInfos.FieldCommand]):
+	return isinstance(command, textInfos.FieldCommand) and command.command == "controlEnd"
+
+
+def _getTextInfoSpeech_considerSpelling(
+		unit: Optional[textInfos.TextInfo],
+		onlyInitialFields: bool,
+		textWithFields: textInfos.TextInfo.TextWithFieldsT,
+		reason: OutputReason,
+		speechSequence: SpeechSequence,
+		language: str,
+) -> Generator[SpeechSequence, None, None]:
+	if onlyInitialFields or any(isinstance(x, str) for x in speechSequence):
+		yield speechSequence
+	if not onlyInitialFields:
+		spellingSequence = list(getSpellingSpeech(
+			textWithFields[0],
+			locale=language
+		))
+		logBadSequenceTypes(spellingSequence)
+		yield spellingSequence
+		if (
+			reason == OutputReason.CARET
+			and unit == textInfos.UNIT_CHARACTER
+			and config.conf["speech"]["delayedCharacterDescriptions"]
+		):
+			descriptionSequence = list(getSingleCharDescription(
+				textWithFields[0],
+				locale=language,
+			))
+			yield descriptionSequence
+
+
+def _getTextInfoSpeech_updateCache(
+		useCache: Union[bool, SpeakTextInfoState],
+		speakTextInfoState: SpeakTextInfoState,
+		newControlFieldStack: List[textInfos.ControlField],
+		formatFieldAttributesCache: textInfos.Field,
+):
+	speakTextInfoState.controlFieldStackCache = newControlFieldStack
+	speakTextInfoState.formatFieldAttributesCache = formatFieldAttributesCache
+	if not isinstance(useCache, SpeakTextInfoState):
+		speakTextInfoState.updateObj()
+
+
 # C901 'getPropertiesSpeech' is too complex
 # Note: when working on getPropertiesSpeech, look for opportunities to simplify
 # and move logic out into smaller helper functions.
diff --git a/source/synthDriverHandler.py b/source/synthDriverHandler.py
@@ -251,6 +251,10 @@ def _get_availableVoices(self) -> OrderedDict[str, VoiceInfo]:
 			self._availableVoices = self._getAvailableVoices()
 		return self._availableVoices
 
+	#: Typing information for auto-property: _get_rate
+	rate: int
+	"""Between 0-100"""
+
 	def _get_rate(self):
 		return 0
 
diff --git a/tests/system/robot/symbolPronunciationTests.py b/tests/system/robot/symbolPronunciationTests.py
@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2021 NV Access Limited
+# Copyright (C) 2021-2022 NV Access Limited
 # This file may be used under the terms of the GNU General Public License, version 2 or later.
 # For more details see: https://www.gnu.org/licenses/gpl-2.0.html
 
@@ -276,6 +276,55 @@ def test_moveByChar():
 	)
 
 
+_CHARACTER_DESCRIPTIONS = {
+	# english character descriptions.
+	'a': 'Alfa',
+	'b': 'Bravo',
+	'c': 'Charlie',
+}
+
+
+def _getDelayedDescriptionsTestSample() -> str:
+	return "".join(_CHARACTER_DESCRIPTIONS.keys())
+
+
+def _testDelayedDescription(expectDescription: bool = True) -> None:
+	"""
+	Perform delayed character descriptions tests with with the specified parameters:
+	@param expectDescription: whether or not a delayed description should be announced
+	"""
+	spoken = _NvdaLib.getSpeechAfterKey(Move.CARET_CHAR.value).split("\n")
+	if not spoken:
+		raise AssertionError(f"Nothing spoken after character press")
+	if spoken[0] not in _CHARACTER_DESCRIPTIONS:
+		raise AssertionError(
+			f"First piece of speech not an expected character; got: '{spoken[0]}'"
+		)
+	if expectDescription:
+		if len(spoken) != 2:
+			raise AssertionError(
+				f"Expected character with description; got: '{spoken}'"
+			)
+		_asserts.strings_match(spoken[1], _CHARACTER_DESCRIPTIONS[spoken[0]])
+	else:
+		if len(spoken) != 1:
+			raise AssertionError(
+				f"Expected single character; got: '{spoken}'"
+			)
+
+
+def test_delayedDescriptions():
+	_notepad.prepareNotepad(_getDelayedDescriptionsTestSample())
+	# Ensure this feature is disabled by default.
+	_testDelayedDescription(expectDescription=False)
+
+	# Activate delayed descriptions feature to do the next test.
+	spy = _NvdaLib.getSpyLib()
+	spy.set_configValue(['speech', 'delayedCharacterDescriptions'], True)
+
+	_testDelayedDescription()
+
+
 def test_selByWord():
 	""" Select word by word with symbol level 'none' and symbol level 'all'.
 	Note that the number of spaces between speech content and 'selected' varies, possibly due to the number
diff --git a/tests/system/robot/symbolPronunciationTests.robot b/tests/system/robot/symbolPronunciationTests.robot
@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2021 NV Access Limited
+# Copyright (C) 2021-2022 NV Access Limited
 # This file may be used under the terms of the GNU General Public License, version 2 or later.
 # For more details see: https://www.gnu.org/licenses/gpl-2.0.html
 *** Settings ***
@@ -42,6 +42,10 @@ moveByCharacter
 	[Documentation]	Ensure symbols announced as expected when navigating by character (numpad 3).
 	test_moveByChar
 
+delayedCharacterDescriptions
+	[Documentation]	Ensure delayed character descriptions are announced as expected when navigating by character.
+	test_delayedDescriptions
+
 selectionByWord
 	[Documentation]	Ensure symbols announced as expected when selecting by word (shift+control+right arrow).
 	[Tags]	selection
diff --git a/user_docs/en/userGuide.t2t b/user_docs/en/userGuide.t2t
@@ -1265,6 +1265,18 @@ This option should generally be enabled.
 However, some Microsoft Speech API synthesizers do not implement this correctly and behave strangely when it is enabled.
 If you are having problems with the pronunciation of individual characters, try disabling this option.
 
+==== Delayed descriptions for characters on cursor movement ====[delayedCharacterDescriptions]
+: Default
+  Disabled
+:
+
+When this setting is checked, NVDA will say the character description when you move by characters.
+
+For example, while reviewing a line by characters, when the letter "b" is read NVDA will say "Bravo" after a 1 second delay.
+This can be useful if it is hard to distinguish between pronunciation of symbols, or for hearing impaired users.
+
+The delayed character description will be cancelled if other text is spoken during that time, or if you press the ``control`` key.
+
 +++ Select Synthesizer (NVDA+control+s) +++[SelectSynthesizer]
 The Synthesizer dialog, which can be opened by activating the Change... button in the speech category of the NVDA settings dialog, allows you to select which Synthesizer NVDA should use to speak with.
 Once you have selected your synthesizer of choice, you can press Ok and NVDA will load the selected Synthesizer.
