beta to master (#20143)

Co-authored-by: GitHub Actions <actions@github.com>

Author: seanbudd

source/_magnifier/__init__.py

@@ -9,7 +9,10 @@
 """
 
 from typing import TYPE_CHECKING
-from .config import getMagnifiedView
+
+from logHandler import log
+
+from .config import getMagnifiedView, getEnabled, setEnabled
 from .utils.types import MagnifiedView
 
 if TYPE_CHECKING:
@@ -72,9 +75,44 @@ def initialize() -> None:
 	"""
 	Initialize the magnifier module with the default magnifier view from config.
 	"""
+	log.debug("Initializing magnifier")
 	magnifiedView = getMagnifiedView()
 	_setMagnifiedView(magnifiedView)
+	if getEnabled():
+		start()
+
+
+def terminate() -> None:
+	"""
+	Terminate the magnifier module.
+	Called when NVDA shuts down.
+	"""
+	global _magnifier
+
+	log.debug("Terminating magnifier")
+	stop(persist=False)
+	_magnifier = None
+
+
+def start() -> None:
+	if _magnifier is None:
+		log.error("Attempted to start magnifier, but it is not initialized.")
+		return
 	_magnifier._startMagnifier()
+	setEnabled(True)
+
+
+def stop(persist: bool = True) -> None:
+	"""Stop the magnifier if it is active.
+
+	:param persist: Whether to persist the magnifier state
+	"""
+	if isActive():
+		_magnifier._stopMagnifier()
+		if persist:
+			setEnabled(False)
+	else:
+		log.debug("Attempted to stop magnifier, but it is not active.")
 
 
 def isActive() -> bool:
@@ -111,14 +149,3 @@ def getMagnifier() -> "Magnifier | None":
 	"""
 	global _magnifier
 	return _magnifier
-
-
-def terminate() -> None:
-	"""
-	Terminate the magnifier module.
-	Called when NVDA shuts down.
-	"""
-	global _magnifier
-	if _magnifier and _magnifier._isActive:
-		_magnifier._stopMagnifier()
-	_magnifier = None

source/_magnifier/commands.py

@@ -10,17 +10,17 @@
 
 from typing import Literal
 import ui
-from . import getMagnifier, initialize, terminate, changeMagnifiedView
+from . import changeMagnifiedView, getMagnifier, start, stop
 from .config import (
 	getMagnifiedView,
 	setMagnifiedView,
 	getZoomLevelString,
 	getFilter,
-	getFullscreenMode,
-	ZoomLevel,
 	getFollowState,
+	getFullscreenMode,
 	setFollowState,
 	toggleAllFollowStates,
+	ZoomLevel,
 )
 from .magnifier import Magnifier
 from .fullscreenMagnifier import FullScreenMagnifier
@@ -89,7 +89,7 @@ def toggleMagnifier() -> None:
 	magnifier: Magnifier | None = getMagnifier()
 	if magnifier and magnifier._isActive:
 		# Stop magnifier
-		terminate()
+		stop()
 		ui.message(
 			pgettext(
 				"magnifier",
@@ -107,7 +107,7 @@ def toggleMagnifier() -> None:
 			),
 		)
 	else:
-		initialize()
+		start()
 		currentFilter = getFilter()
 		magnifiedView = getMagnifiedView()
 		zoomLevel = getZoomLevelString()

source/_magnifier/config.py

@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2025 NV Access Limited, Antoine Haffreingue
+# Copyright (C) 2025-2026 NV Access Limited, Antoine Haffreingue
 # This file may be used under the terms of the GNU General Public License, version 2 or later, as modified by the NVDA license.
 # For full terms and any additional permissions, see the NVDA license file: https://github.com/nvaccess/nvda/blob/master/copying.txt
 
@@ -13,6 +13,24 @@
 from .utils.types import Filter, FullScreenMode, MagnifierFollowFocusType, MagnifiedView
 
 
+def setEnabled(enable: bool) -> None:
+	"""
+	Set the config for the magnifier state (enable or disabled).
+
+	:param enable: True if the magnifier is enabled, False if it is disabled.
+	"""
+	config.conf["magnifier"]["enabled"] = enable
+
+
+def getEnabled() -> bool:
+	"""
+	Check if the magnifier is enabled in config.
+
+	:return: True if the magnifier is enabled, False otherwise.
+	"""
+	return config.conf["magnifier"]["enabled"]
+
+
 class ZoomLevel:
 	"""
 	Constants and utilities for zoom level management.

source/_magnifier/fullscreenMagnifier.py

@@ -41,7 +41,6 @@ def __init__(self):
 		self.currentCoordinates = Coordinates(0, 0)
 		self._spotlightManager = SpotlightManager(self)
 		self._displaySize = Size(self._displayOrientation.width, self._displayOrientation.height)
-		self._startMagnifier()
 
 	@Magnifier.filterType.setter
 	def filterType(self, value: Filter) -> None:

source/config/configSpec.py

@@ -116,6 +116,7 @@
 
 # Magnifier settings
 [magnifier]
+	enabled = boolean(default=false)
 	magnifiedView = string(default="fullscreen")
 	zoomLevel = float(min=1.0, max=10.0, default=2.0)
 	isTrueCentered = boolean(default=False)

source/core.py

@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2006-2025 NV Access Limited, Aleksey Sadovoy, Christopher Toth, Joseph Lee, Peter Vágner,
+# Copyright (C) 2006-2026 NV Access Limited, Aleksey Sadovoy, Christopher Toth, Joseph Lee, Peter Vágner,
 # Derek Riemer, Babbage B.V., Zahari Yurukov, Łukasz Golonka, Cyrille Bougot, Julien Cochuyt
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
@@ -10,7 +10,6 @@
 from typing import (
 	TYPE_CHECKING,
 	Any,
-	List,
 	Optional,
 )
 import comtypes
@@ -135,7 +134,7 @@ def handleReplaceCLIArg(cliArgument: str) -> bool:
 		return cliArgument in ("-r", "--replace")
 
 	addonHandler.isCLIParamKnown.register(handleReplaceCLIArg)
-	unknownCLIParams: List[str] = list()
+	unknownCLIParams: list[str] = list()
 	for param in globalVars.unknownAppArgs:
 		isParamKnown = addonHandler.isCLIParamKnown.decide(cliArgument=param)
 		if not isParamKnown:
@@ -324,7 +323,9 @@ def resetConfiguration(factoryDefaults=False):
 	import audio
 	import screenCurtain
 	import mathPres
+	import _magnifier as magnifier
 
+	magnifier.terminate()
 	log.debug("Terminating vision")
 	vision.terminate()
 	log.debug("Terminating Screen Curtain")
@@ -399,6 +400,7 @@ def resetConfiguration(factoryDefaults=False):
 	vision.initialize()
 	log.debug("initializing Screen Curtain")
 	screenCurtain.initialize()
+	magnifier.initialize()
 	log.debug("Reloading user and locale input gesture maps")
 	inputCore.manager.loadUserGestureMap()
 	inputCore.manager.loadLocaleGestureMap()
@@ -1058,6 +1060,10 @@ def Notify(self):
 
 	sessionTracking.initialize()
 
+	import _magnifier as magnifier
+
+	magnifier.initialize()
+
 	NVDAState._TrackNVDAInitialization.markInitializationComplete()
 
 	log.info("NVDA initialized")
@@ -1084,6 +1090,7 @@ def _doPostNvdaStartupAction():
 		)
 		queueHandler.pumpAll()
 	_terminate(gui)
+	_terminate(magnifier)
 	config.saveOnExit()
 
 	_doLoseFocus()

source/gui/settingsDialogs.py

@@ -40,6 +40,7 @@
 import keyboardHandler
 import languageHandler
 import logHandler
+from _magnifier.commands import toggleMagnifier
 import _magnifier.config as magnifierConfig
 from _magnifier.utils.types import Filter, FullScreenMode, MagnifierFollowFocusType
 import queueHandler
@@ -6049,6 +6050,18 @@ def makeSettings(
 			sizer=settingsSizer,
 		)
 
+		# Enable the magnifier
+		# Translators: The label for a setting in magnifier settings to enable or disable the magnifier.
+		enableMagnifierText = _("&Enable magnifier (immediate effect)")
+		self._magnifierEnabledInitially = magnifierConfig.getEnabled()
+		self.enableMagnifierCheckBox = sHelper.addItem(wx.CheckBox(self, label=enableMagnifierText))
+		self.bindHelpEvent(
+			"MagnifierEnable",
+			self.enableMagnifierCheckBox,
+		)
+		self.enableMagnifierCheckBox.Bind(wx.EVT_CHECKBOX, self.onEnableMagnifierChange)
+		self.enableMagnifierCheckBox.SetValue(self._magnifierEnabledInitially)
+
 		# ZOOM SETTINGS
 		# Translators: The label for a setting in magnifier settings to select the zoom level.
 		zoomLabelText = _("&Zoom level:")
@@ -6066,7 +6079,7 @@ def makeSettings(
 			self.zoomList,
 		)
 
-		# Set  value from config
+		# Set value from config
 		zoomLevel = magnifierConfig.getZoomLevel()
 		zoomIndex = bisect.bisect_left(zoomValues, zoomLevel)
 		# Find the closest value
@@ -6099,7 +6112,7 @@ def makeSettings(
 
 		# FILTER SETTINGS
 		# Translators: The label for a setting in magnifier settings to select the default filter
-		filterLabelText = _("&filter:")
+		filterLabelText = _("F&ilter:")
 		filterChoices = [f.displayString for f in Filter]
 		self.filterList = sHelper.addLabeledControl(
 			filterLabelText,
@@ -6114,7 +6127,7 @@ def makeSettings(
 
 		# FULLSCREEN MODE SETTINGS
 		# Translators: The label for a setting in magnifier settings to select the full-screen mode
-		fullscreenModeLabelText = _("&fullscreen mode:")
+		fullscreenModeLabelText = _("&Fullscreen mode:")
 		fullscreenModeChoices = [mode.displayString for mode in FullScreenMode] if FullScreenMode else []
 		self.fullscreenModeList = sHelper.addLabeledControl(
 			fullscreenModeLabelText,
@@ -6170,7 +6183,7 @@ def makeSettings(
 
 		# KEEP MOUSE CENTERED
 		# Translators: The label for a checkbox to keep the mouse pointer centered in the magnifier view
-		keepMouseCenteredText = _("Keep &mouse pointer centered in magnifier view")
+		keepMouseCenteredText = _("Keep mouse pointer &centered in magnifier view")
 		self.keepMouseCenteredCheckBox = sHelper.addItem(wx.CheckBox(self, label=keepMouseCenteredText))
 		self.bindHelpEvent(
 			"MagnifierKeepMouseCentered",
@@ -6180,6 +6193,8 @@ def makeSettings(
 
 	def onSave(self):
 		"""Save the current selections to config."""
+		magnifierConfig.setEnabled(self.enableMagnifierCheckBox.GetValue())
+
 		selectedZoom = self.zoomList.GetSelection()
 		magnifierConfig.setZoomLevel(magnifierConfig.ZoomLevel.zoom_range()[selectedZoom])
 
@@ -6196,6 +6211,20 @@ def onSave(self):
 			magnifierConfig.setFollowState(focusType, checkBox.GetValue())
 		config.conf["magnifier"]["keepMouseCentered"] = self.keepMouseCenteredCheckBox.GetValue()
 
+	def onDiscard(self):
+		"""Restore magnifier state from original settings from config."""
+		if self._magnifierEnabledInitially != magnifierConfig.getEnabled():
+			toggleMagnifier()
+			self.enableMagnifierCheckBox.SetValue(self._magnifierEnabledInitially)
+
+	def onEnableMagnifierChange(self, evt: wx.CommandEvent):
+		"""Enable magnifier immediately when the checkbox is toggled, and update the checkbox state if there is an error enabling the magnifier."""
+		requestedEnabled = evt.IsChecked()
+		currentEnabled = magnifierConfig.getEnabled()
+		if requestedEnabled != currentEnabled:
+			toggleMagnifier()
+			self.enableMagnifierCheckBox.SetValue(magnifierConfig.getEnabled())
+
 
 class PrivacyAndSecuritySettingsPanel(SettingsPanel):
 	# Translators: The title of the privacy and security category in NVDA's settings.

tests/unit/test_magnifier/test_fullscreenMagnifier.py

@@ -298,6 +298,7 @@ def testCannotStartWhenWindowsMagnifierRunning(self):
 
 		with patch("_magnifier.fullscreenMagnifier.ui.message") as mock_message:
 			magnifier = FullScreenMagnifier()
+			magnifier._startMagnifier()
 
 		self.assertFalse(magnifier._isActive)
 		mock_message.assert_called_once()
@@ -311,6 +312,7 @@ def testCannotStartWhenMagInitializeFails(self):
 
 		with patch("_magnifier.fullscreenMagnifier.ui.message") as mock_message:
 			magnifier = FullScreenMagnifier()
+			magnifier._startMagnifier()
 
 		self.assertFalse(magnifier._isActive)
 		mock_message.assert_called_once()