Magnifier implementation #19228

Boumtchack · 2025-11-17T12:01:25Z

Link to issue number:

Summary of the issue:

This pull request introduces a new NVDA magnifier feature, including docked and lens magnifier modes, color filter support, and a set of global commands for controlling magnification. The changes add new classes for handling magnifier windows, provide optimized color filtering, and implement keyboard shortcuts for toggling magnification, zooming, cycling modes, and color filters.

Description of user facing changes:

Implemented new script commands in globalCommands.py for starting/stopping the magnifier, zooming in/out, cycling color filters, toggling fullscreen mode, cycling magnifier types, and spotlighting the magnifier window, each with descriptive messages and gestures.

Description of developer facing changes:

Description of development approach:

Creating 3 types of magnifier that will be called based on prefered choice of the user. each one got his class and will share settings through parents class

Testing strategy:

unit test

Known issues with pull request:

Code Review Checklist:

Documentation:
- Change log entry
- User Documentation
- Developer / Technical Documentation
- Context sensitive help for GUI changes
Testing:
- Unit tests
- System (end to end) tests
- Manual testing
UX of all users considered:
- Speech
- Braille
- Low Vision
- Different web browsers
- Localization in other languages / culture than English
API is compatible with existing add-ons.
Security precautions taken.

…s or not

…g with nvda

Boumtchack · 2025-12-17T16:28:55Z

Here's what I still have to work on:

Spotlight Manager separated from Fullscreen module
Display change handling
Magnifier Action thing
check tests again?

I'll work on that tomorrow

CyrilleB79 · 2025-12-17T21:44:59Z

I have not done an in-depth review, but here are points that I have noted:

Screen curtain conflict

If NVDA magnifier is applying color filters, this conflicts with NVDA's Screen Curtain, since they both use the color transformation matrix. Trying to enable or disable in any order creates unexpected issues. Thus:

either, best solution, you integrate both so that they do not conflict with each other; Screen Curtain transformation needs to have priority on Magnifier; and Magnifier transformation/filtering should be restored if Magnifier is still enabled when exiting Magnifier.
or, easier, you just forbid to start Magnifier when Screen Curtain is enabled and the other way around

Documentation

A section in the User Guide as well as a Change log item ("New features" section) are required. The description in the User Guide should help understand if the feature is implemented as expected.

Logging

You are using log.info all around your code; we usually use log.debug in all these cases. log.info is rather used at startup, at exit or to log version number of all NVDA components.

Again, thanks for this work. I had not yet tested all the features, but the spotlight seems a very nice one (visual double check needs to be done by someone else than I though).

Boumtchack · 2025-12-18T13:55:57Z

I'll try to see what I can do for the screen curtain, but if is there a reason someone that uses screen curtain would use the magnifier and the other way around? I'm not sure both are used by the same users.

for the log.info, I was going to remove them anyway when everything was clean, it's just helpfull for me to see where I'm at.

I'm kinda lost on where and what I should do for Documentation, is there a way you could give me a placeholder on the files I should change?

CyrilleB79 · 2025-12-18T22:27:03Z

I'll try to see what I can do for the screen curtain, but if is there a reason someone that uses screen curtain would use the magnifier and the other way around? I'm not sure both are used by the same users.

I am such a user. Today, I use NVDA speech feedback as main information channel, in conjunction with Windows Magnifier (with color filter inverted colors) as additional information channel. In case I work with sensitive information, I activate Screen Curtain and use only speech channel. Today, I need to exit Magnifier or to remove color filter before enabling Screen Curtain, and to reopen Magnifier or to restore color filter after I have finished with Screen Curtain. Being able to enable and disable screen curtain keeping the same Magnifier configuration would be a plus.

Regarding the other way around, i.e. enabling / disabling Magnifier while Screen curtain is active, I have no real use cases in mind. But I can imagine these ones:

As a visually impaired user who suffer from the excessive brightness of a white background, I'd like to have the Magnifier enabled with its color filters as soon as I exit screen curtain.
Or: While Screen Curtain is enabled, I disable Screen curtain by mistake and want to re-enable it (or the other way around)

for the log.info, I was going to remove them anyway when everything was clean, it's just helpfull for me to see where I'm at.

OK. Nice.

I'm kinda lost on where and what I should do for Documentation, is there a way you could give me a placeholder on the files I should change?

The Change log is at user_docs/en/changes.md. You need to add a new item in section "2026.2", sub-section "New Features".

The User Guide is at user_docs/en/userGuide.md:

First, in section "### NVDA Settings", there is a sub-section describing each panel. You need to add a "#### Magnifier" section, and describe all its options. Take example on other panels.

Also, it seems quite likely that describing the panel's options is not enough. Since the Magnifier will be a full NVDA specific feature (not just a little feature), it needs to be described in its own section. I think that you need to write a "## Magnifier" section, probably just after the "## Vision" paragraph, to describe what the Magnifier feature in NVDA is and what it allows to do. For example:

describe all the Magnifier shortcuts
explain what are color filters (and maybe what they are for)
what the spotlight is and in which situation it may be useful
etc.

Only English documentation needs to be updated; the documentation in other languages will then be updated by translators from the English one.

Boumtchack · 2025-12-19T09:20:46Z

Thanks for the feedback!

Boumtchack · 2025-12-19T15:27:27Z

i have a hard time making a way to switch between magnifier and the Screen Curtain without errors, so I kept it it simple for now with just preventing one to launch if the other is enabled, I will still try to find a way to make it work as Cyrille said it would be a good point to be abble to toggle them.
Maybe it requires more deep changess that I'm not familiar with, as I try to change the least code outside of my scope (_magnifier module)

Boumtchack · 2025-12-22T16:41:40Z

So the solution I've found was to prevent magnifier to launch if screen curtain is active.
But If I'm in magnifier I can toggle on/off the screen curtain:

if magnifier active:
- Activate ScreenCurtain = stop magnifier
- Deactivate ScreenCurtain = restart magnifier
if Screen Curtain is active:
- Magnifier will ask to stop screen Curtain to start

seanbudd · 2025-12-30T05:05:26Z

I think the behaviour with screen curtain is whatever gets activated should just deactivate the other. However, in settings, we need to make sure both aren't activated at the same time. We should add checks when saving settings to ensure NVDA won't start trying to enable both screen curtain and magnifier. When enabling each, check if the other is active, and if so, disable it.

seanbudd · 2025-12-30T05:20:47Z

Actually I think the behaviour with screen curtain as you've designed is fine for now. It ensures the person intentionally wants to deactivate screen curtain.

seanbudd

Thanks @Boumtchack, the docs here are really good. I've reviewed everything except the tests

.pre-commit-config.yaml

source/_magnifier/__init__.py

source/_magnifier/commands.py

source/_magnifier/config.py

source/_magnifier/magnifier.py

source/_magnifier/fullscreenMagnifier.py

seanbudd · 2025-12-30T06:56:17Z

.pre-commit-config.yaml

+# - repo: https://github.com/DavidAnson/markdownlint-cli2
+#   rev: v0.18.1
+#   hooks:
+#   - id: markdownlint-cli2
+#     name: Lint markdown files
+#     args: ["--fix"]


Suggested change

# - repo: https://github.com/DavidAnson/markdownlint-cli2

# rev: v0.18.1

# hooks:

# - id: markdownlint-cli2

# name: Lint markdown files

# args: ["--fix"]

- repo: https://github.com/DavidAnson/markdownlint-cli2

rev: v0.18.1

hooks:

- id: markdownlint-cli2

name: Lint markdown files

args: ["--fix"]

Please apply this change

CyrilleB79 · 2025-12-30T23:16:34Z

I think the behaviour with screen curtain is whatever gets activated should just deactivate the other.

Why? I have tried to describe a valid use case in #19228 (comment), where screen curtain would be enabled for a short time while Magnifier is already active.

Note that I have not tested last devs of @Boumtchack against that use case.
Also, if I remember well, only the color filter usage conflicts with screen curtain, not all the Magnifier API; at least that is the case with Windows Magnifier.

seanbudd · 2025-12-31T00:57:48Z

@CyrilleB79 - did you miss my follow up message #19228 (comment)

Actually I think the behaviour with screen curtain as you've designed is fine for now. It ensures the person intentionally wants to deactivate screen curtain.

CyrilleB79 · 2025-12-31T11:18:25Z

@CyrilleB79 - did you miss my follow up message #19228 (comment)

Actually I think the behaviour with screen curtain as you've designed is fine for now. It ensures the person intentionally wants to deactivate screen curtain.

Oh sorry, OK. From my quick reading of the description it sounds fine.
I'll come back after tests if needed.

source/winAPI/_displayTracking.py

source/_magnifier/magnifier.py

seanbudd · 2026-01-06T03:40:08Z

source/_magnifier/config.py

+
+		return [i * cls.STEP_FACTOR for i in range(start, end + 1)]
+
+	@classmethod


This suggestion was not applied #19228 (comment)

user_docs/en/userGuide.md

seanbudd · 2026-01-06T03:43:38Z

.pre-commit-config.yaml

+# - repo: https://github.com/DavidAnson/markdownlint-cli2
+#   rev: v0.18.1
+#   hooks:
+#   - id: markdownlint-cli2
+#     name: Lint markdown files
+#     args: ["--fix"]


Please apply this change

tests/unit/test_magnifier/test_magnifier.py

source/_magnifier/magnifier.py

tests/unit/test_magnifier/test_magnifier.py

seanbudd · 2026-01-06T04:00:07Z

tests/unit/test_magnifier/test_fullscreenMagnifier.py

@@ -0,0 +1,458 @@
+# A part of NonVisual Desktop Access (NVDA)


Do these tests actually invoke magnification on your machine? i.e. will the screen magnification change while running tests? We may need to isolate them if that's the case, as running unit tests shouldn't effect the state of a users machine.

Boumtchack added 13 commits October 6, 2025 16:38

first integration of the NVDAMagnifier

8d57e89

changed color filter logic start, strongly typed all code

13a63c7

removed some useless functions, cleaned for readablility

2108d02

color filter working on all type of magnifier

aabd1da

optimisation of the color filter, wip

ad40ec7

Gobal class NVDAMagnifier added to the logic

84b05f1

some clean up

0cb147a

added some unit test, work in progress

402f68f

all magnifier tests, first draft

a2b08cb

linting previous modifications

91e93cd

all first unittest done

c1f15b5

Added a class for the spolight and tests with that

ad1ea7f

first draft of magnifier, simple with only fullscreen

a4afc44

Boumtchack mentioned this pull request Nov 17, 2025

Magnifier integration #19172

Closed

8 tasks

seanbudd changed the title ~~Nvda magnifier implementation~~ Magnifier implementation Nov 18, 2025

Boumtchack added 2 commits November 18, 2025 11:59

resolved bug where magnifier could only launch once

319a71d

added setting and logic to make it persistent

7b3ee4f

Boumtchack force-pushed the NvdaMagnifierImplementation branch from f5a86b5 to 7b3ee4f Compare November 24, 2025 10:10

Boumtchack and others added 12 commits November 24, 2025 14:54

Merge branch 'master' into NvdaMagnifierImplementation

9a4b9ad

Added filter with setting and default values persisting

12e1fc6

Added mode for fullscreen, added button to settings for saving change…

71df447

…s or not

Merge branch 'nvaccess:master' into NvdaMagnifierImplementation

57b1a03

forgot to add the option of persistence to zoom

a908020

Merge branch 'nvaccess:master' into NvdaMagnifierImplementation

0d72e7d

fixed shortcut changes option due to string being alawys true

740c2a9

integrating spotlight, needs some rework

6828b3e

changed the test to latest verion, updated spotlight, lint

6c724de

spotlight zoomback on focus instead of mouse, minor typo

6981c3e

added an option to keep mouse in the center of the screen while movin…

3d757db

…g with nvda

Merge branch 'nvaccess:master' into NvdaMagnifierImplementation

e71bc01

Boumtchack added 2 commits December 17, 2025 17:21

last changes from reviews

c0907c9

uncomented pre-commit config

cd431eb

Boumtchack added 2 commits December 18, 2025 15:19

spotlight moved to utils

63eb140

display tracking

845abf6

Boumtchack added 2 commits December 19, 2025 14:39

screen curtain and magnifier can't be launched together

8bac7ad

user doc

042b87d

ScreenCurtain + Magnifier

d683a15

seanbudd reviewed Dec 30, 2025

View reviewed changes

Boumtchack and others added 3 commits January 5, 2026 17:15

github modifications

4d0b88f

fixes

e144ae3

Merge branch 'nvaccess:master' into NvdaMagnifierImplementation

46f1dd3

seanbudd marked this pull request as ready for review January 6, 2026 03:06

seanbudd requested a review from a team as a code owner January 6, 2026 03:06

seanbudd requested a review from Qchristensen January 6, 2026 03:06

seanbudd reviewed Jan 6, 2026

View reviewed changes

revert pre-commit-config

b9ddd3f


		return [i * cls.STEP_FACTOR for i in range(start, end + 1)]

		@classmethod

		@@ -0,0 +1,458 @@
		# A part of NonVisual Desktop Access (NVDA)

Uh oh!

Magnifier implementation #19228

Are you sure you want to change the base?

Magnifier implementation #19228

Conversation

Boumtchack commented Nov 17, 2025 • edited by seanbudd Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to issue number:

Summary of the issue:

Description of user facing changes:

Description of developer facing changes:

Description of development approach:

Testing strategy:

Known issues with pull request:

Code Review Checklist:

Uh oh!

Boumtchack commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CyrilleB79 commented Dec 17, 2025

Screen curtain conflict

Documentation

Logging

Uh oh!

Boumtchack commented Dec 18, 2025

Uh oh!

CyrilleB79 commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Boumtchack commented Dec 19, 2025

Uh oh!

Boumtchack commented Dec 19, 2025

Uh oh!

Boumtchack commented Dec 22, 2025

Uh oh!

seanbudd commented Dec 30, 2025

Uh oh!

seanbudd commented Dec 30, 2025

Uh oh!

seanbudd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanbudd Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seanbudd Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

CyrilleB79 commented Dec 30, 2025

Uh oh!

seanbudd commented Dec 31, 2025

Uh oh!

CyrilleB79 commented Dec 31, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanbudd Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanbudd Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Boumtchack commented Nov 17, 2025 •

edited by seanbudd

Loading

Boumtchack commented Dec 17, 2025 •

edited

Loading

CyrilleB79 commented Dec 18, 2025 •

edited

Loading

seanbudd Dec 30, 2025 •

edited

Loading