UI Automation in Windows Console: make default in FORMATTED consoles …

…(Windows 11 Sun Valley 2) (#10964)

Supersedes #9771 and #10716. Closes #1682. Closes #8653. Closes #9867. Closes #11172. Closes #11554.

Summary of the issue:

Microsoft has significantly improved performance and reliability of UIA console:
* microsoft/terminal#4018 is an almost complete rewrite of the UIA code which makes the console's UIA implementation more closely align with the API specification.
* microsoft/terminal#10886, microsoft/terminal#10925, and microsoft/terminal#11253 form a robust testing methodology for the UIA implementation, including bug fixes in response to newly added tests based on Word's UIA implementation.
* microsoft/terminal#11122 removes the thousands of empty lines at the end of the console buffer, significantly improving performance and stability. Since all console text ranges are now within the text buffer's bounds, it is no longer possible for console to crash due to the manipulation by UIA clients of an out-of-bounds text range.
* Countless other accessibility-related PRs too numerous to list here.

We should enable UIA support on new Windows Console builds by default for performance improvement and controllable password suppression.

Description of how this pull request fixes the issue:

This PR:
* Exposes all three options for the UIA console feature flag in the UI (replaces the UIA check box with a combo box).
* Adds a runtime check to test if `apiLevel >= FORMATTED`, and use UIA in this case when the user preference is auto. This is the case on Windows 11 Sun Valley 2 (SV2) available now in beta and set for release in the second half of 2022.

source/UIAHandler/utils.py

@@ -305,9 +305,7 @@ def _shouldUseUIAConsole(hwnd: int) -> bool:
 	else:
 		# #7497: the UIA implementation in old conhost is incomplete, therefore we
 		# should ignore it.
-		# When the UIA implementation is improved, the below line will be replaced
-		# with a check that _getConhostAPILevel >= FORMATTED.
-		return False
+		return _getConhostAPILevel(hwnd) >= WinConsoleAPILevel.FORMATTED
 
 
 @lru_cache(maxsize=10)

source/gui/settingsDialogs.py

@@ -2688,10 +2688,7 @@ def __init__(self, parent):
 			# Translators: A choice in a combo box in the advanced settings
 			# panel to have NVDA determine its Windows Console implementation
 			# automatically.
-			# This option is currently equivalent to "legacy", but in a future
-			# version of NVDA, UIA will be used in known good implementations
-			# when this option is selected.
-			_("Automatic (legacy)"),
+			_("Automatic (prefer UIA)"),
 			# Translators: A choice in a combo box in the advanced settings
 			# panel to have NVDA use UIA in the Windows Console when available.
 			_("UIA when available"),

user_docs/en/changes.t2t

@@ -6,6 +6,15 @@ What's New in NVDA
 = 2022.3 =
 
 == New Features ==
+- In the Windows Console Host used by Command Prompt, PowerShell, and the Windows Subsystem for Linux on Windows 11 version 22H2 (Sun Valley 2) and later:
+  - Vastly improved performance and stability. (#10964)
+  - When pressing ``ctrl+f`` to find text, the review cursor position is updated to follow the found term. (#11172)
+  - Reporting of typed text that does not appear onscreen (such as passwords) is disabled by default.
+It can be re-enabled in NVDA's advanced settings panel. (#11554)
+  - Text that has scrolled offscreen can be reviewed without scrolling the console window. (#12669)
+  - More detailed text formatting information is available. (microsoft/terminal#10336)
+  -
+-
 
 
 == Changes ==
@@ -19,6 +28,10 @@ What's New in NVDA
 
 
 == Changes for Developers ==
+- In builds of Windows Console (``conhost.exe``) with an NVDA API level of 2 (``FORMATTED``) or greater, such as those included with Windows 11 version 22H2 (Sun Valley 2), UI Automation is now used by default. (#10964)
+  - This can be overridden by changing the "Windows Console support" setting in NVDA's advanced settings panel.
+  -
+-
 
 
 === Deprecations ===

user_docs/en/userGuide.t2t

@@ -1052,10 +1052,11 @@ When in the table view of added books:
 NVDA provides support for the Windows command console used by Command Prompt, PowerShell, and the Windows Subsystem for Linux.
 The console window is of fixed size, typically much smaller than the buffer that holds the output.
 As new text is written, the content scroll upwards and previous text is no longer visible. 
-Text that is not visibly displayed in the window is not accessible with NVDA's text review commands.
+On Windows versions before Windows 11 22H2, text in the console that is not visibly displayed in the window is not accessible with NVDA's text review commands.
 Therefore, it is necessary to scroll the console window to read earlier text.
+In newer versions of the console and in Windows Terminal, it is possible to review the entire text buffer freely without the need to scroll the window.
 %kc:beginInclude
-The following built-in Windows Console keyboard shortcuts may be useful when [reviewing text #ReviewingText] with NVDA:
+The following built-in Windows Console keyboard shortcuts may be useful when [reviewing text #ReviewingText] with NVDA in older versions of Windows Console:
 || Name | Key | Description |
 | Scroll up | control+upArrow | Scrolls the console window up, so earlier text can be read. |
 | Scroll down | control+downArrow | Scrolls the console window down, so later text can be read. |
@@ -1894,11 +1895,10 @@ It does not affect the modern Windows Terminal.
 In Windows 10 version 1709, Microsoft [added support for its UI Automation API to the console https://devblogs.microsoft.com/commandline/whats-new-in-windows-console-in-windows-10-fall-creators-update/], bringing vastly improved performance and stability for screen readers that support it.
 In situations where UI Automation is unavailable or known to result in an inferior user experience, NVDA's legacy console support is available as a fallback.
 The Windows Console support combo box has three options:
-- Automatic: This option is currently equivalent to "legacy".
-However, with this option selected, NVDA will begin using UI Automation in consoles automatically in a future version once it has become stable and suitable for wider use.
-- UIA when available: Uses UI Automation in consoles if available.
-This will include Console versions which have incomplete or buggy UI Automation implementations.
-Though not yet fully stable, UI Automation may provide a superior user experience in some scenarios, especially in the Windows 11 Sun Valley 2 (22H2) update.
+- Automatic: Uses UI Automation in the version of Windows Console included with Windows 11 version 22H2 and later.
+This option is recommended and set by default.
+- UIA when available: Uses UI Automation in consoles if available, even for versions with incomplete or buggy implementations.
+While this limited functionality may be useful (and even sufficient for your usage), use of this option is entirely at your own risk and no support for it will be provided.
 - Legacy: UI Automation in the Windows Console will be completely disabled.
 The legacy fallback will always be used even in situations where UI Automation would provide a superior user experience.
 Therefore, selecting this option is not recommended unless you know what you are doing.