Text displayed on a multiline braille display will now word wrap on every row in the braille window, not just at the end

[michaelDCurran]

Link to issue number:

None.

Summary of the issue:

Although displaying a long line of braille on a multiline braille display fills up as much of the display as possible, rows may end in the middle of a word. NVDA should honor the 'avoid splitting words when possible' Braille setting for all rows on the display.

Description of user facing changes

When displaying braille on a multiline braille display, NVDA will avoid splitting words over lines if the 'avoid splitting words when possible' braille setting is on.

Description of development approach

Rather than tracking a braille window as only _windowStartPos and _windowEndPos, internally store a list of window rows which map to start and end offsets in the braille buffer. These offsets are calculated each time the window is moved or the buffer is updated, and ensure that words are not split across window rows.

This PR also adds / changes the filters available for external code such as Remote to dictate the size of the display:

• braille: Added a filter_displayDimensions extension point which takes a namedtuple of numRows and numCols, allowing external code to dictate the number of rows and columns for the display. This should be used now in place of filter_displaySize. This stops the worry of external code changing the number of rows but forgetting to change the over all size.
• braille.handler: Added a displayDimensions property which:
  • creates a DisplayDimensions namedtuple of the display's real numRows and numCols.
  • Filters this with filter_displayDimensions.
  • Calculates displaySize from the product of the filtered numRows and numCols.
  • If at least one handler is registered on the old displaySize filter:
    • Filters this with the old filter_displaySize.
    • If the displaySize changes due to filtering, for backwards compatibility the DisplayDimensions numRows is set to 1 and numCols is set to the filtered displaySize.
    • If the DisplayDimensions have changed at all from the internal cache after all the filters and calculations, then fire the handle_displaySizechanged extension point passing displaySize, numRows and numCols.

This all means that new NVDA / remote code could specify full display dimensions, but for backwards compatibility, if the old displaySize filter is used, then braille is forced to a single row with displaySize cells.

Testing strategy:

• Tested NVDA with a Dot pad braille display. Used NVDA in various standard situations for a length of time, displaying long lines of documents and controls, ensuring that splitting words is avoided.
• Performed the same above test but by dictating display should have 3 rows and 10 columns via the displayDimensions filter. Ensured that content only filled a 3 by 10 space on the DotPad and nothing was cut off and I could still pan to see more.
• Performed the same above test but by dictating display should have a display size of 15 via the old displaySize filter. Ensured that content only filled a single line of 15 cells on the DotPad and nothing was cut off and I could still pan to see more.
• Tested with an Orbit Reader single line display, ensuring that displaying and cursor routing still function as before this PR.

Known issues with pull request:

Code only applies the displaySize filter if at least one handler has registeref for the filter. this is checked by len(list(filter_displaySize.handlers)). There is a technical race condition here as a handler could unregister before the filter is applied. However the worse case is really just that a multiline display will stay singleline for the current display update. In future it might be nice if the idea of checking for extension point Filter registrations could be standardized better, in particular some kind of atomic call that both communicated if handlers were registered and filtered a value if so.

Code Review Checklist:

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

Summary by CodeRabbit

• New Features

  • Improved handling of braille display windows with enhanced buffer management and row-based display logic.
  • Introduced a new method to convert window-relative positions to buffer-relative positions, offering better content control.

• Bug Fixes

  • Restructured display dimensions management for more accurate rendering, avoiding word splits in multi-row configurations.

• Tests

  • Added unit tests for resizing cell arrays to ensure functionality across various scenarios.
  • Updated existing tests to align with the new display dimensions structure.