handle conflicts between Windows magnifier and NVDA magnifier

[Boumtchack]

Link to issue number:

fix #20012

Summary of the issue:

When Windows Magnifier was already running, NVDA Magnifier could still start because MagInitialize() succeeds even when the API is held by another process. Only MagSetFullscreenTransform() would fail, triggering the recovery loop — which itself only tested MagInitialize() and MagSetFullscreenColorEffect(), both of which succeed, causing it to falsely declare victory and restart the timer indefinitely.

Description of user facing changes:

NVDA now shows a clear message ("Cannot start magnifier: the magnification API is unavailable. Windows Magnifier may already be running.") when the magnification API cannot be fully initialized at startup. If the conflict occurs after startup, the recovery mechanism is now capped at 3 attempts before stopping the magnifier and notifying the user, preventing log spam.

Description of developer facing changes:

_initializeNativeMagnification() no longer uses @trackNativeMagnifierErrors — it now raises OSError on failure (including a MagSetFullscreenTransform probe that detects the Windows Magnifier conflict). _startMagnifier() catches this error, calls _stopMagnifier() to properly unregister the display change handler, and returns early. _attemptRecovery() reuses _initializeNativeMagnification() to avoid duplicating the probe logic, and is now capped by _MAX_RECOVERY_ATTEMPTS = 3.

Description of development approach:

The fix centers on making _initializeNativeMagnification() a reliable gate: it probes MagSetFullscreenTransform (the actual failing call) as part of initialization and raises on failure rather than silently returning. This single change fixes both the startup path and the recovery path, since _attemptRecovery() can delegate to the same method. A _recoveryAttempts counter (capped at _MAX_RECOVERY_ATTEMPTS) prevents the infinite restart loop when the API remains permanently unavailable.

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.

[CyrilleB79]

@Boumtchack the translators comment check test fails. This one does not fail randomly (as other sometimes do), so it needs to be fixed.

[CyrilleB79]

My bad, the translators comments check test is failing due to cache miss. Unrelated to this PR.

[Boumtchack]

that's weird, I shouldn't be abble to push if my pre-commit fail, I'll look into it

[seanbudd]

Thanks @Boumtchack

[Copilot]

Pull request overview

Addresses conflicts between Windows Magnifier and NVDA’s full-screen magnifier by making Magnification API initialization/recovery reliably detect unusable API states and preventing runaway recovery loops/log spam.

Changes:

• Make _initializeNativeMagnification() validate API usability (including a MagSetFullscreenTransform probe) and raise on failure, with _startMagnifier() handling user notification + cleanup.
• Add recovery attempt tracking and reset logic to avoid repeated error loops.
• Extend unit tests to cover API-conflict startup behavior and recovery scenarios.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
source/_magnifier/fullscreenMagnifier.py	Adds initialization failure handling, API usability probing, and capped recovery attempts.
source/_magnifier/magnifier.py	Introduces _recoveryAttempts state and resets it on successful update cycles.
tests/unit/test_magnifier/test_fullscreenMagnifier.py	Adds tests for API conflict detection and updated recovery expectations.