Magnifier implementation

[Boumtchack]

Link to issue number:

Closes #12539

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:

No significant changes.
A new displayChanged extension point under winAPI._displayTracking, which notifies handlers of display configuration changes.

Description of development approach:

• Introduced the main magnifier module with initialization, activation, and shutdown logic in __init__.py, supporting only full-screen magnification for now.
• Added a FullScreenMagnifier class implementing full-screen magnification, handling zoom, color filters, mouse centering, and spotlight mode, interfacing with the Windows Magnification API.
• Implemented keyboard command handlers for toggling the magnifier, zooming, cycling color filters, changing full-screen modes, and starting spotlight mode in commands.py.
• Added a configuration module (config.py) to manage default zoom level, color filter, full-screen mode, and mouse centering settings, with utilities for retrieving and setting these values.

Testing strategy:

unit test

manual testing of all the new features

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.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 23 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[hwf1324]

Does mouse tracking and visual highlight work with this software? particularly at different DPI scaling?

I think this is unrelated; the reason might be that the candidate window is not reporting the correct position information or something similar. When the candidate window appears, the visual highlighter draws a focus rectangle the size of the current window, and the NVDA magnifier centers on this rectangle instead of following the input cursor.

[seanbudd]

@hwf1324 can you open a new issue for that?

[hwf1324]

can you open a new issue for that?

No problem, but I think this should be done after this PR is merged.

[Qchristensen]

Everything looks good, I would like to see a filter keystroke by default though

[Qchristensen]

Everything reads fine, though I do think we should have a filter keystroke by default - it is a common feature of magnification software, but you also often encounter situations where you need to toggle the filter (eg to see a photo in its natural colours).

Perhaps NVDA+shift+i

Even though it's called "filter" rather than "invert", NVDA+shift+f is already used, and also 'i' is a little consistent with Windows magnifier which uses control+alt+i for the same function.

[seanbudd]

@Boumtchack - can you do this in a separate PR? I think nvda+shift+i is fine

shouldnt block

[CyrilleB79]

Congratulations @Boumtchack for this big work being merged! This is very appreciated. And this lays the foundations for many future related developments and improvements. Again, a big thank you to you!