Announce when moving outside a table in an Excel spreadsheet with UIA

[michaelDCurran]

Link to issue number:

None

Summary of the issue:

A particular range of an Excel spreadsheet can be formatted as a self-contained table.
When NVDA uses UIA to access Excel, it announces when focus enteres the table, but does not announce when exiting.
The impact is that the user does not know when focus moves onto a cell outside of the table. E.g. when perhaps trying to enter a new row of data at the bottom.

Technically, tables in Excel are exposed in Excel as UIA elements, themselves containing child cells.
NVDA already announces entering tables as NVDA has had a 'focusEntered' event which fires on all new focus ancestors, but does not have the opposite for firing on old ancestors.

Description of user facing changes

NVDA will now announce "out of table" when focus moves from a cell inside a table, to a cell outside of a table or in a different table.
This is not directly reported in Braille however, as the user has always been able to scroll backward from the cell to see if they are in the table or just the worksheet.

This feature has not been added to NVDA's support for Excel when using the object model (not UIA), and there are no plans to further enhance the older object model code in the future.

Description of development approach

api.setFocusObject now fires a new 'focusExited' event on any ancestor of the old focus, that is not common with the new focus. It does this at the very end, after firing loseFocus and actually setting the focus.
This means, focus-related event ordering is as follows:

• event_loseFocus fired on the old focus
• event_focusExited is fired on the old focus's parent (assuming it is not common with the new focus ancestors)
• event_focusExited is fired on the old focus's parent's parent (assuming it is not common with the new focus)...
• event_focusEntered is fired on the highest new ancestor for the new focus
• event_focusEntered is fired on the next highest new ancestor for the new focus...
• event_gainFocus is fired on the new focus.

Base NVDAObject's event_focusExited does nothing, as generaly, NVDA should not announce when focus exits an ancestor control.
However, a new ExcelTable UIA NVDAObject has an event_focusExited which announces "out of table" if the new focus is still an ExcelCell. I.e. focus exited the table but is still in the spreadsheet. Not doing this check would mean that "out of table" would have been announced when moving away from Excel or into the ribbon etc which is not preferable.

Testing strategy:

• Ensure NVDA is configured to use UIA for Excel in NVDA's advanced settings.
• Open example_color_table.xlsx in Excel.
• Press down arrow multiple times, noticing that NVDA announces when entering the table at a3, and then announces "out of table" at a8.
• Similarly, moving to d4 and then pressing right arrow, NVDA announces "out of table".

Known issues with pull request:

None known.

Change log entries:

New features

• Excel with UI automation: NVDA now announces when moving outside a table within a spreadsheet.
  Changes
  Bug fixes
  For Developers

Code Review Checklist:

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

stale

[seanbudd]

accidentally dismissed this review

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/rdqa0y71ch2fqg8x/artifacts/output/nvda_snapshot_pr14165-26616,1abd7277.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.7,
  INSTALL_END 0.8,
  BUILD_START 0.0,
  BUILD_END 21.7,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.2,
  TEST_START 0.0,
  TEST_END 13.2,
  FINISH_END 0.1

See test results for failed build of commit 1abd72776d