Merge f8256a4 into 5bab7db

davidacm · web-flow · commit 18e0ee0daa90 · 2022-05-03T14:41:10.000+10:00
diff --git a/source/config/configSpec.py b/source/config/configSpec.py
@@ -51,6 +51,9 @@
 		sayCapForCapitals = boolean(default=false)
 		beepForCapitals = boolean(default=false)
 		useSpellingFunctionality = boolean(default=true)
+		delayedPhoneticDescriptions = boolean(default=false)
+		delayedPhoneticDescriptionsTimeoutMs = integer(default=1000,min=50,max=5000)
+
 
 # Audio settings
 [audio]
diff --git a/source/gui/settingsDialogs.py b/source/gui/settingsDialogs.py
@@ -1618,6 +1618,50 @@ def makeSettings(self, settingsSizer):
 			config.conf["speech"][self.driver.name]["useSpellingFunctionality"]
 		)
 
+		# Translators: This is the label for a checkbox in the
+		# voice settings panel.
+		delayedPhoneticDescriptionsText = _("&Delayed phonetic descriptions for characters on cursor movement")
+		self.delayedPhoneticDescriptionsCheckBox = settingsSizerHelper.addItem(
+			wx.CheckBox(self, label=delayedPhoneticDescriptionsText)
+		)
+		self.bindHelpEvent("delayedPhoneticDescriptions", self.delayedPhoneticDescriptionsCheckBox)
+		self.delayedPhoneticDescriptionsCheckBox.SetValue(
+			config.conf["speech"][self.driver.name]["delayedPhoneticDescriptions"]
+		)
+		self.delayedPhoneticDescriptionsCheckBox .Bind(
+			wx.EVT_CHECKBOX,
+			self.onToggleDelayDescriptions
+		)
+
+		minDelay = int(config.conf.getConfigValidation(
+			("speech", self.driver.name, "delayedPhoneticDescriptionsTimeoutMs")
+		).kwargs["min"])
+		maxDelay = int(config.conf.getConfigValidation(
+			("speech", self.driver.name, "delayedPhoneticDescriptionsTimeoutMs")
+		).kwargs["max"])
+
+		# Translators: This is a label for a setting in voice settings (an edit box to change
+		# Time for the delayed phonetic descriptions in ms;
+		delayedPhoneticDescriptionsTimeoutMsLabel = _("&Time for delayed phonetic descriptions (ms)")
+		self.delayedPhoneticDescriptionsTimeoutMsEdit = settingsSizerHelper.addLabeledControl(
+			delayedPhoneticDescriptionsTimeoutMsLabel,
+			nvdaControls.SelectOnFocusSpinCtrl,
+			min=minDelay,
+			max=maxDelay,
+			initial=config.conf["speech"][self.driver.name]["delayedPhoneticDescriptionsTimeoutMs"])
+		self.bindHelpEvent(
+			"delayedPhoneticDescriptionsTimeoutMs",
+			self.delayedPhoneticDescriptionsTimeoutMsEdit
+		)
+		if not config.conf["speech"][self.driver.name]["delayedPhoneticDescriptions"]:
+			self.delayedPhoneticDescriptionsTimeoutMsEdit.Hide()
+
+	def onToggleDelayDescriptions(self, evt):
+		if evt.IsChecked():
+			self.delayedPhoneticDescriptionsTimeoutMsEdit.Show()
+		else:
+			self.delayedPhoneticDescriptionsTimeoutMsEdit.Hide()
+
 	def onSave(self):
 		AutoSettingsMixin.onSave(self)
 
@@ -1636,6 +1680,10 @@ def onSave(self):
 		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.delayedPhoneticDescriptionsCheckBox.IsChecked()
+		config.conf["speech"][self.driver.name]["delayedPhoneticDescriptions"] = delayedDescriptions
+		delayedDescriptionsMs = self.delayedPhoneticDescriptionsTimeoutMsEdit.Value
+		config.conf["speech"][self.driver.name]["delayedPhoneticDescriptionsTimeoutMs"] = delayedDescriptionsMs
 
 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
@@ -59,12 +59,13 @@
 from enum import IntEnum
 from dataclasses import dataclass
 from copy import copy
-
+from core import callLater
 if typing.TYPE_CHECKING:
 	import NVDAObjects
 
 _speechState: Optional['SpeechState'] = None
 _curWordChars: List[str] = []
+phoneticDescriptionTimer = None
 
 
 class SpeechMode(IntEnum):
@@ -146,6 +147,7 @@ def cancelSpeech():
 		return
 	elif _speechState.speechMode == SpeechMode.beeps:
 		return
+	cancelPhoneticDescriptionTimer()
 	_manager.cancel()
 	_speechState.beenCanceled = True
 	_speechState.isPaused = False
@@ -810,6 +812,8 @@ def speak(  # noqa: C901
 
 	if not speechSequence:  # Pointless - nothing to speak
 		return
+	# cancel any delaied phonetic description if exists.
+	cancelPhoneticDescriptionTimer()
 	import speechViewer
 	if speechViewer.isActive:
 		speechViewer.appendSpeechSequence(speechSequence)
@@ -1136,6 +1140,7 @@ def speakTextInfo(
 		suppressBlanks: bool = False,
 		priority: Optional[Spri] = None
 ) -> bool:
+	global phoneticDescriptionTimer
 	speechGen = getTextInfoSpeech(
 		info,
 		useCache,
@@ -1150,6 +1155,16 @@ def speakTextInfo(
 	speechGen = GeneratorWithReturn(speechGen)
 	for seq in speechGen:
 		speak(seq, priority=priority)
+	if (
+		config.conf["speech"][getSynth().name]["delayedPhoneticDescriptions"]
+		and reason == OutputReason.CARET
+		and unit == textInfos.UNIT_CHARACTER
+	):
+		phoneticDescriptionTimer = callLater(
+			config.conf["speech"][getSynth().name]["delayedPhoneticDescriptionsTimeoutMs"],
+			speakDelayedDescription,
+			_FakeTextInfo(info)
+		)
 	return speechGen.returnValue
 
 
@@ -2595,3 +2610,46 @@ def clearTypedWordBuffer() -> None:
 	complete the word (such as a focus change or choosing to move the caret).
 	"""
 	_curWordChars.clear()
+
+
+def cancelPhoneticDescriptionTimer() -> None:
+	"""
+	this stops the timer used for delaied phonetic descriptions.
+	This should be called when a new sentence is send or the user stops the synth.
+	E.G, by pressing control key.
+	"""
+	global phoneticDescriptionTimer
+	if phoneticDescriptionTimer and phoneticDescriptionTimer.IsRunning():
+		phoneticDescriptionTimer.Stop()
+		phoneticDescriptionTimer = None
+
+
+class _FakeTextInfo():
+	"""
+	this class is used to preserve the information of the old object that contain the text.
+	It's useful to use with delayed descriptions.
+	"""
+
+	def __init__(self, origTextInfo: textInfos.TextInfo):
+		self.text = origTextInfo.text
+		self.fields = origTextInfo.getTextWithFields({})
+
+	def getTextWithFields(self, _=None):
+		return self.fields
+
+
+def speakDelayedDescription(info: _FakeTextInfo):
+	"""
+	this function is used to announce the delayed descriptions.
+	We can't call spellTextInfo directly because we need to check if the description is available first.
+	"""
+	if info.text.strip() == "":
+		return
+	curLang = getCurrentLanguage()
+	if config.conf['speech']['autoLanguageSwitching']:
+		for k in info.fields:
+			if isinstance(k, textInfos.FieldCommand) and k.command == "formatChange":
+				curLang = k.field.get('language', curLang)
+	_, description = getCharDescListFromText(info.text, locale=curLang)[0]
+	if description:
+		spellTextInfo(info, useCharacterDescriptions=True)
diff --git a/user_docs/en/userGuide.t2t b/user_docs/en/userGuide.t2t
@@ -1260,6 +1260,19 @@ 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 phonetic descriptions for characters on cursor movement ====[delayedPhoneticDescriptions]
+This setting is a checkbox that, when checked, tells NVDA to say the phonetic description when you move by characters, after an user defined pause. Default delay setting is 1000 ms (1 sec).
+
+The phonetic description delay will be cancelled if another text is spoken during that time or if you press control key.
+
+For example, if you review this line by characters, when you read the letter "b", NVDA will say "Bravo" after the defined pause.
+
+This can be useful if your current speech synthesizer pronounces some characters in a similar way. Also, can be useful if you have some degree of deafness. In this case, could be a good idea to set NVDA to use small delays.
+
+==== Time for delayed phonetic descriptions (ms) ====[delayedPhoneticDescriptionsTimeoutMs]
+This edit field allows you to type the pause time that NVDA will take to say the phonetic description when you move by characters.
+This setting is specified in milliseconds (ms).
+
 +++ 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.
