Link to issue number:

None.

Summary of the issue:

The Humanware Monarch multiline braille / tactile graphics device is adding support for multiline braille routing in its Braille Terminal.
NVDA should support this in its HID Braille driver, so that it is possible to route to any character within the multiline display.
Humanware Monarch currently supports two means of routing: 1. place your finger where you want to route, and press the select button. Or, 2. do a single tap on the cell you wish to route to. Though this seems a little less accurate.

NVDA's current support for routing works by simply looking for any data index for wsitched on inputs, that has been mapped to a router_key usage. The cell index of the router is based on the index of the specific routerkey within its linked collection (presumably routerSet1).
However, as multiline devices like the Monarch will have so many routers (E.g. 256 for the Monarch), they it would be inefficient to to expose them all as individual router_key sages, and instead may be exposed as a usage range, with custom usage values, but all within the routerSet1 collection. This is what the Monarch does.
Therefore, NVDA's HID braille driver needs to ensure it can support usage ranges for routing.

Description of user facing changes:

It is possible to route to any braille cell on the Humanware Monarch multiline braille device.

Description of developer facing changes:

HID Braille driver:

• _collectInputButtonCapsByDataIndex: ensure to increment the data index for evry usage in a useage range, otherwise data indexes will be wrong during / past a usage range. An example usage range might be a router set where each usage is 1 bit. Windows will force this into a usage range.
• _numberOfCellsValueCaps: this must be initially set to None. Otherwise on multiline devices that don't set this, we get an attribute error.
• InputGesture: rather than detecting routing keys as the specific router_key usage, instead, just treat any usage from the routerSet1 collection as a router_key. As if these are 1 bit usages, such as for a multiline devices with 256 cells say, each usage will be some custom value and not specifically all router_key.

Description of development approach:

Testing strategy:

Using a Humanware Monarch with the latest beta firmware:

• Connected NvDA to the Monarch.
• Opened a document in MS Word, displaying a line that took up more than one braill line on the Monarch.
• Tried routing to various positions on each line, verifying the cursor landed in the correct position.

Known issues with pull request:

None known.

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