Add ability to scroll automatically in braille

source/braille.py

@@ -1704,10 +1704,11 @@ def nextLine(self):
 				try:
 					dest.obj.turnPage()
 				except RuntimeError:
-					pass
+					handler.autoScroll(enable=False)
 				else:
 					dest = dest.obj.makeTextInfo(textInfos.POSITION_FIRST)
 			else:  # no page turn support
+				handler.autoScroll(enable=False)
 				shouldCollapseToEnd = True
 		dest.collapse(shouldCollapseToEnd)
 		self._setCursor(dest)
@@ -2475,6 +2476,7 @@ def __init__(self):
 		self._cursorBlinkUp = True
 		self._cells = []
 		self._cursorBlinkTimer = None
+		self._autoScrollCallLater: wx.CallLater | None = None
 		config.post_configProfileSwitch.register(self.handlePostConfigProfileSwitch)
 		if config.conf["braille"]["tetherTo"] == TetherTo.AUTO.value:
 			self._tether = TetherTo.FOCUS.value
@@ -2510,6 +2512,7 @@ def terminate(self):
 		if self._cursorBlinkTimer:
 			self._cursorBlinkTimer.Stop()
 			self._cursorBlinkTimer = None
+		self.autoScroll(enable=False)
 		config.post_configProfileSwitch.unregister(self.handlePostConfigProfileSwitch)
 		post_secureDesktopStateChange.unregister(self._onSecureDesktopStateChanged)
 		post_sessionLockStateChanged.unregister(self._onSessionLockStateChanged)
@@ -2525,12 +2528,14 @@ def terminate(self):
 
 	def _clearAll(self) -> None:
 		"""Clear the braille buffers and update the braille display."""
+		self.autoScroll(enable=False)
 		self.mainBuffer.clear()
 		if self.buffer is self.messageBuffer:
 			self._dismissMessage(False)
 		self.update()
 
 	def _onSecureDesktopStateChanged(self, isSecureDesktop: bool):
+		self.autoScroll(enable=False)
 		self.mainBuffer.clear()
 		if not easeOfAccess.isRegistered():
 			if isSecureDesktop:
@@ -2984,13 +2989,20 @@ def scrollForward(self):
 		self.buffer.scrollForward()
 		if self.buffer is self.messageBuffer:
 			self._resetMessageTimer()
+		if self._autoScrollCallLater:
+			# Reset the timer.
+			self._resetAutoScroll()
 
 	def scrollBack(self):
 		self.buffer.scrollBack()
 		if self.buffer is self.messageBuffer:
 			self._resetMessageTimer()
+		if self._autoScrollCallLater:
+			# Reset the timer.
+			self._resetAutoScroll()
 
 	def routeTo(self, windowPos):
+		self.autoScroll(enable=False)
 		self.buffer.routeTo(windowPos)
 		if self.buffer is self.messageBuffer:
 			self._dismissMessage()
@@ -3015,6 +3027,7 @@ def message(self, text):
 		):
 			return
 		_pre_showBrailleMessage.notify()
+		self.autoScroll(enable=False)
 		if self.buffer is self.messageBuffer:
 			self.buffer.clear()
 		else:
@@ -3055,6 +3068,39 @@ def _dismissMessage(self, shouldUpdate: bool = True):
 			self.update()
 		_post_dismissBrailleMessage.notify()
 
+	def autoScroll(self, enable: bool) -> None:
+		"""
+		Enable or disable automatic scroll.
+
+		:param enable: ``True`` if automatic scroll should be enabled, ``False`` otherwise.
+		"""
+
+		if not self.enabled or config.conf["braille"]["mode"] == BrailleMode.SPEECH_OUTPUT.value:
+			return
+		if enable and self._autoScrollCallLater is None:
+			self._autoScrollCallLater = wx.CallLater(self._calculateAutoScrollTimeout(), self.scrollForward)
+		elif not enable and self._autoScrollCallLater is not None:
+			self._autoScrollCallLater.Stop()
+			self._autoScrollCallLater = None
+
+	def _calculateAutoScrollTimeout(self) -> int:
+		"""
+		Calculate the timeout for automatic scroll.
+
+		:return: The number of milliseconds to wait until the next scroll.
+		"""
+
+		autoScrollRate = config.conf["braille"]["autoScrollRate"]
+		return int((self.displaySize / autoScrollRate) * 1000)
+
+	def _resetAutoScroll(self) -> None:
+		"""
+		Reset autoScroll.
+		"""
+
+		self.autoScroll(enable=False)
+		self.autoScroll(enable=True)
+
 	def handleGainFocus(self, obj: "NVDAObject", shouldAutoTether: bool = True) -> None:
 		if not self.enabled or config.conf["braille"]["mode"] == BrailleMode.SPEECH_OUTPUT.value:
 			return
@@ -3078,6 +3124,7 @@ def handleGainFocus(self, obj: "NVDAObject", shouldAutoTether: bool = True) -> N
 		)
 
 	def _doNewObject(self, regions):
+		self.autoScroll(enable=False)
 		self.mainBuffer.clear()
 		focusToHardLeftSet = False
 		for region in regions:

source/config/configSpec.py

@@ -83,6 +83,8 @@
 	showMessages = integer(0, 2, default=1)
 	# 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)
 	tetherTo = option("auto", "focus", "review", default="auto")
 	reviewRoutingMovesSystemCaret = featureFlag(\
 		optionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")

source/globalCommands.py

@@ -826,6 +826,56 @@ def script_toggleReportSpellingErrorsInBraille(self, gesture: inputCore.InputGes
 			# Translators: Message presented when turning off reporting spelling errors in braille.
 			ui.message(_("Report spelling errors in braille off"))
 
+	@script(
+		# Translators: Input help mode message for command to toggle braille automatic scroll.
+		description=_("Toggles braille automatic scroll"),
+		category=SCRCAT_BRAILLE,
+	)
+	def script_toggleBrailleAutoScroll(self, gesture: inputCore.InputGesture):
+		if config.conf["braille"]["mode"] == BrailleMode.SPEECH_OUTPUT.value:
+			return
+		shouldEnableAutoScroll = braille.handler._autoScrollCallLater is None
+		if shouldEnableAutoScroll:
+			# Translators: Message reported when automatic scrolling has been enabled in braille.
+			ui.message(_("Automatic scrolling enabled"))
+			timeout = config.conf["braille"]["messageTimeout"] * 1000
+			core.callLater(timeout, braille.handler.autoScroll, shouldEnableAutoScroll)
+		else:
+			# Translators: Message reported when automatic scrolling has been disabled in braille.
+			ui.message(_("Automatic scrolling disabled"))
+
+	@script(
+		# Translators: Input help mode message for command to increase the rate for braille automatic scroll.
+		description=_("Increases the rate for braille automatic scroll"),
+		category=SCRCAT_BRAILLE,
+	)
+	def script_increaseBrailleAutoScrollRate(self, gesture: inputCore.InputGesture):
+		maxRate = int(
+			config.conf.getConfigValidation(
+				("braille", "autoScrollRate"),
+			).kwargs["max"],
+		)
+		if config.conf["braille"]["autoScrollRate"] < maxRate:
+			config.conf["braille"]["autoScrollRate"] += 1
+		rate = str(config.conf["braille"]["autoScrollRate"])
+		ui.message(rate)
+
+	@script(
+		# Translators: Input help mode message for command to decrease the rate for braille automatic scroll.
+		description=_("Decreases the rate for braille automatic scroll"),
+		category=SCRCAT_BRAILLE,
+	)
+	def script_decreaseBrailleAutoScrollRate(self, gesture: inputCore.InputGesture):
+		minRate = int(
+			config.conf.getConfigValidation(
+				("braille", "autoScrollRate"),
+			).kwargs["min"],
+		)
+		if config.conf["braille"]["autoScrollRate"] > minRate:
+			config.conf["braille"]["autoScrollRate"] -= 1
+		rate = str(config.conf["braille"]["autoScrollRate"])
+		ui.message(rate)
+
 	@script(
 		# Translators: Input help mode message for toggle report pages command.
 		description=_("Toggles on and off the reporting of pages"),

source/gui/settingsDialogs.py

@@ -5493,6 +5493,27 @@ def makeSettings(self, settingsSizer):
 		)
 		self.bindHelpEvent("BrailleSettingsInterruptSpeech", self.brailleInterruptSpeechCombo)
 
+		minRate = int(
+			config.conf.getConfigValidation(
+				("braille", "autoScrollRate"),
+			).kwargs["min"],
+		)
+		maxRate = int(
+			config.conf.getConfigValidation(
+				("braille", "autoScrollRate"),
+			).kwargs["max"],
+		)
+		# Translators: The label for a setting in braille settings to change the rate for autoscroll.
+		autoScrollRateText = _("Auto&matic scroll rate (cells/sec)")
+		self.autoScrollRateEdit = followCursorGroupHelper.addLabeledControl(
+			autoScrollRateText,
+			nvdaControls.SelectOnFocusSpinCtrl,
+			min=minRate,
+			max=maxRate,
+			initial=config.conf["braille"]["autoScrollRate"],
+		)
+		self.bindHelpEvent("BrailleAutoScrollRate", self.autoScrollRateEdit)
+
 		if gui._isDebug():
 			log.debug("Finished making settings, now at %.2f seconds from start" % (time.time() - startTime))
 
@@ -5523,6 +5544,7 @@ def onSave(self):
 		]
 		config.conf["braille"]["showMessages"] = self.showMessagesList.GetSelection()
 		config.conf["braille"]["messageTimeout"] = self.messageTimeoutEdit.GetValue()
+		config.conf["braille"]["autoScrollRate"] = self.autoScrollRateEdit.GetValue()
 		tetherChoice = [x.value for x in TetherTo][self.tetherList.GetSelection()]
 		if tetherChoice == TetherTo.AUTO.value:
 			config.conf["braille"]["tetherTo"] = TetherTo.AUTO.value

user_docs/en/changes.md

@@ -35,6 +35,7 @@ An action has been added to view the full scan results on the VirusTotal website
 * In browse mode, the number of items in a list is now reported in braille. (#7455, @nvdaes)
 * Automatically reading the entire result after a successful recognition is now possible via a new option in the Windows OCR settings. (#19150, @Cary-rowen)
 * Added support for reading math content by integrating MathCAT. (@RyanMcCleary, #18323)
+* Added ability to scroll forward braille automatically (#18573, @nvdaes)
 
 ### Changes
 
@@ -95,6 +96,7 @@ On ARM64 machines with Windows 11, these ARM64EC libraries are loaded instead of
 * NVDA is now licensed under "GPL-2 or later".
 * In `braille.py`, the `FormattingMarker` class has a new `shouldBeUsed` method, to determine if the formatting marker key should be reported (#7608, @nvdaes)
 * Added `api.fakeNVDAObjectClasses` set and `api.isFakeNVDAObject` function to identify fake NVDAObject instances. (#19168, @hwf1324)
+* Added an `autoScroll` method to `braille.handler`. (#18573, nvdaes)
 
 #### API Breaking Changes
 

user_docs/en/userGuide.md

@@ -2424,6 +2424,18 @@ Enabling this option will cause NVDA to speak lines or paragraphs reached using
 
 To toggle this option from anywhere, please assign a custom gesture to "speakOnNavigatingByUnit" in the "Braille" section of the [Input Gestures dialog](#InputGestures).
 
+##### Automatic Scroll Rate {#BrailleAutoScrollRate}
+
+This option controls the rate of automatic braille display scrolling, measured in cells per second.
+For example, with the default value of 10 cells/sec, if a braille display with 40 cells is used, the number of seconds between automatic scrolls will be 4.
+If the display had 20 cells, each line of braille would be shown for 2 seconds.
+
+While the automatic scroll option is enabled, you can still use the scroll back command to read previous contents again, and scroll forward, for example, to skip a blank line, or if the line been read is too short.
+
+Automatic scrolling will be disabled if a routing key is pressed, if a message is presented in braille, if a new object is displayed, when entering a secure screen, or when the session is locked.
+
+Commands can be assigned to toggle the automatic scroll option, and to increase or decrease the scroll rate, from the "Braille" section of the [Input Gestures dialog](#InputGestures).
+
 ##### Avoid splitting words when possible {#BrailleSettingsWordWrap}
 
 If this is enabled, a word which is too large to fit at the end of the braille display will not be split.