UIA handler/notification event: handle elements without window handle property set such as window visual state announcements from File Explorer/Windows shell#18229
Merged
SaschaCowley merged 24 commits intoJun 24, 2025
Conversation
…from elements without window handles. Re nvaccess#18220. UIA notification event fails if UIA element has no native window handle. However, some of these elements report system information such as window visual state (restore/maximize/snap) yet do not set native window handle value. Therefore, ask app modules if notifications from these elements should be accepted (notable case: File Explorer/window visual states).
…onEventNoWindowHandle method to determine if notifications should be received from elements without hwnd set. Re nvaccess#18220. Similar to UIA propewrty change event handler: add a method in the base app module to say yes or no if asked to process UIA notification events for elements (senders) without window handle defined. Method signature is same as UIA notification event except arguments other than sender (element) are keyword arguments - not all app modules may wish to work with all UIA notification event arguments. By default, this method will return False for compatibility with previous NVDA behavior of dropping notification events without window handle set.
…as 'widow handle' if native window handle is not set for an element. Re nvaccess#18220. UIA NVDA objects need window handle as part of its construction, including while processing events. However, some elements with important notifications (notably window visual state notifications) do not set native window handle property. Therefore, set foreground window handle as the element's 'window handle' to allow notification event to propagate across handlers (global plugins, app modules, NVDA object).
…from everywhere. Re nvaccess#17841, nvaccess#18175. The element that reports window visual state changes (restore/masimize/minimize/snap) does not define a native window handle property. Therefore, let File Explorer app module say 'yes' when asked to process UIA notification event from this element. Note that this is not the only time a 'no window handle notification' is used - the other case is input layout switch notifications (say, changing between input languages), thus limit processing to snap anouncements.
…ncement (Windows 11 24H2 and Server 2025 and later). Re nvaccess#17841, nvaccess#18175, nvaccess#18220
LeonarddeR
suggested changes
Jun 7, 2025
…NOtificationEventNoWindowHandle -> shouldProcessUIANotificationEvent (generalizability). Re nvaccess#18220, nvaccess#17841. Rename the app module method to make it more generalizable (including handling events from elements with no window handle set).
…ess#18220. Nearest window handle getter from UIA handler can say 'None' if window is not found, and calling bool(None) gives False. Therefore, use the boolean transformation of the nearest window handle call as base implementation for 'shouldProcessUIANotificationEvent' method.
…fic cases when asked to process UIA notification event. Re nvaccess#17841, nvaccess#18220
…dow handle can report notifications only if app modules say so). Re nvaccess#17841, nvaccess#18220
LeonarddeR
reviewed
Jun 9, 2025
…ificationEvent/event_UIA_notification instead of using kwargs dictionary. Re nvaccess#18220. Reviewed by Leonard de Ruijter: spell out argument names for shouldProcessUIANotificationEvent and event_UIA_notification to make the code more readable.
See test results for failed build of commit a3c8d70668 |
CyrilleB79
reviewed
Jun 10, 2025
NOted by Cyrille Bougot: add grave accent (1) to emphasize hotkeys. Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>
See test results for failed build of commit d282f4cfff |
SaschaCowley
requested changes
Jun 13, 2025
SaschaCowley
left a comment
Member
There was a problem hiding this comment.
Note that @michaelDCurran has been requested to review this as well due to my inexperience with UIA
…ment in notification event handler. Re nvaccess#18220. Note from Sascha Cowley (NV ACcess): add type hints please (do this in app modules by importing UIA client from COM interfaces).
…ionEvent' method. Re nvaccess#18220. Note from Sascha Cowley (NV Access): add parameter hints to notification processing event to improve docstring clarity.
… to UIA elements without window handles. Re nvaccess#18220. NOte from reviewers: would it be better to use desktop window handle rather than foreground handle? The issue: some UIA elements do not connect back to the desktop through UIA tree traversal. The foreground window handle makes sense when handling the primary case of window visual state announcement, but there are other places where UIA notification events without window handles (at least from NVDA's perspective) will be seen such as Voice Access (Windows 11). Therefore, switch to using desktop window handle to communicate the need to handle notification events more generically.
michaelDCurran
approved these changes
Jun 17, 2025
michaelDCurran
left a comment
Member
There was a problem hiding this comment.
Approving, at least on the approach.
Contributor
Author
|
Hi, thanks. I think we still need to persuade Microsoft to take UIA tree management more seriously to avoid a situation like this. I’ll introduce Windows 11 Voice Access support within 48 hours of PR merge.
|
SaschaCowley
approved these changes
Jun 24, 2025
# Conflicts: # user_docs/en/changes.md
See test results for failed build of commit 4465872125 |
5 tasks
seanbudd
pushed a commit
that referenced
this pull request
Jun 25, 2025
… NotificationProcessing -> notificationProcessing (argument name consistency) (#18319) Quick follow-up to #18229 Summary of the issue: UIA notification argument names are inconsistent across UIA handler, app modules, and UIA NVDA objects. Description of user facing changes: None Description of developer facing changes: None, as the app module API was just merged. Description of development approach: Change the follwoing argument names in app module version of shouldProcessUIANotificationEvent: NotificationKind -> notificationKind NotificationProcessing -> notificationProcessing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Link to issue number:
Closes #18220
Closes #17841
Summary of the issue:
NVDA does not announce window visual states such as restore and snap when Windows+arrow keys are pressed.
Description of user facing changes:
NVDA will announce window visual states (for the foreground window) when Windows+arrow keys are pressed.
Description of developer facing changes:
Window state notifications are raised by a Windows shell (File Explorer) element without a native window handle. Therefore, allow notifications to be processed if the app module says yes, and if so, use foreground window handle as "window handle" for the element (because UIA NVDA objects require a window handle during construction even though all that will be done is process events).
Description of development approach:
In UIA handler/notification event handler:
Base app module:
File Explorer app module:
Testing strategy:
Manual testing: from any app window (such as a web browser), press Windows+arrw keys to snap windows to part of the screen or press Windows+up arrow to maximize the foreground window.
Prior to this PR: no window state announcement.
After this PR: NVDA will announce window snap notification.
Known issues with pull request:
While the foreground window handle is an obvious choice (as the nanouncemenet pertians to window visual state changes), there might be a better way such as a custom UIA property. Ideally, window handle should be exposed by this shell element and hopefully Microsoft can resolve this. Note that File Explorer is not the only app with this issue - Windows 11 Voice Access exhibits the same problem (#16862).
Code Review Checklist:
@coderabbitai summary