Support the Modern Comments side track pane in MS Word when not accessing MS Word documents via UIA (#12988)

michaelDCurran · web-flow · commit bfbe2bf271f7 · 2021-10-27T21:56:33.000+10:00
Fixes #12982 Summary of the issue: In build 13901, MS Word introduced "Modern comments" which allows comment threads (I.e. an initial comment plus replies) and the ability to resolve or reopen threads. The new UI to do this is exposed as a new comments side pane which shows the comments and replies in a treeview. This UI is only exposed via UI Automation. This UI is supposed to completely replace the older Comments story in a document. As this new UI is imbedded within the document, it shares the same window handle. If NvDA is using the object model to access the document (I.e. the UIA provider of the document's window is ignored) then NVDA never sees the modern comments UI at all. It seems that MS Word does not ever proxy this to MSAA either. Also, if MS Word detects that something is trying to access the comments via the object model in the old way (E.g. calls comment.range) then the Modern comments UI is disabled (hidden) and MS Word ends up in a state where querying the range at the selection of the object model is no longer in the comments story, yet the UI is not shown either. This MS Word bug is known to Microsoft however they have no plans or willingness to fix it. Their only recommended solution is to stop using the object model and just use UIA. Description of how this pull request fixes the issue: in UIAHandler.handler.isUIAElement: return true if the element's windowHandle is _WwG but an ancestor of the element has a UIA className of NetUIHWNDElement. I.e. this UIA element is a control of a NetUI container embedded in an MS Word document. E.g. a control in the Modern Comments side track pane. Also, if there is a UIA focus event for the Word document root, even though we are not classing that window as native UIA, if the previously focused object was a control in a NetUI container embedded in the same Word document, then generate an MSAA focus event for the document, as MS Word will not do this itself. Note that allowing NVDA to track the focus with UIA for these embedded controls is enough to work around the issue, as this then means that focus never hits the Word document while the Comments side track pane should be focused, thus avoids making object model calls MS Word does not like or expect.
diff --git a/source/_UIAHandler.py b/source/_UIAHandler.py
@@ -25,6 +25,7 @@
 
 import threading
 import time
+import IAccessibleHandler.internalWinEventHandler
 import config
 import api
 import appModuleHandler
@@ -44,6 +45,10 @@
 import aria
 
 
+#: The window class name for Microsoft Word documents.
+# Microsoft Word's UI Automation implementation
+# also exposes this value as the document UIA element's classname property.
+MS_WORD_DOCUMENT_WINDOW_CLASS = "_WwG"
 
 HorizontalTextAlignment_Left=0
 HorizontalTextAlignment_Centered=1
@@ -533,6 +538,15 @@ def IUIAutomationFocusChangedEventHandler_HandleFocusChangedEvent(self,sender):
 			return
 		self.lastFocusedUIAElement = sender
 		if not self.isNativeUIAElement(sender):
+			# #12982: This element may be the root of an MS Word document
+			# for which we may be refusing to use UIA as its implementation may be incomplete.
+			# However, there are some controls embedded in the MS Word document window
+			# such as the Modern comments side track pane
+			# for which we do have to use UIA.
+			# But, if focus jumps from one of these controls back to the document (E.g. the user presses escape),
+			# we receive no MSAA focus event, only a UIA focus event.
+			# As we are not treating the Word doc as UIA, we need to manually fire an MSAA focus event on the document.
+			self._emitMSAAFocusForWordDocIfNecessary(sender)
 			if _isDebug():
 				log.debug("HandleFocusChangedEvent: Ignoring for non native element")
 			return
@@ -758,7 +772,7 @@ def _isUIAWindowHelper(self,hwnd):
 			canUseOlderInProcessApproach = bool(appModule.helperLocalBindingHandle)
 			if (
 				# An MS Word document window 
-				windowClass=="_WwG" 
+				windowClass == MS_WORD_DOCUMENT_WINDOW_CLASS
 				# Disabling is only useful if we can inject in-process (and use our older code)
 				and canUseOlderInProcessApproach
 				# Allow the user to explicitly force UIA support for MS Word documents
@@ -838,6 +852,55 @@ def getNearestWindowHandle(self,UIAElement):
 		UIAElement._nearestWindowHandle=window
 		return window
 
+	def _isNetUIEmbeddedInWordDoc(self, element: UIA.IUIAutomationElement) -> bool:
+		"""
+		Detects if the given UIA element represents a control in a NetUI container
+		embedded within a MS Word document window.
+		E.g. the Modern Comments side track pane.
+		This method also caches the answer on the element itself
+		to both speed up checking later and to allow checking on an already dead element
+		E.g. a previous focus.
+		"""
+		if getattr(element, '_isNetUIEmbeddedInWordDoc', False):
+			return True
+		windowHandle = self.getNearestWindowHandle(element)
+		if winUser.getClassName(windowHandle) != MS_WORD_DOCUMENT_WINDOW_CLASS:
+			return False
+		condition = UIAUtils.createUIAMultiPropertyCondition(
+			{UIA.UIA_ClassNamePropertyId: 'NetUIHWNDElement'},
+			{UIA.UIA_NativeWindowHandlePropertyId: windowHandle}
+		)
+		walker = self.clientObject.createTreeWalker(condition)
+		cacheRequest = self.clientObject.createCacheRequest()
+		cacheRequest.AddProperty(UIA.UIA_ClassNamePropertyId)
+		cacheRequest.AddProperty(UIA.UIA_NativeWindowHandlePropertyId)
+		ancestor = walker.NormalizeElementBuildCache(element, cacheRequest)
+		# ancestor will either be the embedded NetUIElement, or just hit the root of the MS Word document window
+		if ancestor.CachedClassName != 'NetUIHWNDElement':
+			return False
+		element._isNetUIEmbeddedInWordDoc = True
+		return True
+
+	def _emitMSAAFocusForWordDocIfNecessary(self, element: UIA.IUIAutomationElement) -> None:
+		"""
+		Fires an MSAA focus event on the given UIA element
+		if the element is the root of a Word document,
+		and the focus was previously in a NetUI container embedded in this Word document.
+		"""
+		import NVDAObjects.UIA
+		oldFocus = eventHandler.lastQueuedFocusObject
+		if (
+			isinstance(oldFocus, NVDAObjects.UIA.UIA)
+			and getattr(oldFocus.UIAElement, '_isNetUIEmbeddedInWordDoc', False)
+			and element.CachedClassName == MS_WORD_DOCUMENT_WINDOW_CLASS
+			and element.CachedControlType == UIA.UIA_DocumentControlTypeId
+			and self.getNearestWindowHandle(element) == oldFocus.windowHandle
+			and not self.isUIAWindow(oldFocus.windowHandle)
+		):
+			IAccessibleHandler.internalWinEventHandler.winEventLimiter.addEvent(
+				winUser.EVENT_OBJECT_FOCUS, oldFocus.windowHandle, winUser.OBJID_CLIENT, 0, oldFocus.windowThreadID
+			)
+
 	def isNativeUIAElement(self,UIAElement):
 		#Due to issues dealing with UIA elements coming from the same process, we do not class these UIA elements as usable.
 		#It seems to be safe enough to retreave the cached processID, but using tree walkers or fetching other properties causes a freeze.
@@ -852,6 +915,14 @@ def isNativeUIAElement(self,UIAElement):
 		if windowHandle:
 			if self.isUIAWindow(windowHandle):
 				return True
+			# #12982: although NVDA by default may not treat this element's window as native UIA,
+			# E.g. it is proxied from MSAA, or NVDA has specifically black listed it,
+			# It may be an element from a NetUIcontainer embedded in a Word document,
+			# such as the MS Word Modern Comments side track pane.
+			# These elements are only exposed via UIA, and not MSAA,
+			# thus we must treat these elements as native UIA.
+			if self._isNetUIEmbeddedInWordDoc(UIAElement):
+				return True
 			if winUser.getClassName(windowHandle)=="DirectUIHWND" and "IEFRAME.dll" in UIAElement.cachedProviderDescription and UIAElement.currentClassName in ("DownloadBox", "accessiblebutton", "DUIToolbarButton", "PushButton"):
 				# This is the IE 9 downloads list.
 				# #3354: UiaHasServerSideProvider returns false for the IE 9 downloads list window,
diff --git a/user_docs/en/changes.t2t b/user_docs/en/changes.t2t
@@ -73,6 +73,7 @@ If you need this functionality please assign a gesture to the appropriate script
 - Fixed duplicate braille and speech when 'description' matches 'content' or 'name'. (#12888)
 - In MS Word with UIA enabled, more accurate playing of spelling error sounds as you type. (#12161)
 - In Windows 11, NVDA will no longer announce "pane" when pressing Alt+Tab to switch between programs. (#12648)
+- The new Modern Comments side track pane is now supported in MS Word when not accessing the document via UIA. Press alt+f12 to move between the side track pane and the document. (#12982)
 -
 
 

Original file line number	Diff line number	Diff line change
`@@ -73,6 +73,7 @@ If you need this functionality please assign a gesture to the appropriate script`
`73`	`73`	`- Fixed duplicate braille and speech when 'description' matches 'content' or 'name'. (#12888)`
`74`	`74`	`- In MS Word with UIA enabled, more accurate playing of spelling error sounds as you type. (#12161)`
`75`	`75`	`- In Windows 11, NVDA will no longer announce "pane" when pressing Alt+Tab to switch between programs. (#12648)`
	`76`	`+- The new Modern Comments side track pane is now supported in MS Word when not accessing the document via UIA. Press alt+f12 to move between the side track pane and the document. (#12982)`
`76`	`77`	`-`
`77`	`78`
`78`	`79`