Fix SAPI 4 driver

source/autoSettingsUtils/driverSetting.py

@@ -49,6 +49,7 @@ def __init__(
 	):
 		"""
 		@param id: internal identifier of the setting
+			If this starts with a `_`, it will not be shown in the settings GUI.
 		@param displayNameWithAccelerator: the localized string shown in voice or braille settings dialog
 		@param availableInSettingsRing: Will this option be available in a settings ring?
 		@param defaultVal: Specifies the default value for a driver setting.

source/config/configSpec.py

@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2006-2025 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
+# Copyright (C) 2006-2024 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
 # Joseph Lee, Dawid Pieper, mltony, Bram Duvigneau, Cyrille Bougot, Rob Meredith,
 # Burman's Computer and Education Ltd., Leonard de Ruijter, Łukasz Golonka
 # This file is covered by the GNU General Public License.
@@ -45,7 +45,6 @@
 	autoDialectSwitching = boolean(default=false)
 	delayedCharacterDescriptions = boolean(default=false)
 	excludedSpeechModes = int_list(default=list())
-	_hasSapi4WarningBeenShown = boolean(default=False)
 
 	[[__many__]]
 		capPitchChange = integer(default=30,min=-100,max=100)

source/gui/settingsDialogs.py

@@ -1552,6 +1552,9 @@ def updateDriverSettings(self, changedSetting=None):
 				continue
 			if setting.id in self.sizerDict:  # update a value
 				self._updateValueForControl(setting, settingsStorage)
+			elif setting.id.startswith("_"):
+				# Skip private settings.
+				continue
 			else:  # create a new control
 				self._createNewControl(setting, settingsStorage)
 		# Update graphical layout of the dialog

source/speech/speech.py

@@ -1,7 +1,7 @@
 # A part of NonVisual Desktop Access (NVDA)
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-# Copyright (C) 2006-2025 NV Access Limited, Peter Vágner, Aleksey Sadovoy, Babbage B.V., Bill Dengler,
+# Copyright (C) 2006-2024 NV Access Limited, Peter Vágner, Aleksey Sadovoy, Babbage B.V., Bill Dengler,
 # Julien Cochuyt, Derek Riemer, Cyrille Bougot, Leonard de Ruijter, Łukasz Golonka
 
 """High-level functions to speak information."""
@@ -11,18 +11,14 @@
 import weakref
 import unicodedata
 import time
-
 import colors
 import api
 from annotation import _AnnotationRolesT
 import controlTypes
 from controlTypes import OutputReason, TextPosition
 from controlTypes.state import State
-import globalVars
-from gui.message import MessageDialog
-import queueHandler
 import tones
-from synthDriverHandler import SynthDriver, getSynth, synthChanged
+from synthDriverHandler import getSynth
 import re
 import textInfos
 import speechDictHandler
@@ -3063,41 +3059,3 @@ def clearTypedWordBuffer() -> None:
 	complete the word (such as a focus change or choosing to move the caret).
 	"""
 	_curWordChars.clear()
-
-
-def _sapi4DeprecationWarning(synth: SynthDriver, audioOutputDevice: str, isFallback: bool):
-	"""A synthChanged event handler to alert the user about the deprecation of SAPI4."""
-
-	def setShown():
-		config.conf["speech"]["_hasSapi4WarningBeenShown"] = True
-
-	def impl():
-		MessageDialog(
-			parent=None,
-			message=_(
-				# Translators: Message warning users that SAPI4 is deprecated.
-				"Microsoft Speech API version 4 is obsolete. "
-				"Using this speech synthesizer may pose a security risk. "
-				"This synthesizer driver will be removed in NVDA 2026.1. "
-				"You are strongly encouraged to choose a more modern speech synthesizer.",
-			),
-			# Translators: Title of a message dialog.
-			title=_("Warning"),
-			buttons=None,
-		).addOkButton(
-			callback=setShown,
-		).Show()
-
-	if (
-		(not isFallback)
-		and (synth.name == "sapi4")
-		and (not config.conf["speech"]["_hasSapi4WarningBeenShown"])
-	):
-		# We need to queue the dialog to appear, as wx may not have been initialised the first time this is called.
-		queueHandler.queueFunction(queueHandler.eventQueue, impl)
-
-
-if not globalVars.appArgs.minimal:
-	# Don't warn users about SAPI4 deprecation in minimal mode.
-	# This stops the dialog appearing on secure screens or in the launcher.
-	synthChanged.register(_sapi4DeprecationWarning)

source/synthDrivers/_sapi4.py

@@ -237,7 +237,7 @@ class DriverMessage(IntEnum):
 	Defined in mmddk.h
 	"""
 
-	QUERY__INSTANCE_ID = 2065
+	QUERY_INSTANCE_ID = 2065
 	"""DRV_QUERYFUNCTIONINSTANCEID """
 
 	QUERY_INSTANCE_ID_SIZE = 2066

source/synthDrivers/sapi4.py

@@ -11,7 +11,12 @@
 from ctypes import byref, c_ulong, POINTER, c_wchar, create_string_buffer, sizeof, windll
 from ctypes.wintypes import DWORD, HANDLE, WORD
 from typing import Optional
-from synthDriverHandler import SynthDriver, VoiceInfo, synthIndexReached, synthDoneSpeaking
+from autoSettingsUtils.driverSetting import BooleanDriverSetting
+import globalVars
+import gui.contextHelp
+import gui.message
+import queueHandler
+from synthDriverHandler import SynthDriver, VoiceInfo, synthIndexReached, synthDoneSpeaking, synthChanged
 from logHandler import log
 import warnings
 from ._sapi4 import (
@@ -128,7 +133,10 @@ def ITTSNotifySinkW_AudioStop(self, this, qTimeStamp: int):
 class SynthDriver(SynthDriver):
 	name = "sapi4"
 	description = "Microsoft Speech API version 4"
-	supportedSettings = [SynthDriver.VoiceSetting()]
+	supportedSettings = [
+		SynthDriver.VoiceSetting(),
+		BooleanDriverSetting("_hasWarningBeenShown", ""),
+	]
 	supportedCommands = {
 		IndexCommand,
 		CharacterModeCommand,
@@ -458,7 +466,7 @@ def _mmDeviceEndpointIdToWaveOutId(targetEndpointId: str) -> int:
 			# Get the device's endpoint ID string.
 			mmr = waveOutMessage(
 				HANDLE(devID),
-				DriverMessage.QUERY__INSTANCE_ID,
+				DriverMessage.QUERY_INSTANCE_ID,
 				byref(currEndpointId),
 				currEndpointIdByteCount,
 			)
@@ -473,3 +481,43 @@ def _mmDeviceEndpointIdToWaveOutId(targetEndpointId: str) -> int:
 	# No matching device found, or default requested explicitly.
 	# Return the ID of Microsoft Sound Mapper
 	return -1
+
+
+def _sapi4DeprecationWarning(synth: SynthDriver, audioOutputDevice: str, isFallback: bool):
+	"""A synthChanged event handler to alert the user about the deprecation of SAPI4."""
+
+	def setShown():
+		synth._hasWarningBeenShown = True
+		synth.saveSettings()
+
+	def impl():
+		gui.message.MessageDialog(
+			parent=None,
+			message=_(
+				# Translators: Message warning users that SAPI4 is deprecated.
+				"Microsoft Speech API version 4 is obsolete. "
+				"Using this speech synthesizer may pose a security risk. "
+				"This synthesizer driver will be removed in NVDA 2026.1. "
+				"You are strongly encouraged to choose a more modern speech synthesizer. "
+				"Consult the Supported Speech Synthesizers section in the user guide for suggestions.",
+			),
+			# Translators: Title of a message dialog.
+			title=_("Warning"),
+			buttons=None,
+		).addOkButton(
+			callback=setShown,
+		).addHelpButton(
+			# Translators: A button in a dialog.
+			label=_("Open user guide"),
+			callback=lambda: gui.contextHelp.showHelp("SupportedSpeechSynths"),
+		).Show()
+
+	if (not isFallback) and (synth.name == "sapi4") and (not getattr(synth, "_hasWarningBeenShown", False)):
+		# We need to queue the dialog to appear, as wx may not have been initialised the first time this is called.
+		queueHandler.queueFunction(queueHandler.eventQueue, impl)
+
+
+if not globalVars.appArgs.secure:
+	# Don't warn users about SAPI4 deprecation in secure mode.
+	# This stops the dialog appearing on secure screens and when secure mode has been forced.
+	synthChanged.register(_sapi4DeprecationWarning)

user_docs/en/changes.md

@@ -182,6 +182,7 @@ Instead, a `callback` property has been added, which returns a function that per
 * Because SAPI5 voices now use `nvwave.WavePlayer` to output audio: (#17592, @gexgd0419)
   * `synthDrivers.sapi5.SPAudioState` has been removed.
   * `synthDrivers.sapi5.SynthDriver.ttsAudioStream` has been removed.
+* Instances of `autoSettingsUtils.driverSetting.DriverSetting` with an `id` that starts with an underscore (_) are no longer shown in NVDA's settings. (#17599)
 
 #### Deprecations