Report spelling errors with a sound while reading

SaschaCowley · Sep 5, 2025 · Apr 18, 2025 · Apr 22, 2025 · Apr 22, 2025 · Apr 23, 2025
commit 747242646fcf8fe4931bc9b2305f68b587b8e1df
@@ -180,6 +180,32 @@ def _displayStringLabels(self):
 		}
 
 
+@unique
+class ReportSpellingErrors(DisplayStringIntEnum):
+	"""Enumeration containing the possible config values to report spelling errors while reading.
+
+	Use ReportSpellingErrors.MEMBER.value to compare with the config;
+	use ReportSpellingErrors.MEMBER.displayString in the UI for a translatable description of this member.
+	"""
+
+	OFF = 0
+	SPEECH = 1
+	SOUND = 2
+
+	@property
+	def _displayStringLabels(self):
+		return {
+			# Translators: A choice in a combo box in the document formatting dialog to not report spelling errors.
+			ReportSpellingErrors.OFF: pgettext("line indentation setting", "Off"),
+			# Translators: A choice in a combo box in the document formatting dialog to report spelling errors
+			# with Speech.
+			ReportSpellingErrors.SPEECH: pgettext("line indentation setting", "Speech"),
+			# Translators: A choice in a combo box in the document formatting dialog to report spelling errors
+			# with a sound.
+			ReportSpellingErrors.SOUND: pgettext("line indentation setting", "Sound"),
+		}
+
+
 @unique
 class ReportTableHeaders(DisplayStringIntEnum):
 	"""Enumeration containing the possible config values to report table headers.

@@ -13,7 +13,7 @@
 #: provide an upgrade step (@see profileUpgradeSteps.py). An upgrade step does not need to be added when
 #: just adding a new element to (or removing from) the schema, only when old versions of the config
 #: (conforming to old schema versions) will not work correctly with the new schema.
-latestSchemaVersion = 17
+latestSchemaVersion = 18
 
 #: The configuration specification string
 #: @type: String
@@ -228,7 +228,8 @@
 	reportAlignment = boolean(default=false)
 	reportLineSpacing = boolean(default=false)
 	reportStyle = boolean(default=false)
-	reportSpellingErrors = boolean(default=true)
+	# 0: Off, 1: Speech, 2: Sound
+	reportSpellingErrors = integer(0, 2, default=1)
 	reportPage = boolean(default=true)
 	reportLineNumber = boolean(default=False)
 	# 0: Off, 1: Speech, 2: Tones, 3: Both Speech and Tones

@@ -24,6 +24,7 @@
 	OutputMode,
 	ReportCellBorders,
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ShowMessages,
 	TetherTo,
@@ -577,3 +578,22 @@ def upgradeConfigFrom_16_to_17(profile: ConfigObj) -> None:
 					log.debug(
 						f"Renamed config['remote']['{sectionKey}']['{oldItemKey}'] to config['remote']['{sectionKey}']['{newItemKey}'].",
 					)
+
+def upgradeConfigFrom_17_to_18(profile: ConfigObj):
+	"""Convert report spelling errors configurations from boolean to integer values."""
+
+	section = "documentFormatting"
+	key = "reportSpellingErrors"
+	try:
+		oldValue: bool = profile[section].as_bool(key)
+	except KeyError:
+		log.debug(f"'{key}' not present in config, no action taken.")
+		return
+	except ValueError:
+		log.error(f"'{key}' is not a boolean, got {profile[section][key]!r}. Deleting.")
+		del profile[section][key]
+		return
+	else:
+		newValue = ReportSpellingErrors.SPEECH.value if oldValue else ReportSpellingErrors.OFF.value
+		profile[section][key] = newValue
+		log.debug(f"Converted '{key}' from {oldValue!r} to {newValue} ({ReportSpellingErrors(newValue).name}).")
@@ -45,6 +45,7 @@
 	BrailleMode,
 	OutputMode,
 	TypingEcho,
+	ReportSpellingErrors,
 )
 from config.featureFlag import FeatureFlag
 from config.featureFlagEnums import BoolFlag
@@ -787,19 +788,18 @@ def script_toggleReportStyle(self, gesture):
 
 	@script(
 		# Translators: Input help mode message for toggle report spelling errors command.
-		description=_("Toggles on and off the reporting of spelling errors"),
+		description=_("Cycles through the possible choices to report spelling errors"),
 		category=SCRCAT_DOCUMENTFORMATTING,
 	)
 	def script_toggleReportSpellingErrors(self, gesture):
-		if config.conf["documentFormatting"]["reportSpellingErrors"]:
-			# Translators: The message announced when toggling the report spelling errors document formatting setting.
-			state = _("report spelling errors off")
-			config.conf["documentFormatting"]["reportSpellingErrors"] = False
-		else:
-			# Translators: The message announced when toggling the report spelling errors document formatting setting.
-			state = _("report spelling errors on")
-			config.conf["documentFormatting"]["reportSpellingErrors"] = True
-		ui.message(state)
+		toggleIntegerValue(
+			configSection="documentFormatting",
+			configKey="reportSpellingErrors",
+			enumClass=ReportSpellingErrors,
+			# Translators: Reported when the user cycles through the choices to report spelling errors.
+			# {mode} will be replaced with the mode; e.g. Off, Speech, Sound.
+			messageTemplate=_("Report spelling errors {mode}"),
+		)
 
 	@script(
 		# Translators: Input help mode message for toggle report pages command.

@@ -39,6 +39,7 @@
 	TetherTo,
 	ParagraphStartMarker,
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ReportCellBorders,
 	OutputMode,
@@ -2748,11 +2749,19 @@ def makeSettings(self, settingsSizer):
 		self.revisionsCheckBox = docInfoGroup.addItem(wx.CheckBox(docInfoBox, label=revisionsText))
 		self.revisionsCheckBox.SetValue(config.conf["documentFormatting"]["reportRevisions"])
 
-		# Translators: This is the label for a checkbox in the
-		# document formatting settings panel.
-		spellingErrorText = _("Spelling e&rrors")
-		self.spellingErrorsCheckBox = docInfoGroup.addItem(wx.CheckBox(docInfoBox, label=spellingErrorText))
-		self.spellingErrorsCheckBox.SetValue(config.conf["documentFormatting"]["reportSpellingErrors"])
+		self.spellingErrorsCombo = docInfoGroup.addLabeledControl(
+			# Translators: This is the label for a checkbox in the
+			# document formatting settings panel.
+			_("Spelling e&rrors"),
+			wx.Choice,
+			choices=[i.displayString for i in ReportSpellingErrors],
+		)
+		self.bindHelpEvent(
+			"DocumentFormattingSettingsSpellingErrors",
+			self.spellingErrorsCombo,
+		)
+		reportSpellingErrors = config.conf["documentFormatting"]["reportSpellingErrors"]
+		self.spellingErrorsCombo.SetSelection(reportSpellingErrors)
 
 		# Translators: This is the label for a group of document formatting options in the
 		# document formatting settings panel
@@ -2975,7 +2984,7 @@ def onSave(self):
 		config.conf["documentFormatting"]["reportHighlight"] = self.highlightCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportAlignment"] = self.alignmentCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportStyle"] = self.styleCheckBox.IsChecked()
-		config.conf["documentFormatting"]["reportSpellingErrors"] = self.spellingErrorsCheckBox.IsChecked()
+		config.conf["documentFormatting"]["reportSpellingErrors"] = self.spellingErrorsCombo.GetSelection()
 		config.conf["documentFormatting"]["reportPage"] = self.pageCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportLineNumber"] = self.lineNumberCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportLineIndentation"] = self.lineIndentationCombo.GetSelection()

@@ -39,6 +39,7 @@
 	EndUtteranceCommand,
 	SuppressUnicodeNormalizationCommand,
 	CharacterModeCommand,
+	WaveFileCommand,
 )
 from .shortcutKeys import getKeyboardShortcutsSpeech
 
@@ -65,6 +66,7 @@
 import config
 from config.configFlags import (
 	ReportLineIndentation,
+	ReportSpellingErrors,
 	ReportTableHeaders,
 	ReportCellBorders,
 	OutputMode,
@@ -1491,7 +1493,7 @@ def speakTextInfo(
 def getTextInfoSpeech(  # noqa: C901
 	info: textInfos.TextInfo,
 	useCache: Union[bool, SpeakTextInfoState] = True,
-	formatConfig: Dict[str, bool] = None,
+	formatConfig: Dict[str, bool | int] = None,
 	unit: Optional[str] = None,
 	reason: OutputReason = OutputReason.QUERY,
 	_prefixSpeechCommand: Optional[SpeechCommand] = None,
@@ -1516,7 +1518,7 @@ def getTextInfoSpeech(  # noqa: C901
 	)
 	# For performance reasons, when navigating by paragraph or table cell, spelling errors will not be announced.
 	if unit in (textInfos.UNIT_PARAGRAPH, textInfos.UNIT_CELL) and reason == OutputReason.CARET:
-		formatConfig["reportSpellingErrors"] = False
+		formatConfig["reportSpellingErrors"] = ReportSpellingErrors.OFF.value
 
 	# Fetch the last controlFieldStack, or make a blank one
 	controlFieldStackCache = speakTextInfoState.controlFieldStackCache if speakTextInfoState else []
@@ -1891,7 +1893,9 @@ def _getTextInfoSpeech_considerSpelling(
 	speechSequence: SpeechSequence,
 	language: str,
 ) -> Generator[SpeechSequence, None, None]:
-	if onlyInitialFields or any(isinstance(x, str) for x in speechSequence):
+	# zzz Replacing if onlyInitialFields or any(isinstance(x, str) for x in speechSequence):
+	if onlyInitialFields or speechSequence:
+		# zzz replaced if onlyInitialFields or speechSequence:
 		yield speechSequence
 	if not onlyInitialFields:
 		spellingSequence = list(
@@ -2991,13 +2995,16 @@ def getFormatFieldSpeech(  # noqa: C901
 				# Translators: Reported when text no longer contains a bookmark
 				text = _("out of bookmark")
 				textList.append(text)
-	if formatConfig["reportSpellingErrors"]:
+	if formatConfig["reportSpellingErrors"] != ReportSpellingErrors.OFF.value:
 		invalidSpelling = attrs.get("invalid-spelling")
 		oldInvalidSpelling = attrsCache.get("invalid-spelling") if attrsCache is not None else None
 		if (invalidSpelling or oldInvalidSpelling is not None) and invalidSpelling != oldInvalidSpelling:
 			if invalidSpelling:
-				# Translators: Reported when text contains a spelling error.
-				text = _("spelling error")
+				if formatConfig["reportSpellingErrors"] == ReportSpellingErrors.SPEECH.value:
+					# Translators: Reported when text contains a spelling error.
+					text = _("spelling error")
+				else:
+					text = WaveFileCommand(r"waves\textError.wav")
 			elif extraDetail:
 				# Translators: Reported when moving out of text containing a spelling error.
 				text = _("out of spelling error")

@@ -2609,7 +2609,7 @@ When enabled, NVDA will announce all non-character keys you type on the keyboard
 ##### Play sound for spelling errors while typing {#KeyboardSettingsAlertForSpellingErrors}
 
 When enabled, a short buzzer sound will be played when a word you type contains a spelling error.
-This option is only available if reporting of spelling errors is enabled in NVDA's [Document Formatting Settings](#DocumentFormattingSettings), found in the NVDA Settings dialog.
+This option is only available if [reporting of spelling errors](#DocumentFormattingSettingsSpellingErrors) is enabled in NVDA's Document Formatting Settings.
 
 ##### Handle keys from other applications {#KeyboardSettingsHandleKeys}
 
@@ -2951,7 +2951,7 @@ You can configure reporting of:
   * Comments
   * Bookmarks
   * Editor revisions
-  * Spelling errors
+  * Spelling errors [(Off, Speech, Sound)](#DocumentFormattingSettingsSpellingErrors)
 * Pages and spacing
   * Page numbers
   * Line numbers
@@ -3000,6 +3000,19 @@ By default, NVDA will detect the formatting at the position of the System caret
 
 Enable this option while proof reading documents in applications such as WordPad, where formatting is important.
 
+##### Spelling errors reporting {#DocumentFormattingSettingsSpellingErrors}
+
+This option allows you to configure how spelling errors are reported while reading text.
+The "Report spelling errors" combo box has three options.
+
+* Off: NVDA will not report any spelling error
+* Speech: NVDA will say "spelling error" when a spelling error is encountered while reading text
+* Sound: NVDA will play a short buzzer sound when a spelling error is encountered while reading text
+
+When navigating word by word or character by character, "out of spelling error" is also reported if Speech or Sound option is selected.
+
+Due to performance limitations, spelling errors are not reported when navigating by paragraph or by cell in tables, no matter the choice selected in the combo-box.
+
 ##### Line indentation reporting {#DocumentFormattingSettingsLineIndentation}
 
 This option allows you to configure how indentation at the beginning of lines is reported.