Add ability to scroll automatically in braille

source/braille.py

@@ -1712,10 +1712,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)
@@ -2483,6 +2484,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
@@ -2518,6 +2520,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)
@@ -2533,12 +2536,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:
@@ -2992,13 +2997,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()
@@ -3023,6 +3035,7 @@ def message(self, text):
 		):
 			return
 		_pre_showBrailleMessage.notify()
+		self.autoScroll(enable=False)
 		if self.buffer is self.messageBuffer:
 			self.buffer.clear()
 		else:
@@ -3063,6 +3076,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:
+			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
@@ -3086,6 +3132,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

@@ -82,6 +82,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 (cells/sec)
+	autoScrollRate = float(default=10, min=1, max=20)
 	tetherTo = option("auto", "focus", "review", default="auto")
 	reviewRoutingMovesSystemCaret = featureFlag(\
 		optionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")

source/globalCommands.py

@@ -844,6 +844,63 @@ def script_toggleReportSpellingErrorsInBraille(self, gesture: inputCore.InputGes
 			# Translators: Message presented when turning off reporting spelling errors or grammar in braille.
 			ui.message(_("Report 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):
+		shouldEnableAutoScroll = braille.handler._autoScrollCallLater is None
+		timeout = 0
+		if shouldEnableAutoScroll:
+			# Translators: Message reported when automatic scrolling has been enabled in braille.
+			ui.message(_("Automatic scrolling enabled"))
+			if not (
+				config.conf["braille"]["showMessages"] == ShowMessages.DISABLED
+				or config.conf["braille"]["mode"] == BrailleMode.SPEECH_OUTPUT.value
+			):
+				timeout = config.conf["braille"]["messageTimeout"] * 1000
+		else:
+			# Translators: Message reported when automatic scrolling has been disabled in braille.
+			ui.message(_("Automatic scrolling disabled"))
+		core.callLater(timeout, braille.handler.autoScroll, shouldEnableAutoScroll)
+
+	@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"] + 0.5 <= maxRate:
+			config.conf["braille"]["autoScrollRate"] += 0.5
+		else:
+			config.conf["braille"]["autoScrollRate"] = maxRate
+		rate = f"{config.conf['braille']['autoScrollRate']:.1f}"
+		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"] - 0.5 >= minRate:
+			config.conf["braille"]["autoScrollRate"] -= 0.5
+		else:
+			config.conf["braille"]["autoScrollRate"] = minRate
+		rate = f"{config.conf['braille']['autoScrollRate']:.1f}"
+		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

@@ -3449,6 +3449,8 @@ class DocumentNavigationPanel(SettingsPanel):
 	helpId = "DocumentNavigation"
 
 	def makeSettings(self, settingsSizer: wx.BoxSizer) -> None:
+		shouldDebugGui = gui._isDebug()
+		startTime = time.time() if shouldDebugGui else 0
 		sHelper = guiHelper.BoxSizerHelper(self, sizer=settingsSizer)
 		# Translators: This is a label for the paragraph navigation style in the document navigation dialog
 		paragraphStyleLabel = _("&Paragraph style:")
@@ -5456,6 +5458,18 @@ def makeSettings(self, settingsSizer):
 		)
 		self.bindHelpEvent("BrailleSettingsInterruptSpeech", self.brailleInterruptSpeechCombo)
 
+		# Translators: The label for a setting in braille settings to change the rate for autoscroll.
+		autoScrollRateText = _("Auto&matic scroll rate")
+		self.autoScrollRateSlider: nvdaControls.EnhancedInputSlider = sHelper.addLabeledControl(
+			autoScrollRateText,
+			nvdaControls.EnhancedInputSlider,
+			minValue=5,
+			maxValue=100,
+		)
+		self.autoScrollRateSlider.SetValue(int(config.conf["braille"]["autoScrollRate"] * 5))
+		self.autoScrollRateSlider.SetPageSize(2)
+		self.bindHelpEvent("BrailleSettingsAutoScrollRate", self.autoScrollRateSlider)
+
 		if gui._isDebug():
 			log.debug("Finished making settings, now at %.2f seconds from start" % (time.time() - startTime))
 
@@ -5486,6 +5500,8 @@ def onSave(self):
 		]
 		config.conf["braille"]["showMessages"] = self.showMessagesList.GetSelection()
 		config.conf["braille"]["messageTimeout"] = self.messageTimeoutEdit.GetValue()
+		# Values are multiplied by 5, so we can set a smaller difference between consecutive values.
+		config.conf["braille"]["autoScrollRate"] = self.autoScrollRateSlider.GetValue() / 5
 		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

@@ -6,6 +6,7 @@
 
 ### New Features
 
+* Added ability to scroll forward braille automatically. (#18573, @nvdaes)
 * A new command, assigned to `NVDA+x`, has been introduced to repeat the last information spoken by NVDA; pressing it twice shows it in a browseable message. (#625, @CyrilleB79)
 * Added an unassigned command to toggle keyboard layout. (#19211, @CyrilleB79)
 
@@ -21,6 +22,8 @@
 
 Please refer to [the developer guide](https://download.nvaccess.org/documentation/developerGuide.html#API) for information on NVDA's API deprecation and removal process.
 
+* Added an `autoScroll` method to `braille.handler`. (#18573, @nvdaes)
+
 #### Deprecations
 
 <!-- Beyond this point, Markdown should not be linted, as we don't modify old change log sections. -->

user_docs/en/userGuide.md

@@ -2398,6 +2398,20 @@ 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 slider controls the rate of automatic braille display scrolling, measured in cells per second.
+The minimum value (0 %) will be 1 cell per second, and the maximum value (100 %), 20 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, when the session is locked, or when the end of the window is reached.
+
+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).
+When using commands to decrease or increase the scroll rate, instead of the slider, NVDA will report the number of cells for second, not the percentage shown in the slider.
+
 ##### 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.