Add touch based web element navigation in browse mode (#19414)

Closes #3424 

### Summary of the issue:

As noted in the above issue, touch users do not have a dedicated way to
perform browse mode style navigation of web content using touch
gestures.

### Description of user facing changes:

A new Web touch navigation mode has been introduced. When active, touch
gestures allow users to navigate common web elements such as links,
buttons, headings, form fields, landmarks, and other structural elements
in browse mode documents.
This enables touch based navigation that mirrors existing browse mode
navigation commands.
When browse mode is exited, the Web touch mode is automatically removed
and touch navigation returns to its previous behavior.

### Description of developer facing changes:

New touch gesture scripts have been added to invoke existing browse mode
navigation commands. These scripts reuse the existing
BrowseModeTreeInterceptor logic rather than introducing new navigation
implementations.
Supporting logic has been added to track the active browse mode context
and route touch gestures to the appropriate browse mode commands when
available.

### Description of development approach:

This change was implemented by subscribing to browse mode state change
notifications and using them as the authoritative signal for enabling
and disabling web specific touch behavior. The active browse mode tree
interceptor is cached on activation and cleared on deactivation.

### Testing strategy:

Manual testing was performed using touch navigation in multiple browse
mode documents across supported web browsers. Testing verified:
* Automatic activation of Web touch mode when entering browse mode
* Correct removal of Web touch mode when leaving browse mode
* Correct navigation between web elements using touch gestures
* No appearance of Web touch mode in non browse mode contexts

### Known issues with pull request:

None

Author: kefaslungu

source/browseMode.py

@@ -1,7 +1,7 @@
 # A part of NonVisual Desktop Access (NVDA)
 # Copyright (C) 2006-2026 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
 # Joseph Lee, Dawid Pieper, mltony, Bram Duvigneau, Cyrille Bougot, Rob Meredith,
-# Burman's Computer and Education Ltd., Leonard de Ruijter, Łukasz Golonka, Cary-rowen
+# Burman's Computer and Education Ltd., Leonard de Ruijter, Łukasz Golonka, Cary-rowen, Kefas Lungu
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
@@ -215,6 +215,8 @@
 	enableOnPageLoad = boolean(default=true)
 	loadChromiumVBufOnBusyState = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")
 	textParagraphRegex = string(default="{configDefaults.DEFAULT_TEXT_PARAGRAPH_REGEX}")
+	# Element types available for cycling in browse touch mode.
+	browseModeTouchNavigationElements = string_list(default=list("heading", "link", "formField", "list", "table"))
 
 [touch]
 	enabled = boolean(default=true)

source/config/configSpec.py

@@ -4581,12 +4581,7 @@ def script_touch_changeMode(self, gesture):
 		index = (index + 1) % len(touchHandler.availableTouchModes)
 		newMode = touchHandler.availableTouchModes[index]
 		touchHandler.handler._curTouchMode = newMode
-		try:
-			newModeLabel = touchHandler.touchModeLabels[newMode]
-		except KeyError:
-			# Translators: Cycles through available touch modes (a group of related touch gestures; example output: "object mode"; see the user guide for more information on touch modes).
-			newModeLabel = _("%s mode") % newMode
-		ui.message(newModeLabel)
+		ui.message(newMode.displayString)
 
 	@script(
 		# Translators: Input help mode message for a touchscreen gesture.

source/globalCommands.py

@@ -6,7 +6,7 @@
 # Łukasz Golonka, Aaron Cannon, Adriani90, André-Abush Clause, Dawid Pieper,
 # Takuya Nishimoto, jakubl7545, Tony Malykh, Rob Meredith,
 # Burman's Computer and Education Ltd, hwf1324, Cary-rowen, Christopher Proß, Tianze
-# Neil Soiffer, Ryan McCleary.
+# Neil Soiffer, Ryan McCleary, Kefas Lungu.
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
@@ -2662,6 +2662,23 @@ def makeSettings(self, settingsSizer):
 		)
 		self.trapNonCommandGesturesCheckBox.SetValue(config.conf["virtualBuffers"]["trapNonCommandGestures"])
 
+		# browseMode imports gui, which imports from settingsDialogs, so a top-level import
+		# would create a circular dependency. Keep this import lazy.
+		import browseMode
+
+		# Store element types for use in onSave (excludes the always-active "default" entry).
+		self._browseModeElements = list(browseMode.BrowseModeTreeInterceptor._browseTouchNavRegistry)
+		self._browseModeCheckListBox: nvdaControls.CustomCheckListBox = sHelper.addLabeledControl(
+			# Translators: Label for the list of browse mode touch navigation element types in browse mode settings.
+			_("T&ouch navigation elements:"),
+			nvdaControls.CustomCheckListBox,
+			choices=[label for _itemType, label in self._browseModeElements],
+		)
+		self._browseModeCheckListBox.Enable(touchHandler.touchSupported())
+		enabledTypes = set(config.conf["virtualBuffers"]["browseModeTouchNavigationElements"])
+		for i, (itemType, _label) in enumerate(self._browseModeElements):
+			self._browseModeCheckListBox.Check(i, itemType in enabledTypes)
+
 	def onSave(self):
 		config.conf["virtualBuffers"]["maxLineLength"] = self.maxLengthEdit.GetValue()
 		config.conf["virtualBuffers"]["linesPerPage"] = self.pageLinesEdit.GetValue()
@@ -2681,6 +2698,11 @@ def onSave(self):
 		config.conf["virtualBuffers"]["trapNonCommandGestures"] = (
 			self.trapNonCommandGesturesCheckBox.IsChecked()
 		)
+		config.conf["virtualBuffers"]["browseModeTouchNavigationElements"] = [
+			itemType
+			for i, (itemType, _label) in enumerate(self._browseModeElements)
+			if self._browseModeCheckListBox.IsChecked(i)
+		]
 
 
 class MathSettingsPanel(SettingsPanel):

source/gui/settingsDialogs.py

@@ -1,14 +1,23 @@
 # A part of NonVisual Desktop Access (NVDA)
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-# Copyright (C) 2012-2025 NV Access Limited, Joseph Lee, Babbage B.V.
+# Copyright (C) 2012-2026 NV Access Limited, Joseph Lee, Babbage B.V., Kefas Lungu
 
 """handles touchscreen interaction.
 Used to provide input gestures for touchscreens, touch modes and other support facilities.
 In order to use touch features, NVDA must be installed on a touchscreen computer.
 """
 
 import threading
+from functools import cached_property
+from typing import (
+	TYPE_CHECKING,
+	Self,
+)
+
+if TYPE_CHECKING:
+	import browseMode
+
 from ctypes import (
 	byref,
 	Structure,
@@ -43,6 +52,8 @@
 import core
 import systemUtils
 from utils import _deprecate
+from utils.displayString import DisplayStringStrEnum
+from treeInterceptorHandler import post_browseModeStateChange
 
 __getattr__ = _deprecate.handleDeprecations(
 	_deprecate.MovedSymbol(
@@ -51,15 +62,38 @@
 		"SystemMetrics",
 		"MAXIMUM_TOUCHES",
 	),
+	_deprecate.RemovedSymbol(
+		"touchModeLabels",
+		{
+			"text": _("text mode"),
+			"object": _("object mode"),
+			"browse": _("browse mode"),
+		},
+		message="Use touchHandler.TouchMode enum instead.",
+	),
 )
 
 
-availableTouchModes = ["text", "object"]
+class TouchMode(DisplayStringStrEnum):
+	"""Available touch screen navigation modes."""
+
+	TEXT = "text"
+	OBJECT = "object"
+	BROWSE = "browse"
+
+	@cached_property
+	def _displayStringLabels(self) -> dict[Self, str]:
+		return {
+			# Translators: The name of a touch mode.
+			TouchMode.TEXT: _("text mode"),
+			# Translators: The name of a touch mode.
+			TouchMode.OBJECT: _("object mode"),
+			# Translators: The name of a touch mode used when in browse mode.
+			TouchMode.BROWSE: _("browse mode"),
+		}
+
 
-touchModeLabels = {
-	"text": _("text mode"),
-	"object": _("object mode"),
-}
+availableTouchModes: list[TouchMode] = [TouchMode.TEXT, TouchMode.OBJECT]
 
 HWND_MESSAGE = -3
 
@@ -95,6 +129,30 @@
 POINTER_MESSAGE_FLAG_CANCELED = 0x400
 
 
+def _browseModeStateChange(
+	browseMode: bool = False,
+	interceptor: "browseMode.BrowseModeTreeInterceptor | None" = None,
+	**kwargs,
+) -> None:
+	if not handler:
+		return
+
+	if browseMode:
+		# Entering browse mode
+		if TouchMode.BROWSE not in availableTouchModes:
+			availableTouchModes.append(TouchMode.BROWSE)
+
+		handler._curTouchMode = TouchMode.BROWSE
+
+	else:
+		# Leaving browse mode
+		if TouchMode.BROWSE in availableTouchModes:
+			availableTouchModes.remove(TouchMode.BROWSE)
+
+		if handler._curTouchMode == TouchMode.BROWSE:
+			handler._curTouchMode = TouchMode.OBJECT
+
+
 class POINTER_INFO(Structure):
 	_fields_ = [
 		("pointerType", DWORD),
@@ -232,7 +290,7 @@ def getDisplayTextForIdentifier(cls, identifier):
 		# Translators: a touch screen gesture
 		source = _("Touch screen")
 		if mode:
-			source = "{source}, {mode}".format(source=source, mode=touchModeLabels[mode])
+			source = "{source}, {mode}".format(source=source, mode=TouchMode(mode).displayString)
 		return source, " + ".join(actions)
 
 	def _get__immediate(self):
@@ -249,7 +307,7 @@ class TouchHandler(threading.Thread):
 	def __init__(self):
 		self.pendingEmitsTimer = gui.NonReEntrantTimer(core.requestPump)
 		super().__init__(name=f"{self.__class__.__module__}.{self.__class__.__qualname__}")
-		self._curTouchMode = "object"
+		self._curTouchMode = TouchMode.OBJECT
 		self.initializedEvent = threading.Event()
 		self.threadExc = None
 		self.start()
@@ -333,7 +391,7 @@ def setMode(self, mode):
 
 	def pump(self):
 		for preheldTracker, tracker in self.trackerManager.emitTrackers():
-			gesture = TouchInputGesture(preheldTracker, tracker, self._curTouchMode)
+			gesture = TouchInputGesture(preheldTracker, tracker, self._curTouchMode.value)
 			try:
 				inputCore.manager.executeGesture(gesture)
 			except inputCore.NoInputGestureAction:
@@ -408,12 +466,14 @@ def initialize():
 		% user32.GetSystemMetrics(SystemMetrics.MAXIMUM_TOUCHES),
 	)
 	config.post_configProfileSwitch.register(handlePostConfigProfileSwitch)
+	post_browseModeStateChange.register(_browseModeStateChange)
 	setTouchSupport(config.conf["touch"]["enabled"])
 
 
 def terminate():
 	global handler
 	config.post_configProfileSwitch.unregister(handlePostConfigProfileSwitch)
+	post_browseModeStateChange.unregister(_browseModeStateChange)
 	if handler:
 		handler.terminate()
 		handler = None

source/touchHandler.py

@@ -47,8 +47,6 @@
 	"column break",
 	"background pattern {pattern}",
 	"NVDA Speech Viewer",
-	"text mode",
-	"object mode",
 	"NonVisual Desktop Access",
 	"A free and open source screen reader for Microsoft Windows",
 	"Copyright (C) {years} NVDA Contributors",

tests/checkPot.py

@@ -16,6 +16,9 @@
 * 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)
 * Added an unassigned Quick Navigation Command for jumping to next/previous slider in browse mode. (#17005, @hdzrvcc0X74)
+* Added touch based navigation of browse mode elements, allowing touch screen users to move between links, headings, form fields, lists, tables and other quick navigation elements. (#3424, @kefaslungu)
+  * Flick down or up to cycle through element types; flick right or left to navigate between elements of the selected type.
+  * The element types shown when cycling can be configured in the Browse Mode settings panel.
 * Added support for custom speech dictionaries. (#19558, #17468, @LeonarddeR)
   * Dictionaries can be provided in the `speechDicts` folder in an add-on package.
   * Dictionary metadata can be added to an optional `speechDictionaries` section in the add-on manifest.

user_docs/en/changes.md

@@ -613,13 +613,13 @@ Therefore, gestures such as 2-finger flick up and 4-finger flick left are all po
 #### Touch Modes {#TouchModes}
 
 As there are many more NVDA commands than possible touch gestures, NVDA has several touch modes you can switch between which make certain subsets of commands available.
-The two modes are text mode and object mode.
+The three modes are text mode, object mode and browse mode.
 Certain NVDA commands listed in this document may have a touch mode listed in brackets after the touch gesture.
 For example, flick up (text mode) means that the command will be performed if you flick up, but only while in text mode.
 If the command does not have a mode listed, it will work in any mode.
 
 <!-- KC:beginInclude -->
-To toggle touch modes, perform a 3-finger tap.
+To switch between touch modes, perform a 3-finger tap.
 <!-- KC:endInclude -->
 
 #### Touch keyboard {#TouchKeyboard}
@@ -1064,6 +1064,38 @@ If you want to use these while still being able to use your cursor keys to read
 To toggle single letter navigation on and off for the current document, press NVDA+shift+space.
 <!-- KC:endInclude -->
 
+#### Touch Navigation in Browse Mode {#BrowseModeTouch}
+
+When using a touch enabled device, NVDA provides an additional touch navigation mode for browsing content in browse mode.
+
+When browse mode is active in supported documents such as web pages or Word documents, NVDA can expose a browse touch mode.
+This mode allows users to navigate structural elements of a document using touch gestures, similar to browse mode navigation with the keyboard.
+
+In browse touch mode, flick gestures are used to move between common document elements such as links, buttons, headings, form fields, landmarks, and other document structures.
+
+This feature is intended to provide touch users with efficient, structured navigation that mirrors existing browse mode functionality.
+
+##### Touch gestures in browse mode
+
+<!-- KC:beginInclude -->
+
+| Name | Touch | Description |
+|---|---|---|
+| Select next element type | flick down | Switches to the next browse mode navigation element type |
+| Select previous element type | flick up | Switches to the previous browse mode navigation element type |
+| Move to next element | flick right | Moves to the next browse mode element of the selected type |
+| Move to previous element | flick left | Moves to the previous browse mode element of the selected type |
+
+<!-- KC:endInclude -->
+
+When the "default" element type is selected, flicking left or right moves through all elements in the document.
+When any other element type is selected, flicking left or right moves to the previous or next element of that type.
+Flicking up or down cycles through the available element types.
+
+The selected element type is remembered separately for each document while it remains open.
+Note that browse touch mode gestures only take effect when browse mode is active in the document.
+If focus moves outside the document (for example, to the browser address bar or the taskbar), browse touch mode gestures will not navigate the document until focus returns to it in browse mode.
+
 #### Text paragraph navigation command {#TextNavigationCommand}
 
 You can jump to the next or previous text paragraph by pressing `p` or `shift+p`.
@@ -3317,6 +3349,15 @@ Enabled by default, this option allows you to choose if gestures (such as key pr
 As an example, if enabled and the letter j was pressed, it would be trapped from reaching the document, even though it is not a quick navigation command nor is it likely to be a command in the application itself.
 In this case NVDA will tell Windows to play a default sound whenever a key which gets trapped is pressed.
 
+##### Browse mode touch navigation elements {#BrowseModeSettingsBrowseModeNavigationElements}
+
+This list allows you to choose which element types are available when cycling through elements in browse touch mode.
+Use the checkboxes to enable or disable individual element types.
+Only the checked element types will appear when flicking up or down to cycle through browse mode navigation elements.
+This setting only affects touch navigation and has no effect on keyboard browse mode navigation.
+
+Available element types are those available from [single letter navigation](#SingleLetterNavigation).
+
 #### Document Formatting {#DocumentFormattingSettings}
 
 <!-- KC:setting -->