Add ability to scroll automatically in braille #19126

nvdaes · 2025-10-21T18:52:15Z

Add ability to scroll automatically with braille
Add ability to scroll automatically in braille

Link to issue number:

Fixes #18573

Summary of the issue:

Users may wish to scroll braille automatically.

Description of user facing changes:

Added an unassigned command to toggle scrolling braille automatically.
Added unasigned commands to decrease and increase the autoScroll rate.
In the braille settings subpanel, added an edit box to set the autoScroll rate, measured in cells/seconds.

Description of developer facing changes:

The BrailleHandler class has a new method named autoScroll with an enable parameter, to toggle braille automatic -scroll.

Description of development approach:

Added an autoScroll`` method in the BrailleHandlerclass to toggle automatic scroll. This will usewx.CallLaterto call theautoScrollForwardmethod. Code has been added to stop autoScroll when the caret reaches the end of a document (the cursor is not moved), when a message is displayed in braille, when a new object is handled, on secure screens, and when the session is locked, via the_clearAll` method.
Also, if automatic scroll is enabled, when scrolling back or forward, autoScroll will be disabled and enabled to reset the timer and scroll forward again.

Testing strategy:

Tested locally.

Known issues with pull request:

None.

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.

codeofdusk · 2025-10-21T21:21:05Z

Some displays have capacitive sensors that can detect when you reach the end of the line of Braille and optionally advance automatically, so supporting this use case is also worth thinking about.

CC @FelixGruetzmacher, @LeonarddeR.

…possible interferences, especially if speak while navigating by line or paragraph is enabled

…railleScroll

LeonarddeR · 2025-10-22T11:12:09Z

For now, the default reading speed is 10 chars/sec.

This means that the speed would be dependant on the braille display size, but that doesn't seem to be the case in your code yet. I like the assumed characters per sec approach though. That would mean you can increase scrolling speed when a line only contains a few characters.

nvdaes · 2025-10-22T16:02:50Z

Leonard wrote:

I like the assumed characters per sec approach

I write the code for that approach, but later I removed it due to feedback from people who is concerned about ability to understand this concept, thinking for example in older people, or people with cognitive difficulties. Seems that the BrailleExtender add-on used the seconds approach, not chars/sec.
We may create a combo box to decide between seconds or char/sec, or adding a checkbox asking if this should be proportional to the display size or the number of cells used.
cc: @gerald-hartig since this may be controversial.

nvdaes · 2025-10-23T04:29:40Z

For now I'll try to create a combo box. I thought abou using the number of used cells, not the display size, too. But perhaps this produces an uncomfortable feeling if someone doesn't know if all relevant information has been read, if interval about scrollings is variable. So a combo box is more flexible than a checkbox, to add several options if desired.
In the spanish community, where there are users testing this, a combo box has been suggested for this.

nvdaes · 2025-10-25T17:31:09Z

@SaschaCowley , I think that the failure of Pyright is not related to the code. Seems that the analysis is not performed due to something related to the cache.

nvdaes · 2025-10-25T18:20:13Z

Sorry @SaschaCowley , forget my comment about Pyright. I've analyzed the code locally and have fixed it (now no I don't get errors and the check here has passed).

nvdaes · 2025-10-29T05:45:54Z

I see that this has been labelled with ConceptApproved, so I'll continue working on this. I think that adding a combo box for cells/seconds and seconds can be confusing, since in one case the value increases the rate, and in the other one the delay is increased. So I'm thinking in adding just a value, but trying to reflect the conversion between cells/seconds to seconds deppending on the display size. I have found people who doesn't understand the concept of cells/seconds, at least the first time. But I think that it has more sense that jst seconds, since the same value can be applied regardless to the display size, for example if someone connects a different braille display.

user_docs/en/userGuide.md

Co-authored-by: Sean Budd <[email protected]>

nvdaes · 2025-11-21T04:16:30Z

@seanbudd , thanks for your review. I've seen just a suggestion related to the user guide, and I've applied it.

SaschaCowley

Overall really nice, @nvdaes. A few style things, as well as some questions regarding the UX for braille-only users.

source/braille.py

SaschaCowley · 2025-11-25T06:17:33Z

source/globalCommands.py

+		if config.conf["braille"]["autoScrollRate"] < maxRate:
+			config.conf["braille"]["autoScrollRate"] += 1
+		rate = str(config.conf["braille"]["autoScrollRate"])
+		speech.speakMessage(rate)


What about braille-only users?

SaschaCowley · 2025-11-25T06:18:49Z

source/globalCommands.py

+		if config.conf["braille"]["autoScrollRate"] > minRate:
+			config.conf["braille"]["autoScrollRate"] -= 1
+		rate = str(config.conf["braille"]["autoScrollRate"])
+		speech.speakMessage(rate)


What about braille-only users?

user_docs/en/userGuide.md

nvdaes · 2025-11-25T06:41:58Z

Thanks for your review, @SaschaCowley . About only braille users, when a message is shown in braille, scrolling is disabled, but I'll try to fix this.

Co-authored-by: Sascha Cowley <[email protected]>

…railleScroll

nvdaes · 2025-11-25T22:38:19Z

@SaschaCowley , I think that I've addressed all your comments, and I've tested this locally.

seanbudd

@nvdaes - nice work here, I'm sure this will be a much appreciated feature.

seanbudd · 2025-12-05T02:50:02Z

source/braille.py

+		:param enable: ``True`` if automatic scroll should be enabled, ``False`` otherwise.
+		"""
+
+		if not self.enabled or config.conf["braille"]["mode"] == BrailleMode.SPEECH_OUTPUT.value:


I'm a bit confused by this, wouldn't braille mode speech output be a major use case for this? i.e. being able to read the braille and hear the speech at roughly the same time?

Yes, may be. I don't use the speech mode, so I didn't think about this. I'll test and add it.

source/config/configSpec.py

seanbudd · 2025-12-05T02:53:53Z

source/config/configSpec.py

 	# Timeout after the message will disappear from braille display
 	messageTimeout = integer(default=4, min=1, max=20)
+	# Rate for automatic scroll
+	autoScrollRate = integer(default=10, min=1, max=20)


is 20 different rates too limiting? perhaps the interval step should be 0.1 or 0.5?

Yes, 20 seems too much. Let's use 15 cells/sec. Should we use a slider instead of a spin control?

I was thinking 20 is not enough? I think a spin control is good here

Generally I read at 12 cells/sec or so. According to a rule used in Spain for captions, the recommended speed is 12 chars/sec or so too. I think that 20 is a lot, but may be that in some texts can be used.
We can use 30 if you want. When lines are short, I use the keystroke in the braille display to scroll forward manually.

My concern wasn't about raising it to 30, but instead allowing 10.5/sec or 10.1/sec. e.g. finer grain

OK, then 20 may be enough, but I need to investigate how to allow 0.1 interval using seconds. Perhaps milliseconds wikk be better, or using a slider. I don't know another samples of float numbers with spin controls.

You can use SetIncrement on a wx.SpintCtrl

I think an interval of 0.5 might be enough? We can always change it 0.1 later

OK. I'll try to use SetIncrement and a float value in the config. I'll work for this this weekend.

Co-authored-by: Sean Budd <[email protected]>

CyrilleB79 · 2025-12-05T13:14:41Z

FYI, in #12049, I have finally had to use integers in milliseconds rather than float number due to GUI issues (with wx).

nvdaes · 2025-12-06T03:20:35Z

Cyrille wrote:

I have finally had to use integers in milliseconds

I'm investigating several solutions, like using percentages or milliseconds, but I'm not satisfied with the user experience.
I've tried to investigate floatspin, but seems that it's not easy to select the text of the text control.
But in fact, incrementing one cell/sec may provide enough granularity. We are talking about cells/sec, not secs/cells. And anyway the timeout with the same increment in cells/sec will be increased in a different number of milliseconds, depending on the display sice. But I think that cells/sec is better that secs or ms, to get a timeout proportional to the display size.
I'll fix things if I find any errors, and I'll wait for your answer befor moving forward.

nvdaes and others added 3 commits October 21, 2025 05:09

Add ability to scroll automatically with braille

5b411ab

Add ability to scroll automatically in braille

ab1056e

Pre-commit auto-fix

098bedc

nvdaes mentioned this pull request Oct 21, 2025

Braille text autoscroll #18573

Open

nvdaes added 4 commits October 22, 2025 05:29

Beep instead of speaking message when scrolling is enabled, to avoid …

b997c66

…possible interferences, especially if speak while navigating by line or paragraph is enabled

Merge branch 'brailleScroll' of https://github.com/nvdaes/nvda into b…

7e89c2c

…railleScroll

Added edit box to set the interval in seconds for autoScroll

d380d88

Convert to milliseconds autoScrollTimeout

01e4f87

nvdaes and others added 10 commits October 24, 2025 05:47

Add combo box for autoScroll intervals

79d83f9

Merge branch 'master' into brailleScroll

c3c7e47

Save autoScroll interval option

f033be7

Pre-commit auto-fix

5b6fca5

Use option for autoScrollInterval in config

572f1af

Add commands to increase and decrease autoScroll

e1e8b70

Pre-commit auto-fix

7ab4eb2

Update coment

3d60cd1

Merge remote-tracking branch 'origin/master' into brailleScroll

43335b5

Use oneShot in autoScroll

6873bae

Fix pyright analysis locally

17d52c6

SaschaCowley added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Oct 28, 2025

nvdaes and others added 3 commits October 30, 2025 05:25

Merge remote-tracking branch 'origin/master' into brailleScroll

3463e1d

Remove combo box to select how to calculate the autoScroll interval

a1a748c

Pre-commit auto-fix

22515bb

nvdaes added 4 commits November 20, 2025 15:49

Update user guide

bc64da2

Disable autoScroll when the session is locked

3207953

Update user guide

00ab1ae

Update changelog

3efcc0e

nvdaes requested a review from SaschaCowley November 20, 2025 18:54

nvdaes marked this pull request as ready for review November 20, 2025 18:55

nvdaes requested review from a team as code owners November 20, 2025 18:55

nvdaes requested a review from Qchristensen November 20, 2025 18:55

seanbudd reviewed Nov 21, 2025

View reviewed changes

user_docs/en/userGuide.md Outdated Show resolved Hide resolved

Apply suggestions from code review

f3a2041

Co-authored-by: Sean Budd <[email protected]>

SaschaCowley requested changes Nov 25, 2025

View reviewed changes

nvdaes and others added 6 commits November 25, 2025 07:46

Apply suggestions from code review

0734bb6

Co-authored-by: Sascha Cowley <[email protected]>

Pre-commit auto-fix

a6a142a

Address code review

367a301

Pre-commit auto-fix

dbcffc5

Improve toggling scroll handling message timeout

a8f2459

Merge branch 'brailleScroll' of https://github.com/nvdaes/nvda into b…

f8630ea

…railleScroll

seanbudd reviewed Dec 5, 2025

View reviewed changes

nvdaes and others added 6 commits December 5, 2025 05:53

Apply suggestions from code review

87f6ec8

Co-authored-by: Sean Budd <[email protected]>

Merge

3d754c3

Restore liblouis

b3052eb

Increase maximum for scroll rate

72cc841

Allow scrolling when braille follows speech

c19039d

Merge branch 'master' into brailleScroll

8f5eb26

Uh oh!

Add ability to scroll automatically in braille #19126

Are you sure you want to change the base?

Add ability to scroll automatically in braille #19126

Uh oh!

Conversation

nvdaes commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to issue number:

Summary of the issue:

Description of user facing changes:

Description of developer facing changes:

Description of development approach:

Testing strategy:

Known issues with pull request:

Code Review Checklist:

Uh oh!

codeofdusk commented Oct 21, 2025

Uh oh!

LeonarddeR commented Oct 22, 2025

Uh oh!

nvdaes commented Oct 22, 2025

Uh oh!

nvdaes commented Oct 23, 2025

Uh oh!

nvdaes commented Oct 25, 2025

Uh oh!

nvdaes commented Oct 25, 2025

Uh oh!

nvdaes commented Oct 29, 2025

Uh oh!

Uh oh!

nvdaes commented Nov 21, 2025

Uh oh!

SaschaCowley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nvdaes commented Nov 25, 2025

Uh oh!

nvdaes commented Nov 25, 2025

Uh oh!

seanbudd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CyrilleB79 commented Dec 5, 2025

nvdaes commented Oct 21, 2025 •

edited

Loading