Add touch based web element navigation in browse mode by kefaslungu · Pull Request #19414 · nvaccess/nvda

kefaslungu · 2026-01-03T17:15:19Z

Link to issue number:

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

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.

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

…mode

seanbudd · 2026-02-03T04:29:08Z

@kefaslungu - do you intend to finish this?

kefaslungu · 2026-02-03T08:44:32Z

Hi @seanbudd ,

It is now ready for review. I've decided to send another PR for the remaining features discussed at #3424

SaschaCowley

Welcome @kefaslungu! Thanks for opening your first PR for NVDA!

There are a few things in here that have me concerned, but overall I really like the direction you're going.

SaschaCowley · 2026-02-06T04:12:15Z

source/globalCommands.py

+		"default",
+		"link",
+		"button",
+		"form field",
+		"heading",
+		"frame",
+		"table",
+		"list",
+		"graphic",
+		"landmark",


These all need to be made translateable, since they're used in the UI. For example

# Translators: An element type in browse mode. "link",

SaschaCowley · 2026-02-06T04:12:15Z

source/globalCommands.py

+	browseModeCommands = (
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextLink,
+			browseMode.BrowseModeTreeInterceptor.script_previousLink,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextButton,
+			browseMode.BrowseModeTreeInterceptor.script_previousButton,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextFormField,
+			browseMode.BrowseModeTreeInterceptor.script_previousFormField,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextHeading,
+			browseMode.BrowseModeTreeInterceptor.script_previousHeading,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextFrame,
+			browseMode.BrowseModeTreeInterceptor.script_previousFrame,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextTable,
+			browseMode.BrowseModeTreeInterceptor.script_previousTable,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextList,
+			browseMode.BrowseModeTreeInterceptor.script_previousList,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextGraphic,
+			browseMode.BrowseModeTreeInterceptor.script_previousGraphic,
+		),
+		(
+			browseMode.BrowseModeTreeInterceptor.script_nextLandmark,
+			browseMode.BrowseModeTreeInterceptor.script_previousLandmark,
+		),
+	)


These can be constructed dynamically.

nvda/source/browseMode.py

Lines 605 to 607 in 8dbe0fd

scriptSuffix = itemType[0].upper() + itemType[1:]

scriptName = "next%s" % scriptSuffix

funcName = "script_%s" % scriptName

SaschaCowley · 2026-02-06T04:12:15Z

source/globalCommands.py

+	@scriptHandler.script(
+		description="Select next web navigation element",
+		gesture="ts(Web):flickDown",
+	)
+	def script_nextWebElement(self, gesture):
+		ti = api.getNavigatorObject().treeInterceptor
+		if not isinstance(ti, browseMode.BrowseModeTreeInterceptor):
+			return
+
+		self.webBrowseMode = (self.webBrowseMode + 1) % len(self.webElements)
+		ui.message(self.webElements[self.webBrowseMode])
+
+	@scriptHandler.script(
+		description="Select previous web navigation element",
+		gesture="ts(Web):flickUp",
+	)
+	def script_prevWebElement(self, gesture):
+		ti = api.getNavigatorObject().treeInterceptor
+		if not isinstance(ti, browseMode.BrowseModeTreeInterceptor):
+			return
+
+		self.webBrowseMode = (self.webBrowseMode - 1) % len(self.webElements)
+		ui.message(self.webElements[self.webBrowseMode])
+
+	@scriptHandler.script(gesture="ts(Web):flickRight")
+	def script_nextSelectedElement(self, gesture):
+		ti = api.getNavigatorObject().treeInterceptor
+		if not isinstance(ti, browseMode.BrowseModeTreeInterceptor):
+			return
+
+		if self.webBrowseMode == 0:
+			self.script_navigatorObject_nextInFlow(gesture)
+		else:
+			nextScript, _ = self.browseModeCommands[self.webBrowseMode - 1]
+			nextScript(ti, gesture)
+
+	@scriptHandler.script(gesture="ts(Web):flickLeft")
+	def script_prevSelectedElement(self, gesture):
+		ti = api.getNavigatorObject().treeInterceptor
+		if not isinstance(ti, browseMode.BrowseModeTreeInterceptor):
+			return
+
+		if self.webBrowseMode == 0:
+			self.script_navigatorObject_previousInFlow(gesture)
+		else:
+			_, prevScript = self.browseModeCommands[self.webBrowseMode - 1]
+			prevScript(ti, gesture)


You need to make the descriptions for all of these scripts translatable. Also add the browse mode category to the scripts.

SaschaCowley · 2026-02-06T04:12:15Z

source/touchHandler.py

+	if browseMode:
+		# Entering browse mode
+		if webModeName not in availableTouchModes:
+			availableTouchModes.append(webModeName)


You also need to add this, and a corresponding translatable name, to touchModeLabels . This doesn't need to be done dynamically.

has this comment from sascha been addressed? https://github.com/nvaccess/nvda/pull/19414/files#r2772194150

source/globalCommands.py

josephsl · 2026-02-07T13:26:20Z

Hi,

I am the original creator of the parts of the code reviewed in this pull request discussion. Kefas has adopted it to NVDA Core expectations and structure.

The comment on implementation in the global commands module can be explained by the fact that the code and the idea behind it comes from an add-on (Enhanced Touch Gestures). The add-on used a global plugin class to house list of navigable elements, browse mode script calls, and the gesture to cycle between web elements. Our (Kefas and I) plan is to adopt Enhanced Touch Gestures add-on based on the pull request code structure and make changes based on review comments, with the end goal of removing web mode from the add-on in favor of NVDA Core version.

Thanks for reviewing Kefas' pull request.

… element registration and settings Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

kefaslungu · 2026-02-19T03:32:37Z

Hi all,

I've made some changes as follows:

Moved all web touch navigation scripts from GlobalCommands into BrowseModeTreeInterceptor, with category=inputCore.SCRCAT_BROWSEMODE and translatable descriptions.
Dynamic element registration: addQuickNav now accepts includeInWebTouch=True and auto-registers each element type into _webTouchNavRegistry. _webBrowseElements is built from this registry after all qn() calls, so future NVDA element types appear automatically with no manual updates. Heading sub-types (heading1–9) are excluded via includeInWebTouch=False.
Settings: Added a sub-section to BrowseModePanel (one per element type) to control which types appear when cycling.

SaschaCowley

Heading in the right direction, but still needs some work. Good progress though :)

source/config/configSpec.py

source/gui/settingsDialogs.py

source/browseMode.py

source/globalCommands.py

source/touchHandler.py

source/browseMode.py

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

…mode # Conflicts: # source/gui/settingsDialogs.py

kefaslungu · 2026-02-23T01:19:31Z

Hi @SaschaCowley,

Thanks for the detailed review! I've addressed all the feedback as follows:

Replaced all the 37 boolean config keys with a single string_list.
Replaced individual checkboxes with CustomCheckListBox.
Added explicit translatable touchLabel to every addQuickNav call, removing the camelCase derivation.
Heading levels (1–9) are now registered with their own touch labels rather than excluded.
_webBrowseCurrentType is now an instance attribute.
Renamed includeInWebTouch → availableInWebTouch.

All that is left now is documentation, but I'll do that as soon as the code is approved.

Cheers!

user_docs/en/userGuide.md

source/gui/settingsDialogs.py

source/touchHandler.py

Copilot

Pull request overview

This PR implements touch-based navigation for web elements in browse mode, addressing issue #3424 from 2013. The feature introduces a new "web" touch mode that allows touchscreen users to navigate structural elements (links, headings, form fields, etc.) using touch gestures, providing an experience similar to keyboard-based browse mode navigation.

Changes:

Adds a "web" touch mode that activates automatically when entering browse mode
Implements four touch gestures for cycling through and navigating between element types (flick up/down to select element type, left/right to navigate)
Provides GUI settings to configure which element types are available for touch navigation
Includes comprehensive user documentation explaining the new feature

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
user_docs/en/userGuide.md	Adds documentation for the new web touch mode, including a table of gestures and usage explanations
user_docs/en/changes.md	Adds changelog entry describing the new feature
source/touchHandler.py	Implements browse mode state change handler to add/remove web mode and switch to it automatically
source/gui/settingsDialogs.py	Adds UI controls for selecting which web elements are available in touch navigation
source/config/configSpec.py	Adds configuration option for web touch navigation elements with sensible defaults
source/browseMode.py	Implements core touch navigation scripts, element cycling logic, and registry system for available elements

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

source/browseMode.py

user_docs/en/userGuide.md

source/touchHandler.py

user_docs/en/userGuide.md

source/browseMode.py

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

…mode

kefaslungu · 2026-02-27T01:47:53Z

Hi @seanbudd,

All requested changes has been made, please take a look.

source/browseMode.py

seanbudd · 2026-02-27T04:25:08Z

source/browseMode.py

+		@param availableInWebTouch: If True, register this element type for web touch navigation cycling.
+			Set to False to exclude an element type entirely from web touch navigation.
+		@param touchLabel: A short, translated, plural label for this element type used in web touch navigation
+			cycling (e.g. C{_("links")}). Required when C{availableInWebTouch} is True.


Please see the coding standards for more information.

Suggested change

@param availableInWebTouch: If True, register this element type for web touch navigation cycling.

Set to False to exclude an element type entirely from web touch navigation.

@param touchLabel: A short, translated, plural label for this element type used in web touch navigation

cycling (e.g. C{_("links")}). Required when C{availableInWebTouch} is True.

:param availableInWebTouch: If True, register this element type for web touch navigation cycling.

Set to False to exclude an element type entirely from web touch navigation.

:param touchLabel: A short, translated, plural label for this element type used in web touch navigation

cycling (e.g. ``_("links")``). Required when ``availableInWebTouch`` is True.

source/browseMode.py

seanbudd · 2026-02-27T04:26:10Z

source/browseMode.py

+
+	#: The itemType currently selected for web touch navigation. None means "default" (all content).
+	#: Stored as an instance attribute so each document remembers its own preference.
+	_webBrowseCurrentType: Optional[str] = None


use | None syntax

source/touchHandler.py

user_docs/en/userGuide.md

seanbudd · 2026-02-27T04:30:14Z

source/touchHandler.py

+	if browseMode:
+		# Entering browse mode
+		if webModeName not in availableTouchModes:
+			availableTouchModes.append(webModeName)


has this comment from sascha been addressed? https://github.com/nvaccess/nvda/pull/19414/files#r2772194150

source/browseMode.py

seanbudd · 2026-02-27T04:32:08Z

source/browseMode.py

+			"Selects the previous element type for web touch navigation",
+		),
+		category=inputCore.SCRCAT_BROWSEMODE,
+		gesture="ts(Web):flickUp",


Suggested change

gesture="ts(Web):flickUp",

gesture="ts(web):flickUp",

source/browseMode.py

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

kefaslungu · 2026-02-27T16:59:07Z

Hi @seanbudd,

All suggestions have been addressed.

kefaslungu and others added 5 commits January 3, 2026 15:35

Added Web navigation to core

b6fd89a

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

Pre-commit auto-fix

b4e9bd4

Added relevant user documentation and changes

62eb77f

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

Added name

daf47b4

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

Merge branch 'webmode' of https://github.com/kefaslungu/nvda into web…

8fe2f73

…mode

seanbudd added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Jan 6, 2026

kefaslungu marked this pull request as ready for review February 3, 2026 08:41

kefaslungu requested review from a team as code owners February 3, 2026 08:41

kefaslungu requested review from Qchristensen and SaschaCowley February 3, 2026 08:41

SaschaCowley requested changes Feb 6, 2026

View reviewed changes

SaschaCowley reviewed Feb 6, 2026

View reviewed changes

source/globalCommands.py Show resolved Hide resolved

Move web touch navigation into BrowseModeTreeInterceptor with dynamic…

82043fa

… element registration and settings Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

kefaslungu and others added 2 commits February 19, 2026 03:47

Merge branch 'master' into webmode

6030aba

Pre-commit auto-fix

de05928

seanbudd assigned SaschaCowley Feb 19, 2026

kefaslungu requested a review from SaschaCowley February 19, 2026 16:49

SaschaCowley requested changes Feb 20, 2026

View reviewed changes

SaschaCowley marked this pull request as draft February 20, 2026 08:13

kefaslungu and others added 3 commits February 23, 2026 02:02

Addressed reviewer's comments

266c625

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

Merge branch 'webmode' of https://github.com/kefaslungu/nvda into web…

6a93eed

…mode # Conflicts: # source/gui/settingsDialogs.py

Pre-commit auto-fix

a68cdf3

kefaslungu requested a review from SaschaCowley February 23, 2026 01:19

kefaslungu marked this pull request as ready for review February 23, 2026 01:20

seanbudd requested a review from Copilot February 26, 2026 00:31

Copilot started reviewing on behalf of seanbudd February 26, 2026 00:32 View session

seanbudd reviewed Feb 26, 2026

View reviewed changes

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

source/gui/settingsDialogs.py Show resolved Hide resolved

source/touchHandler.py Outdated Show resolved Hide resolved

source/touchHandler.py Outdated Show resolved Hide resolved

seanbudd marked this pull request as draft February 26, 2026 00:36

Copilot AI reviewed Feb 26, 2026

View reviewed changes

kefaslungu added 2 commits February 27, 2026 02:39

Added documentation and minor fixes

d670765

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

Merge branch 'webmode' of https://github.com/kefaslungu/nvda into web…

3707430

…mode

seanbudd reviewed Feb 27, 2026

View reviewed changes

Fix type hint where necessary

4052b06

Signed-off-by: kefaslungu <jameskefaslungu@gmail.com>

kefaslungu requested a review from seanbudd February 27, 2026 16:59

kefaslungu marked this pull request as ready for review February 27, 2026 17:00

	scriptSuffix = itemType[0].upper() + itemType[1:]
	scriptName = "next%s" % scriptSuffix
	funcName = "script_%s" % scriptName

Uh oh!

Conversation

kefaslungu commented Jan 3, 2026 • 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!

seanbudd commented Feb 3, 2026

Uh oh!

kefaslungu commented Feb 3, 2026

Uh oh!

SaschaCowley 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!

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!

josephsl commented Feb 7, 2026

Uh oh!

kefaslungu commented Feb 19, 2026

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kefaslungu commented Feb 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kefaslungu commented Feb 27, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kefaslungu commented Jan 3, 2026 •

edited

Loading