Only restore braille on secure desktop exit, not on ordinary desktop switches

[LeonarddeR]

Link to issue number:

Fixup for #18810

Summary of the issue:

Since #18810, NVDA frees the braille display when switching to the secure desktop and restores it
when returning to a user desktop. However, the restore branch also runs on desktop switches that
never entered the secure desktop. Moving input focus between a Remote Desktop session and the local
machine generates EVENT_SYSTEM_DESKTOPSWITCH in the remote session, so
braille.handler._onSecureDesktopStateChanged is invoked with isSecureDesktop=False even though
the secure desktop was never active. This re-runs braille display detection (or re-sets the
configured display), repeatedly disconnecting and re-detecting a working display. For remote braille
(e.g. RDAccess) each such switch causes a full channel teardown and re-handshake, so braille churns
on every alt+tab / focus change.

Description of user facing changes:

The braille display is no longer briefly disconnected and re-detected on desktop switches that do not
enter the secure desktop, such as switching between a Remote Desktop session and the local machine.

Description of developer facing changes:

None.

Description of development approach:

In BrailleHandler._onSecureDesktopStateChanged, when returning to a user desktop
(isSecureDesktop=False), only restore the display when the current display differs from
_lastRequestedDisplayName. Switching to the secure desktop replaces the display with the
noBraille fallback via setDisplayByName(..., isFallback=True), which deliberately does not update
_lastRequestedDisplayName. So a current display equal to _lastRequestedDisplayName means the
display was never freed (an ordinary desktop switch) and there is nothing to restore. This covers
both automatic detection (where _lastRequestedDisplayName holds the detected driver name) and a
manually configured display (where it equals the configured display). Entering the secure desktop is
unchanged, so the display is still freed there.

Testing strategy:

Manually tested in a Remote Desktop session with a braille display, switching focus between the
session and the local machine (alt+tab / Windows+D): the display is no longer repeatedly
disconnected and re-detected. Verified a genuine secure desktop transition (UAC prompt) still frees
and then restores the display.

Known issues with pull request:

autoScroll and mainBuffer are still cleared at the top of _onSecureDesktopStateChanged on every
reported desktop switch, so an ordinary switch still briefly clears the braille buffer (no reconnect).
This is unchanged behaviour and could be addressed separately.

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.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refines NVDA’s braille secure-desktop handling to avoid unnecessary braille display teardown/re-detection on desktop switches that never entered the Secure Desktop (notably Remote Desktop session focus changes). It adjusts the restore path so it only runs when the current display differs from the last requested display, which is intended to indicate the Secure Desktop fallback was activated.

Changes:

• Guard braille “restore” behavior on isSecureDesktop=False so ordinary desktop switches don’t re-run display selection/detection.
• Add a user-facing changelog entry describing the reduced braille churn on non-secure desktop switches.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
source/braille/brailleHandler.py	Adds an early-return guard to avoid restoring/re-detecting braille on ordinary desktop switches.
user_docs/en/changes.md	Documents the user-visible fix for braille churn on non-secure desktop switches (e.g. Remote Desktop focus changes).