Update Braille Reading and Automatic Scroll Rate in User Guide by Qchristensen · Pull Request #20477 · nvaccess/nvda

Qchristensen · 2026-07-10T01:50:23Z

Link to issue number:

No issue, but supersedes PR #20457 (Which I'll close now this is open)

Summary of the issue:

Moved from PR #20457 to make change against beta rather than master. Accommodated the suggestions from that PR and also expanded scope to add a new "Braille Reading" topic under the main Braille section which includes a sub-section on automatic Braille scrolling.

Also added tables for Braille reading and input commands. These have many unassigned gestures. The intention is to eventually document all unassigned gestures in their respective sections of the user guide.

Initially prompted because automatic braille scrolling requires an unassigned gesture to be used in order to work. This wasn't 100% obvious in the documentation originally (at least not to me).

Description of user facing changes:

Updated user guide

Description of developer facing changes:

Description of development approach:

Testing strategy:

Known issues with pull request:

Issue #20473 proposes several gestures which will need to be added to the table / documentation once added. (They will also mean less emphasis on the gestures being undefined, though given the number of braille gestures which ARE undefined, it will still be worth highlighting in that section of the user guide).

Code Review Checklist:

[ x ] 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
[ 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.
Security precautions taken.

Moved from PR #20457 to make change against beta rather than master. Accommodated the suggestions from that PR and also expanded scope to add a new "Braille Reading" topic under the main Braille section which includes a sub-section on automatic Braille scrolling. Also added tables for Braille reading and input commands. These have many unassigned gestures. The intention is to eventually document all unassigned gestures in their respective sections of the user guide.

Co-authored-by: Sean Budd <sean@nvaccess.org>

Qchristensen

Fixed up keystrokes not marked up

seanbudd · 2026-07-10T03:44:44Z

+| Toggles braille mode | `NVDA+alt+t` | Allows cycling between available braille modes: "follow cursors" and "display speech output"|
+| Tether braille |`VDA+control+t` | This option allows you to choose whether the braille display will follow the system focus / caret, the navigator object / review cursor, or both |
+| Toggle automatic scroll | None | Scrolls the display to present information which is larger than will fit on the display at once.  Press again to pause scrolling |
+| Increase automatic scroll rate | none | Makes automatic scrolling faster (when enabled) |


Please capitalize None in the rest of these

Co-authored-by: Sean Budd <sean@nvaccess.org>

Qchristensen

Fixed: "none" to "None" and added KC commands around the two tables.

CyrilleB79 · 2026-07-10T08:24:29Z

+| Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position |
+| Toggle braille cursor | none | Toggle the braille cursor on and off |
+| Toggle braille context information | none | Toggle the way context information is presented in braille |
+| Toggle braille mode | `NVDA+alt+t` | Toggles braille mode |


This entry appears twice in the table.

CyrilleB79 · 2026-07-10T08:40:06Z

-This slider controls the rate of automatic braille display scrolling, measured in cells per second.
+This slider controls the rate at which NVDA scrolls the braille display when [automatic braille scrolling](#AutomaticBrailleScrolling) is enabled, measured in cells per second.
+
+In order to use this feature, you first need to assign a gesture to toggle automatic braille scrolling in the "Braille" section of the [Input Gestures dialog](#InputGestures).


This line should be removed.
It's related to the feature, not to the setting.
More, you've already written this in the section dedicated to the braille scrolling feature.

Well, it's related to being able to use the setting. This is the first option we have in the whole settings dialog which affects a feature which does not have a default gesture. I'm concerned people may be confused by that so wanted to make it abundantly clear - but I'm open to what others think?

Meanwhile, Noelia has created an issue proposing a default gesture, so if that is adopted, then obviously this line can be removed in both places (though still applies to other braille gestures, but we can discuss that separately).

Just above in the paragraph, you write:
This slider controls the rate at which NVDA scrolls the braille display when [automatic braille scrolling](#AutomaticBrailleScrolling) is enabled, measured in cells per second.

You already mention the feature, with a link to its description paragraph, and indicate that this parameter applies when the feature is enabled.
This seemed enough to me.

Qchristensen · 2026-07-10T12:44:37Z

+| Toggle braille tethering | `NVDA+ctrl+t` | Toggle tethering of braille between the focus and the review position |
+| Toggle braille cursor | none | Toggle the braille cursor on and off |
+| Toggle braille context information | none | Toggle the way context information is presented in braille |
+| Toggle braille mode | `NVDA+alt+t` | Toggles braille mode |


Suggested change

| Toggle braille mode | `NVDA+alt+t` | Toggles braille mode |

Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>

Co-authored-by: Noelia Ruiz Martínez <nrm1977@gmail.com>

Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>

Copilot

Pull request overview

Updates the NVDA User Guide’s Braille documentation to make “automatic braille scrolling” more discoverable and to introduce gesture tables for braille reading/input commands.

Changes:

Adds a new “Braille Reading” subsection, including an “Automatic Braille Scrolling” explanation and a “Braille Reading Gestures” table.
Adds a “Braille Input Gestures” table under the braille keyboard shortcut/inputting section.
Reworks “Automatic Scroll Rate” to emphasize that gestures must be assigned to use/tune automatic scrolling, and links readers to the new “Automatic Braille Scrolling” section.

+| Toggle automatic scroll | None | Scrolls the display to present information which is larger than will fit on the display at once.  Press again to pause scrolling |
+| Increase automatic scroll rate | none | Makes automatic scrolling faster (when enabled) |
+| Decrease automatic scroll rate | none | Makes automatic scrolling slower (when enabled) |
+| Cycle braille cursor shapes | none | Cycle through the shape options (dot pattern) of the braille cursor |
+| Cycle move system caret when routing review cursor | none | Cycle through the braille move system caret when routing review cursor states |


+| Cycle show messages modes | none | Cycle through the braille show messages modes |
+| Cycle braille show selection states | none | Cycle through the braille show selection states |
+| Cycle braille Unicode normalization states | none | Cycle through the braille Unicode normalization states |
+| Move braille to focus | none | Moves the braille display to the current focus |
+| Move braille to next line | none | Moves the braille display to the next line |


+| Move braille to previous line | none | Moves the braille display to the previous line |
+| Report braille formatting | none | Reports formatting info for the text under this braille cell |
+| Route to or activate braille object | none | Routes the cursor to or activates the object under this braille cell |
+| Scroll braille display back | none | Scrolls the braille display back |
+| Scroll braille display forward | none | Scrolls the braille display forward |


+| Toggle braille cursor | none | Toggle the braille cursor on and off |
+| Toggle braille context information | none | Toggle the way context information is presented in braille |
+| Toggle speaking when navigating braille | none | Toggles on and off speaking when navigating by lines or paragraph with braille |
+| Toggle speaking character when routing | none | Toggles speaking the character under the cursor when routing cursor in text |


 In addition, the emulated keypress cannot reflect Braille typed before the modifier key was pressed.
 This means that, to type alt+2 with a Braille code that uses a number sign, you must first toggle Alt and then type a number sign.

+#### Braille Input Gestures {BrailleInputGestures}


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Quentin Christensen <quentin@nvaccess.org> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Qchristensen

Applied previous suggestions

Qchristensen requested a review from a team as a code owner July 10, 2026 01:50

Pre-commit auto-fix

1cc5cca

This was referenced Jul 10, 2026

Update automatic scrolling in the userGuide #20457

Closed

Add gestures to manage automatic scrolling braille #20473

Open

seanbudd added this to the 2026.2 milestone Jul 10, 2026

seanbudd reviewed Jul 10, 2026

View reviewed changes

Comment thread user_docs/en/userGuide.md

Comment thread user_docs/en/userGuide.md Outdated

Comment thread user_docs/en/userGuide.md Outdated

Comment thread user_docs/en/userGuide.md Outdated

Comment thread user_docs/en/userGuide.md Outdated

Comment thread user_docs/en/userGuide.md Outdated

Qchristensen and others added 6 commits July 10, 2026 12:05

Update user_docs/en/userGuide.md

52e92e8

Co-authored-by: Sean Budd <sean@nvaccess.org>

Update user_docs/en/userGuide.md

13c283a

Co-authored-by: Sean Budd <sean@nvaccess.org>

Update user_docs/en/userGuide.md

2ee4184

Co-authored-by: Sean Budd <sean@nvaccess.org>

Update user_docs/en/userGuide.md

281dd07

Co-authored-by: Sean Budd <sean@nvaccess.org>

Pre-commit auto-fix

50e6fe2

Update user_docs/en/userGuide.md

575aa8e