Report background and highlighted text in MS Word (#14610)

Fixes #5866, fixes #7396, fixes #12101

Summary of the issue:
In these years, Microsoft Word users working without UIA had no feedback about background and highlighting colors, often used by colleagues, teachers and students.

UIA has provided a partial solution when available, but its support for these features is far from perfect (see later).

Description of user facing changes
Assuming UIA is not available/forcibly enabled:

when color reporting is enabled in formatting preferences, users will hear background colors too;
when marked/highlighted text reporting is enabled in formatting preferences, users will hear highlighting colors ("highlighted in {color}" and "no highlighting"), regardless of color reporting.
Description of development approach
It was very difficult to find a way, so I'll add some details.

Initially, I used VBA objects approach, querying Paragraph.Shading.BackgroundPatternColor and Range.HighlightColorIndex over a winwordDocument.Range to calculate each time, so it was very slow.

Then I found this document and, after having understood what I needed and how to find the required wdDISPID_ constants, I was able to move all work on the C++ component of nvdaHelperRemote related to winword, that appears very much faster.

In window/winword.py, to take advantage of winwordColorToNVDAColor work, I added also a dict that collects indexes from wdColorIndex and decimal values from wdColor.

About speech, I had to introduce a new format field, highlight-color.

Now, UIA: sure, it already covers background and highlight colors, but expose them as the same attribute, via UIA_BackgroundColorAttributeId (and no, I asked, even visually they are distinct). There is an AnnotationType_Highlighted identifier, but it seems to not be used in this scenario.

Locally I have a possible workaround, based on the fact that, as you see in Word Home menu, highlighting color is applied to characters, background color to paragraphs; so, if textRange has a background-color, I compare it to that retrieved from paragraph and, if I receive IUnknown/MixedAttributeValue, I assume the initial one is an highlighting color and try to get the real background color from "\r" EOL.

But I'm not totally convinced, so I not included it in this PR for now.

Author: ABuffEr

nvdaHelper/remote/WinWord/Constants.h

@@ -213,3 +213,8 @@ constexpr int wdDISPID_INLINESHAPE_CHART = 149;
 constexpr int wdDISPID_CHART_CHARTTITLE = 1610743811;
 constexpr int wdDISPID_CHART_HASTITLE = 1610743809;
 constexpr int wdDISPID_CHARTTITLE_TEXT = 1610743820;
+
+// constants for colors
+constexpr int wdDISPID_PARAGRAPHFORMAT_SHADING = 1101;
+constexpr int wdDISPID_SHADING_BACKGROUNDPATTERNCOLOR = 5;
+constexpr int wdDISPID_RANGE_HIGHLIGHTCOLORINDEX = 301;

nvdaHelper/remote/winword.cpp

@@ -52,6 +52,7 @@ constexpr int formatConfig_includeLayoutTables = 0x20000;
 constexpr int formatConfig_reportLineSpacing = 0x40000;
 constexpr int formatConfig_reportSuperscriptsAndSubscripts = 0x80000;
 constexpr int formatConfig_reportGraphics = 0x100000;
+constexpr int formatConfig_reportHighlightColor = 0x200000;
 
 constexpr int formatConfig_fontFlags =(formatConfig_reportFontName|formatConfig_reportFontSize|formatConfig_reportFontAttributes|formatConfig_reportColor|formatConfig_reportSuperscriptsAndSubscripts);
 constexpr int formatConfig_initialFormatFlags =(formatConfig_reportPage|formatConfig_reportLineNumber|formatConfig_reportTables|formatConfig_reportHeadings|formatConfig_includeLayoutTables);
@@ -525,9 +526,28 @@ void generateXMLAttribsForFormatting(IDispatch* pDispatchRange, int startOffset,
 	if((formatConfig&formatConfig_reportLineNumber)&&(_com_dispatch_raw_method(pDispatchRange,wdDISPID_RANGE_INFORMATION,DISPATCH_PROPERTYGET,VT_I4,&iVal,L"\x0003",wdFirstCharacterLineNumber)==S_OK)) {
 		formatAttribsStream<<L"line-number=\""<<iVal<<L"\" ";
 	}
-	if((formatConfig&formatConfig_reportAlignment)||(formatConfig&formatConfig_reportParagraphIndentation)||(formatConfig&formatConfig_reportLineSpacing)) {
+	if (
+		(formatConfig & formatConfig_reportColor)
+		|| (formatConfig & formatConfig_reportAlignment)
+		|| (formatConfig & formatConfig_reportParagraphIndentation)
+		|| (formatConfig & formatConfig_reportLineSpacing)
+	) {
 		IDispatchPtr pDispatchParagraphFormat=NULL;
 		if(_com_dispatch_raw_propget(pDispatchRange,wdDISPID_RANGE_PARAGRAPHFORMAT,VT_DISPATCH,&pDispatchParagraphFormat)==S_OK&&pDispatchParagraphFormat) {
+			if (formatConfig & formatConfig_reportColor) {
+				IDispatchPtr pDispatchParagraphFormatShading = NULL;
+				if (
+					_com_dispatch_raw_propget(pDispatchParagraphFormat, wdDISPID_PARAGRAPHFORMAT_SHADING, VT_DISPATCH, &pDispatchParagraphFormatShading) == S_OK
+					&& pDispatchParagraphFormatShading
+				) {
+					int bgColor = 0;
+					if (
+						_com_dispatch_raw_propget(pDispatchParagraphFormatShading, wdDISPID_SHADING_BACKGROUNDPATTERNCOLOR, VT_I4, &bgColor) == S_OK
+					) {
+						formatAttribsStream << L"background-color=\"" << bgColor << L"\" ";
+					}
+				}
+			}
 			if(formatConfig&formatConfig_reportAlignment) {
 				if(_com_dispatch_raw_propget(pDispatchParagraphFormat,wdDISPID_PARAGRAPHFORMAT_ALIGNMENT,VT_I4,&iVal)==S_OK) {
 					switch(iVal) {
@@ -654,6 +674,14 @@ void generateXMLAttribsForFormatting(IDispatch* pDispatchRange, int startOffset,
 			}
 		}
 	}
+	int hlColorIndex = 0;
+	if (
+		(formatConfig & formatConfig_reportHighlightColor)
+		&& (_com_dispatch_raw_propget(pDispatchRange, wdDISPID_RANGE_HIGHLIGHTCOLORINDEX, VT_I4, &hlColorIndex) == S_OK)
+		&& (hlColorIndex > 0)
+	) {
+		formatAttribsStream << L"highlight-color-index=\"" << hlColorIndex << L"\" ";
+	}
 	if (formatConfig&formatConfig_reportLanguage) {
 		int languageId = 0;
 		if (_com_dispatch_raw_propget(pDispatchRange,	wdDISPID_RANGE_LANGUAGEID, VT_I4, &languageId)==S_OK) {

source/NVDAObjects/window/winword.py

@@ -41,6 +41,7 @@
 from ..behaviors import EditableTextWithoutAutoSelectDetection
 from . import _msOfficeChart
 import locationHelper
+from enum import IntEnum
 
 #Word constants
 
@@ -219,6 +220,56 @@
 	wdThemeColorText2:msoThemeDark2,
 }
 
+
+# document useful values from:
+# https://learn.microsoft.com/en-us/office/vba/api/word.wdcolorindex
+class WinWordColorIndex(IntEnum):
+
+	wdBlack = 1
+	wdBlue = 2
+	wdBrightGreen = 4
+	wdDarkBlue = 9
+	wdDarkRed = 13
+	wdDarkYellow = 14
+	wdGray25 = 16
+	wdGray50 = 15
+	wdGreen = 11
+	wdPink = 5
+	wdRed = 6
+	wdTeal = 10
+	wdTurquoise = 3
+	wdViolet = 12
+	wdWhite = 8
+	wdYellow = 7
+
+
+# document useful values from:
+# https://learn.microsoft.com/en-us/office/vba/api/word.wdcolor
+class WinWordColor(IntEnum):
+
+	wdBlack = 0
+	wdBlue = 16711680
+	wdBrightGreen = 65280
+	wdDarkBlue = 8388608
+	wdDarkRed = 128
+	wdDarkYellow = 32896
+	wdGray25 = 12632256
+	wdGray50 = 8421504
+	wdGreen = 32768
+	wdPink = 16711935
+	wdRed = 255
+	wdTeal = 8421376
+	wdTurquoise = 16776960
+	wdViolet = 8388736
+	wdWhite = 16777215
+	wdYellow = 65535
+
+
+# map (highlighting) color index to color decimal value
+_colorIndexToColor: Dict[WinWordColorIndex, WinWordColor] = {
+	colorIndex.value: WinWordColor[colorIndex.name].value for colorIndex in WinWordColorIndex
+}
+
 wdRevisionTypeLabels={
 	# Translators: a Microsoft Word revision type (inserted content) 
 	wdRevisionInsert:_("insertion"),
@@ -327,6 +378,7 @@
 	"reportLineSpacing": 0x40000,
 	"reportSuperscriptsAndSubscripts": 0x80000,
 	"reportGraphics": 0x100000,
+	"reportHighlight": 0x200000,
 }
 formatConfigFlag_includeLayoutTables = 0x20000
 
@@ -876,6 +928,20 @@ def _normalizeFormatField(self,field,extraDetail=False):
 		color=field.pop('color',None)
 		if color is not None:
 			field['color']=self.obj.winwordColorToNVDAColor(int(color))
+		bgColor = field.pop('background-color', None)
+		if bgColor is not None:
+			field['background-color'] = self.obj.winwordColorToNVDAColor(int(bgColor))
+		hlColorIndex = field.pop('highlight-color-index', None)
+		if hlColorIndex is not None:
+			hlColor = None
+			try:
+				val = _colorIndexToColor[int(hlColorIndex)]
+				hlColor = self.obj.winwordColorToNVDAColor(val)
+			except (KeyError, ValueError):
+				log.debugWarning("highlight color error", exc_info=True)
+				pass
+			if hlColor is not None:
+				field['highlight-color'] = hlColor
 		try:
 			languageId = int(field.pop('wdLanguageId',0))
 			if languageId:

source/speech/speech.py

@@ -2442,6 +2442,17 @@ def getFormatFieldSpeech(  # noqa: C901
 				# Translators: Reported when text is no longer marked
 				else _("not marked"))
 			textList.append(text)
+		# color-highlighted text in Word
+		hlColor = attrs.get("highlight-color")
+		oldHlColor = attrsCache.get("highlight-color") if attrsCache is not None else None
+		if (hlColor or oldHlColor is not None) and hlColor != oldHlColor:
+			colorName = hlColor.name if isinstance(hlColor, colors.RGB) else hlColor
+			text = (
+				# Translators: Reported when text is color-highlighted
+				_("highlighted in {color}").format(color=colorName) if hlColor
+				# Translators: Reported when text is no longer marked
+				else _("not highlighted"))
+			textList.append(text)
 	if formatConfig["reportEmphasis"]:
 		# strong text
 		strong=attrs.get("strong")

user_docs/en/changes.t2t

@@ -14,6 +14,8 @@ What's New in NVDA
 - In Mozilla Firefox and Google Chrome, NVDA now reports when a control opens a dialog, grid, list or tree if the author has specified this using aria-haspopup. (#14709)
 - It is now possible to use system variables (such as ``%temp%`` or ``%homepath%``) in the path specification while creating portable copies of NVDA. (#14680)
 - Added support for the ``aria-brailleroledescription`` ARIA 1.3 attribute, allowing web authors to override the type of an element shown on the Braille display. (#14748)
+- When highlighted text is enabled Document Formatting, highlight colours are now reported in Microsoft Word. (#7396, #12101, #5866)
+- When colors are enabled Document Formatting, background colours are now reported in Microsoft Word. (#5866)
 - 
 
 
@@ -70,6 +72,7 @@ If not provided, the default thread is used. (#14627)
 - ``hwIo.ioThread.IoThread`` now has a ``setWaitableTimer`` method to set a waitable timer using a python function.
 Similarly, the new ``getCompletionRoutine`` method allows you to convert a python method into a completion routine safely. (#14627)
 - ``offsets.OffsetsTextInfo._get_boundingRects`` should now always return ``List[locationHelper.rectLTWH]`` as expected for a subclass of ``textInfos.TextInfo``. (#12424)
+- ``highlight-color`` is now a format field attribute. (#14610)
 -
 
 === Deprecations ===