Add a graphical user interface for the vision framework

source/autoSettingsUtils/autoSettings.py

@@ -243,26 +243,20 @@ def loadSettings(self, onlyChanged: bool = False):
 		self._loadSpecificSettings(self, self.supportedSettings, onlyChanged)
 
 	@classmethod
-	def _paramToPercent(cls, current, min, max):
+	def _paramToPercent(cls, current: int, min: int, max: int) -> int:
 		"""Convert a raw parameter value to a percentage given the current, minimum and maximum raw values.
 		@param current: The current value.
-		@type current: int
 		@param min: The minimum value.
-		@type current: int
 		@param max: The maximum value.
-		@type max: int
 		"""
 		return paramToPercent(current, min, max)
 
 	@classmethod
-	def _percentToParam(cls, percent, min, max):
+	def percentToParam(cls, percent: int, min: int, max: int) -> int:
 		"""Convert a percentage to a raw parameter value given the current percentage and the minimum and maximum
-		 raw parameter values.
+		raw parameter values.
 		@param percent: The current percentage.
-		@type percent: int
 		@param min: The minimum raw parameter value.
-		@type min: int
 		@param max: The maximum raw parameter value.
-		@type max: int
 		"""
 		return percentToParam(percent, min, max)

source/autoSettingsUtils/utils.py

@@ -8,7 +8,7 @@
 """
 
 
-def paramToPercent(current, min, max):
+def paramToPercent(current: int, min: int, max: int) -> int:
 	"""Convert a raw parameter value to a percentage given the current, minimum and maximum raw values.
 	@param current: The current value.
 	@type current: int
@@ -17,10 +17,10 @@ def paramToPercent(current, min, max):
 	@param max: The maximum value.
 	@type max: int
 	"""
-	return int(round(float(current - min) / (max - min) * 100))
+	return round(float(current - min) / (max - min) * 100)
 
 
-def percentToParam(percent, min, max):
+def percentToParam(percent: int, min: int, max: int) -> int:
 	"""Convert a percentage to a raw parameter value given the current percentage and the minimum and maximum
 	raw parameter values.
 	@param percent: The current percentage.
@@ -30,7 +30,7 @@ def percentToParam(percent, min, max):
 	@param max: The maximum raw parameter value.
 	@type max: int
 	"""
-	return int(round(float(percent) / 100 * (max - min) + min))
+	return round(float(percent) / 100 * (max - min) + min)
 
 
 class UnsupportedConfigParameterError(NotImplementedError):
@@ -43,16 +43,13 @@ class StringParameterInfo(object):
 	"""
 	Used to represent a value of a DriverSetting instance.
 	"""
+	id: str
+	displayName: str
 
-	def __init__(self, id, displayName):
+	def __init__(self, id: str, displayName: str):
 		"""
 		@param id: The unique identifier of the value.
-		@type id: str
 		@param displayName: The name of the value, visible to the user.
-		@type displayName: str
 		"""
 		self.id = id
 		self.displayName = displayName
-		# Keep backwards compatibility
-		self.ID = id
-		self.name = displayName

source/globalCommands.py

@@ -2358,7 +2358,7 @@ def script_toggleScreenCurtain(self, gesture):
 
 		from visionEnhancementProviders.screenCurtain import ScreenCurtainProvider
 		screenCurtainId = ScreenCurtainProvider.getSettings().getId()
-		screenCurtainProviderInfo = vision.visionHandler.getProviderInfo(screenCurtainId)
+		screenCurtainProviderInfo = vision.handler.getProviderInfo(screenCurtainId)
 		alreadyRunning = screenCurtainId in vision.handler.providers
 
 		GlobalCommands._tempEnableScreenCurtain = scriptCount == 0
@@ -2418,7 +2418,7 @@ def script_toggleScreenCurtain(self, gesture):
 			scriptCount in (0, 1)  # 1 press (temp enable) or 2 presses (enable)
 		):
 			# Check if screen curtain is available, exit early if not.
-			if not vision.getProviderClass(screenCurtainId).canStart():
+			if not screenCurtainProviderInfo.providerClass.canStart():
 				# Translators: Reported when the screen curtain is not available.
 				message = _("Screen curtain not available")
 				self._toggleScreenCurtainMessage = message

source/gui/settingsDialogs.py

@@ -300,7 +300,7 @@ def _buildGui(self):
 		self.SetSizer(self.mainSizer)
 
 	@abstractmethod
-	def makeSettings(self, sizer) -> wx.BoxSizer:
+	def makeSettings(self, sizer: wx.BoxSizer):
 		"""Populate the panel with settings controls.
 		Subclasses must override this method.
 		@param sizer: The sizer to which to add the settings controls.
@@ -1018,6 +1018,7 @@ def driver(self):
 		return self._driverRef()
 
 	def __call__(self,evt):
+		evt.Skip()  # allow other handlers to also process this event.
 		val=evt.GetSelection()
 		setattr(self.driver,self.setting.id,val)
 
@@ -1028,6 +1029,7 @@ def __init__(self,driver,setting,container):
 		super(StringDriverSettingChanger,self).__init__(driver,setting)
 
 	def __call__(self,evt):
+		evt.Skip()  # allow other handlers to also process this event.
 		# Quick workaround to deal with voice changes.
 		if self.setting.id == "voice":
 			# Cancel speech first so that the voice will change immediately instead of the change being queued.
@@ -2845,10 +2847,17 @@ def onOk(self, evt):
 			port = self.possiblePorts[self.portsList.GetSelection()][0]
 			config.conf["braille"][display]["port"] = port
 		if not braille.handler.setDisplayByName(display):
-			# Translators: This message is presented when
-			# NVDA is unable to load the selected
-			# braille display.
-			gui.messageBox(_("Could not load the %s display.")%display, _("Braille Display Error"), wx.OK|wx.ICON_WARNING, self)
+
+			gui.messageBox(
+				# Translators: The message in a dialog presented when NVDA is unable to load the selected
+				# braille display.
+				message=_(f"Could not load the {display} display."),
+				# Translators: The title in a dialog presented when NVDA is unable to load the selected
+				# braille display.
+				caption=_("Braille Display Error"),
+				style=wx.OK | wx.ICON_WARNING,
+				parent=self
+			)
 			return 
 
 		if self.IsModal():
@@ -3121,13 +3130,13 @@ def showTerminationErrorForProviders(
 			"Could not gracefully terminate the following vision enhancement providers:\n"
 			f"{providerNames }"
 		)
-		gui.messageBox(
-			message,
-			# Translators: The title of the vision enhancement provider error message box.
-			_("Vision Enhancement Provider Error"),
-			wx.OK | wx.ICON_WARNING,
-			parent,
-		)
+	gui.messageBox(
+		message,
+		# Translators: The title of the vision enhancement provider error message box.
+		_("Vision Enhancement Provider Error"),
+		wx.OK | wx.ICON_WARNING,
+		parent,
+	)
 
 
 class VisionProviderStateControl(vision.providerBase.VisionProviderStateControl):
@@ -3221,7 +3230,7 @@ class VisionSettingsPanel(SettingsPanel):
 
 	def _getProviderInfos(self) -> List[vision.providerInfo.ProviderInfo]:
 		return list(
-			vision.visionHandler.getProviderInfo(providerId) for providerId in vision.handler.providers
+			vision.handler.getProviderInfo(providerId) for providerId in vision.handler.providers
 		)
 
 	def _createProviderSettingsPanel(
@@ -3255,7 +3264,7 @@ def makeSettings(self, settingsSizer: wx.BoxSizer):
 		self.settingsSizerHelper = guiHelper.BoxSizerHelper(self, sizer=settingsSizer)
 		self.settingsSizerHelper.addItem(wx.StaticText(self, label=self.panelDescription))
 
-		for providerInfo in vision.visionHandler.getProviderList():
+		for providerInfo in vision.handler.getProviderList(reloadFromSystem=True):
 			providerSizer = self.settingsSizerHelper.addItem(
 				wx.StaticBoxSizer(wx.StaticBox(self, label=providerInfo.translatedName), wx.VERTICAL),
 				flag=wx.EXPAND
@@ -3296,8 +3305,7 @@ def safeTerminateProviders(
 		"""
 		errorProviders: List[vision.providerInfo.ProviderInfo] = []
 		for provider in providers:
-			with VisionProviderStateControl(self, provider) as control:
-				success = control.terminateProvider(shouldPromptOnError=False)
+			success = VisionProviderStateControl(self, provider).terminateProvider(shouldPromptOnError=False)
 			if not success:
 				errorProviders.append(provider)
 		if verbose:
@@ -3331,7 +3339,7 @@ def onDiscard(self):
 			providerInfo.providerId for providerInfo in self.initialProviders
 		]
 		providersToTerminate = [
-			vision.visionHandler.getProviderInfo(providerId) for providerId in vision.handler.providers
+			vision.handler.getProviderInfo(providerId) for providerId in vision.handler.providers
 			if providerId not in initialProviderIds
 		]
 		self.safeTerminateProviders(providersToTerminate)
@@ -3345,7 +3353,7 @@ def onSave(self):
 			except Exception:
 				log.debug(f"Error saving providerPanel: {panel.__class__!r}", exc_info=True)
 		self.initialProviders = list(
-			vision.visionHandler.getProviderInfo(providerId)
+			vision.handler.getProviderInfo(providerId)
 			for providerId in vision.handler.providers
 		)
 
@@ -3440,14 +3448,18 @@ def _nonEnableableGUI(self, evt):
 		self._checkBox.SetValue(False)
 
 	def _enableToggle(self, evt):
-		if evt.IsChecked():
-			self._providerControl.startProvider()
-			self._providerSettings.updateDriverSettings()
-			self._providerSettings.onPanelActivated()
-		else:
-			self._providerControl.terminateProvider()
-			self._providerSettings.updateDriverSettings()
-			self._providerSettings.onPanelActivated()
+		shouldBeRunning = evt.IsChecked()
+		if shouldBeRunning and not self._providerControl.startProvider():
+			self._checkBox.SetValue(False)
+			return
+		elif not shouldBeRunning and not self._providerControl.terminateProvider():
+			# When there is an error on termination, don't leave the checkbox checked.
+			# The provider should not be left configured to startup.
+			self._checkBox.SetValue(False)
+			return
+		# Able to successfully start / terminate:
+		self._providerSettings.updateDriverSettings()
+		self._providerSettings.onPanelActivated()
 		self._sendLayoutUpdatedEvent()
 
 	def onDiscard(self):

source/vision/__init__.py

@@ -10,7 +10,7 @@
 Add-ons can provide their own provider
 using modules in the visionEnhancementProviders package containing a L{VisionEnhancementProvider} class.
 """
-from .visionHandler import VisionHandler, getProviderClass
+from .visionHandler import VisionHandler
 import visionEnhancementProviders
 import config
 from typing import Optional

source/vision/providerBase.py

@@ -7,27 +7,37 @@
 """Module within the vision framework that contains the base vision enhancement provider class.
 """
 
-from abc import abstractmethod, ABC
+from abc import abstractmethod
 
 from autoSettingsUtils.autoSettings import AutoSettings
 from baseObject import AutoPropertyObject
 from .visionHandlerExtensionPoints import EventExtensionPoints
 from typing import Optional, Any
 
 
-class VisionEnhancementProviderSettings(AutoSettings, ABC):
+class VisionEnhancementProviderSettings(AutoSettings):
 	"""
 	Base class for settings for a vision enhancement provider.
 	Ensure that the following are implemented:
 	- AutoSettings.getId:
 			This is case sensitive. Used in the config file. Does not have to match the module name.
 	- AutoSettings.getTranslatedName:
-			The string that should appear in the GUI as the name
+			The string that should appear in the GUI as the name.
 	- AutoSettings._get_supportedSettings:
-			The "runtime" settings for your provider
+			The "runtime" settings for your provider. By default this just returns L{_get_preInitSettings}.
+			The implementation must handle how to modify the returned settings based on external (software,
+			hardware) dependencies.
 	Although technically optional, derived classes probably need to implement:
 	- AutoSettings._get_preInitSettings:
-			The settings always configurable for your provider
+			The settings that are always configurable for your provider.
+	@note
+	If the vision enhancement provider has settings, it will provide an implementation of this class.
+	The provider will hold a reference to an instance of this class, this is accessed through the class method
+	L{VisionEnhancementProvider.getSettings}.
+	One way to handle settings that are strictly runtime:
+	- During initialization, the vision enhancement provider can instruct the settings instance what it should
+	expose using the L{utoSettings._get_supportedSettings} property.
+	- "_exampleProvider_autoGui.py" provides an example of this.
 	"""
 	def __init__(self):
 		super().__init__()
@@ -122,7 +132,7 @@ def reinitialize(self) -> None:
 
 	@abstractmethod
 	def terminate(self) -> None:
-		"""Terminate this driver.
+		"""Terminate this provider.
 		This should be used for any required clean up.
 		@precondition: L{initialize} has been called.
 		@postcondition: This provider can no longer be used.