Persist magnifier starting (#20051)

Fixes #19494
Summary of the issue:

Whether or not the magnifier has already started was not persisted in config
Description of user facing changes:

magnifier being enabled is now persisted in config

fixed some collisions with accelerator keys in the magnifier settings dialog
Description of developer facing changes:

none
Description of development approach:

added code to toggle magnifier and persist in settings

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()

user_docs/en/userGuide.md

@@ -1573,6 +1573,7 @@ To enable or disable the magnifier, press `NVDA+shift+w`.
 The "Increase magnification level" keystroke, `NVDA+shift+equals`, will start the magnifier if it is not running.
 When the magnifier is enabled, NVDA will announce the current zoom level, color filter, and focus tracking mode.
 When disabled, the screen returns to its normal size.
+The Magnifier state is saved for future NVDA sessions, so after enabling Magnifier, it will start automatically after restarting NVDA
 
 Important: The NVDA Magnifier cannot be used simultaneously with Screen Curtain for security reasons.
 If you attempt to enable the magnifier while Screen Curtain is active, NVDA will prompt you to disable Screen Curtain first, and vice versa.
@@ -2877,6 +2878,16 @@ Key: `NVDA+control+w`
 The Magnifier category in the NVDA Settings dialog allows you to configure the default behavior of NVDA's built-in [Magnifier](#Magnifier) feature.
 This settings category contains the following options:
 
+##### Enable Magnifier {#MagnifierEnable}
+
+When toggled, Magnifier will start and stop immediately.
+The selected state is also saved for future NVDA sessions, so if you enable Magnifier here, it will start automatically after restarting NVDA.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Disabled|
+
 ##### Zoom level {#MagnifierZoom}
 
 This slider allows you to set the zoom level when using the magnifier.