MS Word: The result of Word commands to expand or collapse a heading is now reported

source/appModules/winword.py

@@ -1,7 +1,7 @@
 # A part of NonVisual Desktop Access (NVDA)
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-# Copyright (C) 2019-2024 NV Access Limited, Cyrille Bougot
+# Copyright (C) 2019-2025 NV Access Limited, Cyrille Bougot
 
 """App module for Microsoft Word.
 Word and Outlook share a lot of code and components. This app module gathers the code that is relevant for
@@ -11,10 +11,20 @@
 import appModuleHandler
 from scriptHandler import script
 import ui
+from logHandler import log
 from NVDAObjects.IAccessible.winword import WordDocument as IAccessibleWordDocument
 from NVDAObjects.UIA.wordDocument import WordDocument as UIAWordDocument
 from NVDAObjects.window.winword import WordDocument
 from utils.displayString import DisplayStringIntEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+	import inputCore
+
+
+# From WdOutlineLevel enumeration
+# See https://learn.microsoft.com/fr-fr/office/vba/api/word.wdoutlinelevel
+wdOutlineLevelBodyText = 10
 
 
 class ViewType(DisplayStringIntEnum):
@@ -79,6 +89,48 @@ def script_toggleChangeTracking(self, gesture):
 			# Translators: a message when toggling change tracking in Microsoft word
 			ui.message(_("Change tracking off"))
 
+	@script(
+		gestures=["kb:alt+shift+-", "kb:alt+shift+=", "kb:alt+shift+numpadPlus", "kb:alt+shift+numpadMinus"],
+	)
+	def script_collapseOrExpandHeading(self, gesture: "inputCore.InputGesture") -> None:
+		if not self.WinwordSelectionObject:
+			# We cannot fetch the Word object model, so we therefore cannot report the collapsed state change.
+			# The object model may be unavailable because this is a pure UIA implementation such as Windows 10 Mail,
+			# or it's within Windows Defender Application Guard.
+			# In this case, just let the gesture through and don't report anything.
+			gesture.send()
+			return
+		if self.WinwordWindowObject.view.Type in [ViewType.OUTLINE, ViewType.DRAFT]:
+			# In draft mode, collapsing headings is not available.
+			# In Outline view, paragraph.CollapsedState does not report the correct value.
+			# So do not report anything in these modes
+			gesture.send()
+			return
+		maxParagraphs = 50
+		for nParagraph, paragraph in enumerate(self.WinwordSelectionObject.paragraphs):
+			if paragraph.outlineLevel != wdOutlineLevelBodyText:
+				break
+			if nParagraph >= maxParagraphs:
+				log.debugWarning("Too many paragraphs selected")
+				gesture.send()
+				return
+		else:
+			gesture.send()
+			# Translators: a message when collapsing or expanding headings in MS Word
+			ui.message(_("No heading selected"))
+			return
+		val = self._WaitForValueChangeForAction(
+			lambda: gesture.send(),
+			lambda: paragraph.CollapsedState,
+		)
+		if val:
+			# Translators: a message when collapsing a heading in MS Word
+			msg = _("Collapsed")
+		else:
+			# Translators: a message when expanding a heading in MS Word
+			msg = _("Expanded")
+		ui.message(msg)
+
 	__gestures = {
 		"kb:control+shift+b": "toggleBold",
 		"kb:control+shift+w": "toggleUnderline",

user_docs/en/changes.md

@@ -38,7 +38,9 @@ To use this feature, "allow NVDA to control the volume of other applications" mu
   * It now starts with a more user friendly explanation of its purpose, instead of a warning. (#12351)
   * The initial window can now be exited with `escape` or `alt+f4`. (#10799)
   * It will now show a message to the user, including the error, in the rare event of a Windows error while attempting COM re-registrations.
-* In Word and Outlook the result of more font formatting shortcuts is now reported. (#10271, @CyrilleB79)
+* In Word and Outlook the result of more shortcuts is reported:
+  * font formatting shortcuts (#10271, @CyrilleB79)
+  * Collapse or expand heading (#17545, @CyrilleB79)
 * Default input and output braille tables can now be determined based on the NVDA language. (#17306, #16390, #290, @nvdaes)
 * In Microsoft Word, when using the "report focus" command, the document layout will be announced if this information is available and reporting object descriptions is enabled. (#15088, @nvdaes)
 * NVDA will now only warn about add-on incompatibility when updating to a version which has an incompatible add-on API to the currently installed copy. (#17071, #17506)