MS Word documents: report when headings are collapsed in both speech and braille.

[michaelDCurran]

Link to issue number:

None.

Summary of the issue:

In Microsoft Word, it is possible to collapse a heading, so that all the paragraphs directly following the heading are hidden. As of MS Word 16.0.18226, a new UIA text range custom attribute was added, to convey the expand collapse state of headings. NVDA should report when a heading is collapsed based on this value.

Description of user facing changes

In Microsoft Word, If a heading is collapsed, NVDA will now report this in speech and braille.

Description of development approach

• When fetching format information for a text range in MS Word via UIA, if the range supports the expand collapse custom attribute, expose the 'collapsed' key on its format field, setting it to true for collapsed, and false for expanded.
• speech.getFormatfieldSpeech: speak "collapsed" when moving by line or paragraph over text with 'collapsed' set to true in its format field, or if it changes to true when moving by word / character.
• In Braille, Report a plus (+) sign at the start of text that is collapsed according to its format field.

Testing strategy:

Tested with MS Word 16.0.18331.

• Open a new document in Microsoft word.
• Type an initial line of text.
• Type a second line of text and format it as a heading (press alt+shift+rightArrow)
• Type another line of text directly below it formatted as a normal paragraph.
• Arrow up to the heading, noting that the heading is spoken / braille dnormally (I.e. heading level 2 test). No expand / collapse info is reported.
• Collapse the heading by choosing collapse in the context menu.
• Arrow up and back down to read the heading. Note that NvDA now reports 'collapsed' in speech and a plus (+) sign in braille.

Known issues with pull request:

None known.

This implementation only reports when a heading is collapsed, and not explicitly when expanded. However, as expanded headings will far outweigh collapsed, I think it would be way too noisy to report expanded, when that is going to be the norm.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

@coderabbitai summary

[CyrilleB79]

For the feature to be complete, the following could be added to this PR:

1. There are still many people using legacy Word object model instead of UIA. When possible, it would be nice to have features developed for both interfaces at the same time. In the specific case, you can use Paragraph.CollapsedState property.

2. There are shortcuts to collapse or expand headings. My Word is in French, but according to ChatGPT, on English Word, it is alt+shift+plus or alt+shift+-. Could you implement feedback reporting of these actions? If it is already reported automatically in newer Word versions (I have not tested myself), ignore this request of course.

If you prefer have this development merged as is, at least, document these missing points in "Known issues" sections and open new issues to track these missing points. Thanks.

[CyrilleB79]

I get the following error with an older Word version:
UnboundLocalError: cannot access local variable 'docElement' where it is not associated with a value

You should indent this code to execute it in the "if" branch where docElement is defined.

Suggested change

	expandCollapseState = UIARemote.msWord_getCustomAttributeValue(
	docElement,
	textRange,
	UIACustomAttributeID.EXPAND_COLLAPSE_STATE,
	)
	if expandCollapseState == EXPAND_COLLAPSE_STATE.COLLAPSED:
	formatField.field["collapsed"] = True
	elif expandCollapseState == EXPAND_COLLAPSE_STATE.EXPANDED:
	formatField.field["collapsed"] = False
	expandCollapseState = UIARemote.msWord_getCustomAttributeValue(
	docElement,
	textRange,
	UIACustomAttributeID.EXPAND_COLLAPSE_STATE,
	)
	if expandCollapseState == EXPAND_COLLAPSE_STATE.COLLAPSED:
	formatField.field["collapsed"] = True
	elif expandCollapseState == EXPAND_COLLAPSE_STATE.EXPANDED:
	formatField.field["collapsed"] = False

[michaelDCurran]

@CyrilleB79 I have addressed the docElement issue pre Windows 11, and also exposed collapsed for headings in Word with the object model.
Re shortcuts: you are welcome to open issues for these if you like, but it is out of scope for this particular PR.

[SaschaCowley]

Why does this need to be assigned to a variable?

Suggested change

	collapsed = field.get("collapsed")
	if collapsed:
	if field.get("collapsed"):

[SaschaCowley]

Is the version of Word applicable now that this has been added to the object model too?

[CyrilleB79]

I have just tested this PR, launching the installer (nvda_snapshot_pr17499-34747,bb1e29a1.exe) and running the temporary version.

• With UIA always, the feature is not working; maybe it is expected on Windows 10?
• With Word Object Model (UIA Only when necessary), Word crashes.

I am with:

• Microsoft® Word 2016 MSO (Version 2410 Build 16.0.18129.20158) 32 bits
• Windows 10 2004 (AMD64) build 19041.388; note that this is not the last version (I cannot test on last Win 10); may it be the cause of the crash?

[codeofdusk]

@CyrilleB79 This is expected because Windows 10 doesn't have remote ops support in UIA core.

[michaelDCurran]

I can't reproduce the crash. I'll need a crash dump if you can get one. However, if this is hard to get / or we can not trace the reason, then I'll need to remove the object model support for reporting collapsed from this PR, as I cannot hold back the UIA part (which works fine on win11) - it is a request from Microsoft.

[CyrilleB79]

I have not been able to get a crash dump for Word. I have tried both methods described in NVDA wiki:

• paragraph Minidumps for Other Applications
• paragraph Alternative Way to Get Minidumps for Other Applications, actually following MSDN article

In both cases, I cannot get any dumpfile. I have also tried to force a dumpfile, killing winword process from task manager without success, so I am probably doing something wrong when trying to get the dumpfile.

Word crashes, actually disappears, when arrowing in text heading formatted, or when trying to use expand / collapse commands. When I move the caret in normal (body) text, there is no problem.

It would be nice to be able to fix this. @Adriani90 would you be able to reproduce the crash described here with object model (legacy, i.e. "Only when necessary" in advanced settings)?

But if it is not possible to fix the issue with Word Object model, nor reproducible on your side, I understand that you may want to merge the UIA part, what is already an improvement.

[CyrilleB79]

@michaelDCurran, I have found why it crashes on my end and tested that it does not crash anymore with the fix, running from source.

Strange that you have not experimented this crash; maybe you were not really testing Word object model due to 13704?

[michaelDCurran]

I was definitely testing with the object model. Perhaps you are using 32 bit MS Word and I am using 64 bit, or you have tighter execution / memory policies set in Windows? Either way, I'm glad you found the cause.

[CyrilleB79]

I was definitely testing with the object model. Perhaps you are using 32 bit MS Word and I am using 64 bit, or you have tighter execution / memory policies set in Windows? Either way, I'm glad you found the cause.

Yes, I am running Office 2016 32 bits.