preparing the new magnifier types

source/_magnifier/__init__.py

@@ -9,55 +9,116 @@
 """
 
 from typing import TYPE_CHECKING
-from .fullscreenMagnifier import FullScreenMagnifier
+from .config import getMagnifierType
+from .utils.types import MagnifierType
 
 if TYPE_CHECKING:
 	from .magnifier import Magnifier
 
 _magnifier: "Magnifier | None" = None
 
 
-def initialize():
+def createMagnifier(magnifierType: MagnifierType) -> "Magnifier":
 	"""
-	Initialize the magnifier module
-	For now, only the full-screen magnifier is supported
+	Create a magnifier instance based on the specified type.
+
+	:param magnifierType: The type of magnifier to create
+	:return: The created magnifier instance
+	:raises ValueError: If the magnifier type is not supported
+	"""
+
+	match magnifierType:
+		case MagnifierType.FULLSCREEN:
+			from .fullscreenMagnifier import FullScreenMagnifier
+
+			return FullScreenMagnifier()
+
+		case MagnifierType.FIXED:
+			from .placeholderMagnifier import PlaceholderMagnifier
+
+			return PlaceholderMagnifier()
+
+		case MagnifierType.DOCKED:
+			from .placeholderMagnifier import PlaceholderMagnifier
+
+			return PlaceholderMagnifier()
+
+		case MagnifierType.LENS:
+			from .placeholderMagnifier import PlaceholderMagnifier
+
+			return PlaceholderMagnifier()
+
+		case _:
+			raise ValueError(f"Unsupported magnifier type: {magnifierType}")
+
+
+def _setMagnifierType(magnifierType: MagnifierType) -> None:
+	"""
+	Set the magnifier type, stopping the current one if active and creating a new instance.
+
+	:param magnifierType: The type of magnifier to set
 	"""
+	global _magnifier
+
+	# Stop current magnifier if active
+	if _magnifier and _magnifier._isActive:
+		_magnifier._stopMagnifier()
 
-	magnifier = FullScreenMagnifier()
-	setMagnifier(magnifier)
+	# Create and set new magnifier instance
+	_magnifier = createMagnifier(magnifierType)
+
+
+def initialize() -> None:
+	"""
+	Initialize the magnifier module with the default magnifier type from config.
+	"""
+	magnifierType = getMagnifierType()
+	_setMagnifierType(magnifierType)
+	_magnifier._startMagnifier()
 
 
 def isActive() -> bool:
 	"""
-	Check if magnifier is currently active for settings
+	Check if magnifier is currently active.
+
+	:return: True if magnifier is active, False otherwise
 	"""
 	global _magnifier
-	return _magnifier and _magnifier._isActive
+	return _magnifier is not None and _magnifier._isActive
 
 
-def getMagnifier() -> "Magnifier | None":
+def changeMagnifierType(magnifierType: MagnifierType) -> None:
 	"""
-	Get current magnifier
+	Change the magnifier type at runtime.
+	Stops the current magnifier and starts a new one of the specified type.
+
+	:param magnifierType: The new magnifier type to use
+	:raises RuntimeError: If no magnifier is currently active
 	"""
 	global _magnifier
-	return _magnifier
+	if not _magnifier or not _magnifier._isActive:
+		raise RuntimeError("Cannot change magnifier type: magnifier is not active")
 
+	_setMagnifierType(magnifierType)
+	_magnifier._startMagnifier()
 
-def setMagnifier(magnifier: "Magnifier") -> None:
+
+def getMagnifier() -> "Magnifier | None":
 	"""
-	Set magnifier instance
+	Get the current magnifier instance.
 
-	:param magnifier: The magnifier instance to set
+	:return: The current magnifier instance, or None if not initialized
 	"""
 	global _magnifier
-	_magnifier = magnifier
+	return _magnifier
 
 
-def terminate():
+def terminate() -> None:
 	"""
-	Called when NVDA shuts down
+	Terminate the magnifier module.
+	Called when NVDA shuts down.
 	"""
 	global _magnifier
 	if _magnifier and _magnifier._isActive:
 		_magnifier._stopMagnifier()
-		_magnifier = None
+	_magnifier = None

source/_magnifier/commands.py

@@ -10,11 +10,13 @@
 
 from typing import Literal
 import ui
-from . import getMagnifier, initialize, terminate
+from . import getMagnifier, initialize, terminate, changeMagnifierType
 from .config import (
 	getDefaultZoomLevelString,
 	getDefaultFilter,
 	getDefaultFullscreenMode,
+	getMagnifierType,
+	setMagnifierType,
 	ZoomLevel,
 )
 from .magnifier import Magnifier
@@ -101,19 +103,31 @@ def toggleMagnifier() -> None:
 		initialize()
 
 		filter = getDefaultFilter()
-		fullscreenMode = getDefaultFullscreenMode()
-
-		ui.message(
-			pgettext(
+		magnifierType = getMagnifierType()
+		zoomLevel = getDefaultZoomLevelString()
+		if magnifierType == MagnifierType.FULLSCREEN:
+			fullscreenMode = getDefaultFullscreenMode()
+			msg = pgettext(
 				"magnifier",
 				# Translators: Message announced when starting the NVDA magnifier.
-				"Starting magnifier with {zoomLevel} zoom level, {filter} filter, and {fullscreenMode} full-screen mode",
+				"Starting {magnifierType} magnifier with {zoomLevel} zoom level, {filter} filter, and {fullscreenMode} full-screen mode",
 			).format(
-				zoomLevel=getDefaultZoomLevelString(),
+				magnifierType=magnifierType.displayString,
+				zoomLevel=zoomLevel,
 				filter=filter.displayString,
 				fullscreenMode=fullscreenMode.displayString,
-			),
-		)
+			)
+		else:
+			msg = pgettext(
+				"magnifier",
+				# Translators: Message announced when starting the NVDA magnifier.
+				"Starting {magnifierType} magnifier with {zoomLevel} zoom level and {filter} filter",
+			).format(
+				magnifierType=magnifierType.displayString,
+				zoomLevel=zoomLevel,
+				filter=filter.displayString,
+			)
+		ui.message(msg)
 
 
 def zoom(direction: Direction) -> None:
@@ -175,6 +189,30 @@ def toggleFilter() -> None:
 		)
 
 
+def cycleMagnifierType() -> None:
+	"""Cycle through magnifier types (full-screen, fixed, docked (to do), lens (to do))"""
+	magnifier: Magnifier = getMagnifier()
+	if magnifierIsActiveVerify(
+		magnifier,
+		MagnifierAction.CHANGE_MAGNIFIER_TYPE,
+	):
+		types = list(MagnifierType)
+		currentType = magnifier._magnifierType
+		idx = types.index(currentType)
+		newType = types[(idx + 1) % len(types)]
+		log.debug(f"Changing magnifier type from {currentType} to {newType}")
+		changeMagnifierType(newType)
+		setMagnifierType(newType)
+		magnifier = getMagnifier()
+		ui.message(
+			pgettext(
+				"magnifier",
+				# Translators: Message announced when changing the magnifier type with {type} being the new magnifier type.
+				"Magnifier type changed to {type}",
+			).format(type=magnifier._magnifierType.displayString),
+		)
+
+
 def toggleFullscreenMode() -> None:
 	"""Cycle through full-screen focus modes (center, border, relative)"""
 	magnifier: Magnifier = getMagnifier()

source/_magnifier/config.py

@@ -9,7 +9,7 @@
 """
 
 import config
-from .utils.types import Filter, FullScreenMode
+from .utils.types import Filter, FullScreenMode, MagnifierType
 
 
 class ZoomLevel:
@@ -123,6 +123,24 @@ def setDefaultFilter(filter: Filter) -> None:
 	config.conf["magnifier"]["defaultFilter"] = filter.value
 
 
+def getMagnifierType() -> MagnifierType:
+	"""
+	Get magnifier type from config.
+
+	:return: The magnifier type.
+	"""
+	return MagnifierType(config.conf["magnifier"]["magnifierType"])
+
+
+def setMagnifierType(magnifierType: MagnifierType) -> None:
+	"""
+	Set magnifier type from settings.
+
+	:param magnifierType: The magnifier type to set.
+	"""
+	config.conf["magnifier"]["magnifierType"] = magnifierType.value
+
+
 def getDefaultFullscreenMode() -> FullScreenMode:
 	"""
 	Get default full-screen mode from config.

source/_magnifier/fullscreenMagnifier.py

@@ -14,17 +14,17 @@
 from .magnifier import Magnifier
 from .utils.filterHandler import FilterMatrix
 from .utils.spotlightManager import SpotlightManager
-from .utils.types import Filter, Coordinates, FullScreenMode
+from .utils.types import Filter, Coordinates, FullScreenMode, MagnifierType
 from .config import getDefaultFullscreenMode
 
 
 class FullScreenMagnifier(Magnifier):
 	def __init__(self):
 		super().__init__()
+		self._magnifierType = MagnifierType.FULLSCREEN
 		self._fullscreenMode = getDefaultFullscreenMode()
 		self._currentCoordinates = Coordinates(0, 0)
 		self._spotlightManager = SpotlightManager(self)
-		self._startMagnifier()
 
 	@property
 	def filterType(self) -> Filter:

source/_magnifier/magnifier.py

@@ -42,7 +42,7 @@ class Magnifier:
 
 	def __init__(self):
 		self._displayOrientation = getPrimaryDisplayOrientation()
-		self._magnifierType: MagnifierType = MagnifierType.FULLSCREEN
+		self._magnifierType: MagnifierType
 		self._isActive: bool = False
 		self._zoomLevel: float = getDefaultZoomLevel()
 		self._panStep: int = getDefaultPanStep()

source/_magnifier/placeholderMagnifier.py

@@ -0,0 +1,26 @@
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2025 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
+"""
+Placeholder magnifier module.
+"""
+
+from .magnifier import Magnifier
+from .utils.types import Coordinates, MagnifierType
+
+
+class PlaceholderMagnifier(Magnifier):
+	def __init__(self):
+		super().__init__()
+		self._magnifierType = MagnifierType.PLACEHOLDER
+		self._currentCoordinates = Coordinates(0, 0)
+
+	def _startMagnifier(self) -> None:
+		super()._startMagnifier()
+
+	def _stopMagnifier(self) -> None:
+		super()._stopMagnifier()
+
+	def _doUpdate(self):
+		super()._doUpdate()

source/_magnifier/utils/types.py

@@ -41,6 +41,7 @@ class MagnifierAction(DisplayStringEnum):
 	PAN_TOP_EDGE = auto()
 	PAN_BOTTOM_EDGE = auto()
 	TOGGLE_FILTER = auto()
+	CHANGE_MAGNIFIER_TYPE = auto()
 	CHANGE_FULLSCREEN_MODE = auto()
 	START_SPOTLIGHT = auto()
 
@@ -69,6 +70,8 @@ def _displayStringLabels(self) -> dict["MagnifierAction", str]:
 			self.PAN_BOTTOM_EDGE: pgettext("magnifier action", "pan to bottom edge"),
 			# Translators: Action description for toggling color filters.
 			self.TOGGLE_FILTER: pgettext("magnifier action", "toggle filters"),
+			# Translators: Action description for changing magnifier type.
+			self.CHANGE_MAGNIFIER_TYPE: pgettext("magnifier action", "change magnifier type"),
 			# Translators: Action description for changing full-screen mode.
 			self.CHANGE_FULLSCREEN_MODE: pgettext("magnifier action", "change full-screen mode"),
 			# Translators: Action description for starting spotlight mode.
@@ -80,18 +83,24 @@ class MagnifierType(DisplayStringStrEnum):
 	"""Type of magnifier"""
 
 	FULLSCREEN = "fullscreen"
+	FIXED = "fixed"
 	DOCKED = "docked"
 	LENS = "lens"
+	PLACEHOLDER = "placeholder"
 
 	@property
 	def _displayStringLabels(self) -> dict["MagnifierType", str]:
 		return {
 			# Translators: Magnifier type - full-screen mode.
 			self.FULLSCREEN: pgettext("magnifier", "Fullscreen"),
+			# Translators: Magnifier type - fixed mode.
+			self.FIXED: pgettext("magnifier", "Fixed"),
 			# Translators: Magnifier type - docked mode.
 			self.DOCKED: pgettext("magnifier", "Docked"),
 			# Translators: Magnifier type - lens mode.
 			self.LENS: pgettext("magnifier", "Lens"),
+			# Translators: Magnifier type - placeholder for unsupported types.
+			self.PLACEHOLDER: pgettext("magnifier", "Placeholder"),
 		}
 
 

source/config/configSpec.py

@@ -116,6 +116,7 @@
 [magnifier]
 	defaultZoomLevel = float(min=1.0, max=10.0, default=2.0)
 	defaultPanStep = integer(min=1, max=100, default=10)
+	magnifierType = string(default="fullscreen")
 	defaultFullscreenMode = string(default="center")
 	isTrueCentered = boolean(default=False)
 	defaultFilter = string(default="normal")

source/globalCommands.py

@@ -5159,6 +5159,20 @@ def script_toggleFilter(
 	) -> None:
 		_magnifier.commands.toggleFilter()
 
+	@script(
+		description=_(
+			# Translators: Describes a command.
+			"Cycle through Magnifier type",
+		),
+		category=SCRCAT_VISION,
+		gesture="kb:nvda+shift+t",
+	)
+	def script_cycleMagnifierType(
+		self,
+		gesture: inputCore.InputGesture,
+	) -> None:
+		_magnifier.commands.cycleMagnifierType()
+
 	@script(
 		description=_(
 			# Translators: Describes a command.