Expose number of rows/lines on multiline braille displays

[bramd]

Link to issue number:

None

Summary of the issue:

Currently, NVDA assumes that braille displays always have one line of output. There are no native braille drivers in NVDA that support multi line displays.
However, BRLTTY supports a few multi line displays such as the Canute and the DotPad. A first step to supporting these displays would be to treat them as one large display so we can at least output to all their cells. Multi line displays now crash the BRLTTY driver.

Description of user facing changes

Multi line braille displays can now be used through BRLTTY and will no longer cause the driver to crash. Please note that the display is handled as one large continuous display and no specific features exist to use the multiple braille lines for multi line output.

Description of development approach

The BRLTTY driver only reads the number of columns and uses that as numCells. This causes a crashing braille driver with multi line displays, since we send not enough cells to fill the display.

This PR adds numCols and numRows properties to the BrailleDisplayDriver class and the default for numCells is to return the total number of cells on the display. Setting numCells is still supported for single line displays, but for multi line displays this will raise a ValueError and numCols/numRows should be set explicitly.

The BRLTTY driver is modified to set numRows/numCols correctly based on the info from BrlAPI.

Testing strategy:

• Ran unit tests
• Tested output with a DotPad connected through BRLTTY

Known issues with pull request:

None

Change log entries:

New features
Changes
Bug fixes

• Multi line braille displays will no longer crash the BRLTTY driver and are treated as one continuous display
  For Developers
• The BrailleDisplayDriver base class now has numRows and numCols properties to provide information about multi line braille displays, setting numCells is still supported for single line braille displays and numCells will return the total number of cells for multi line braille displays

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.

[LeonarddeR]

One thing that can probably be ignored. the ecoBraille and lilli implement _get_numCells explicitly, so in that case numCells and numColls wil differ. That shouldn't be a problem though.

[bramd]

@LeonarddeR For Lilli we could probably solve this by just making numCells a simple assignment and get rid of the getter, which returns a static value anyway and should trigger set_numCells. For EcoBraille I don't see an easy way to solve this. It might not matter now, but I don't really like it either since numCols is part of the public interface of the BrailleDisplay class and should be reliable.

[bramd]

Still not really happy with the Lilli/Ecobraille situation, but see no clear way to fix this. So I would like an initial review and am still open for changes.

[LeonarddeR]

May be we should leave numCols and numRows alone for single line braille display drivers. This can be done by removing the setter from numCells from the base class. Of course this means you need to undo the changes to the unit test as well.
If NVDA core would ever be adapted to support multi line displays better, it can safely use numCells and if something special regarding multi line displays needs to happen, numRows must be greater than one anyway.

[seanbudd]

Could you confirm these changes?

[bramd]

@seanbudd Thanks for your review suggestions, I have applied them. If we accept the slightly API breaking change I think this is ready for merging.

[seanbudd]

@bramd - I don't think this counts as an API breaking change - could you explain how the API would break for an add-on?

[bramd]

@bramd - I don't think this counts as an API breaking change - could you explain how the API would break for an add-on?

Drivers providing their own get_numCells implementation may and up with a difference in numCols and numCells, but since nothing consumes numCols yet, this is not an issue for now. As long as we stick with numCells in NVDA core for single line displays, I don't see any issues.