Gestures to pan screen with arrows #19478

Boumtchack · 2026-01-20T15:55:42Z

Link to issue number:

Fixes #19471

Summary of the issue:

Users who doesn't use mouse were needing a way to move the screen

Description of user facing changes:

8 new gestures to learn for panning magnifier window

Description of developer facing changes:

N/A

Description of development approach:

Creating a new class function that will move the magnifier window center based on the direction choosed
Implementing list variable with xmin/xmax/ymin/ymax, that will update based on zoom level. This is used to know when window reached the edge.

Adding 8 new gestures:

left, top, right, bottom of a customisable panning value
left, top right, bottom to edge of the screen.

Testing strategy:

Manual test of each gestures
unit tests

Known issues with pull request:

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.

Boumtchack · 2026-01-20T15:58:34Z

I implemented NVDA+alt+arrows gestures for step by step panning, the values can be changed, there is a min/max/step variables that can be modified.
for the go to the edge the gestures are NVDA+shift+alt+arrows.

I choosed to force the mouse to stay in the middle of the magnifier window so if someone decides to move it, there won't be a sudden jump of the window.

I'm open to any modifications

Copilot

Pull request overview

This PR adds keyboard gestures for panning the magnifier screen, allowing users who don't use a mouse to navigate the magnified view. The implementation includes customizable pan values and edge detection for boundary awareness.

Changes:

Added 8 new keyboard gestures (4 directional pans + 4 edge pans) with NVDA+Alt+Arrow combinations
Introduced configurable pan value setting with range from 10-100 pixels
Implemented pan margin calculation and boundary detection logic

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
source/config/configSpec.py	Adds defaultPanValue configuration option with min/max constraints
source/_magnifier/config.py	Implements PanValue class with pan_range and pan_strings methods, plus getter/setter functions
source/_magnifier/magnifier.py	Adds _panValue field, setPanMarginBorder method, and _pan method for panning logic
source/_magnifier/utils/types.py	Defines 8 new MagnifierAction enum values for pan operations
source/_magnifier/commands.py	Implements 8 command functions for panning operations with user feedback
source/globalCommands.py	Registers 8 script handlers with keyboard gesture bindings
source/gui/settingsDialogs.py	Adds pan value dropdown to magnifier settings panel

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

source/_magnifier/magnifier.py

source/_magnifier/commands.py

source/_magnifier/utils/types.py

source/_magnifier/magnifier.py

source/_magnifier/config.py

source/gui/settingsDialogs.py

source/_magnifier/commands.py

seanbudd · 2026-01-21T04:52:15Z

Please fill out the PR description in full and address CoPilot's review

cary-rowen · 2026-01-21T07:34:42Z

Do these really need four default gestures?

CyrilleB79 · 2026-01-21T07:55:57Z

Do these really need four default gestures?

IMO yes. These commands are mandatory for any Magnifier user who does not use the mouse. IMO these gestures are much more useful than than gestures to toggle focus tracking mode or to cycle through filters.

What would you suggest instead? Leave them unassigned, or something else?

seanbudd

Thanks @Boumtchack - this is just a partial review. Would also like @CyrilleB79's thoughts around panning grain

source/_magnifier/commands.py

source/_magnifier/magnifier.py

source/config/configSpec.py

source/_magnifier/config.py

source/gui/settingsDialogs.py

source/globalCommands.py

CyrilleB79 · 2026-01-22T12:47:14Z

I have done some tests on this PR.

The paning commands work until the first focus change or the first caret move after the Magnifier is started. After that, they do not work anymore. This critical bug make them unuseful in practice.
Being able to define the panning step size seems quite quite interesting, even if I do not remember to have seen this possibility in other magnifiers. I wonder though if it wouldn't be more interesting and useful to define it depending on how much the view is zoomed. E.g. step from 1% to 90% of the zoomed view; this way, I expect that the distance jumped on the magnified view be always the same, helping the eyes to jump at the right place (may be especially useful when user has difficulty to follow movements on screen due to narrow field of vision).
Since these commands may be used quite frequently / repeatedly, they are quite verbose. Saying "Panning right" when you pan right does not provide any useful information, since as a user, I already know that I have pressed right arrow key; a user who needs confirmation that they have pressed the correct key can already enable "Echo command keys". My recommendations regarding command feedback would be that when pressing any panning (or jump to edge) command:

If the magnified view is actually being moved, just a slight beep confirms that the command has been executed
if the view does not move when the command has been called due to the fact that it has reached the edge of the screen, a different beep (louder / longer) to inform the user that the view cannot be moved. Alternatively, reporting "Left edge" / "Top edge" / etc. is nice too.

Wording: What about using "Pan the magnified view" instead of "Pan the magnifier"? This seems clearer to me.

source/_magnifier/utils/types.py

Boumtchack · 2026-01-26T14:59:12Z

The paning commands work until the first focus change or the first caret move after the Magnifier is started. After that, they do not work anymore. This critical bug make them unuseful in practice.

I have tried getting this problem but it works fine for me, have you some settings that are not default that could be the reason of this issue?

Being able to define the panning step size seems quite quite interesting, even if I do not remember to have seen this possibility in other magnifiers. I wonder though if it wouldn't be more interesting and useful to define it depending on how much the view is zoomed. E.g. step from 1% to 90% of the zoomed view; this way, I expect that the distance jumped on the magnified view be always the same, helping the eyes to jump at the right place (may be especially useful when user has difficulty to follow movements on screen due to narrow field of vision).

If I understand correctly, it we would change the pan steps value by a % step value so it feels the same for the user regardless of the zoom level?
so the settings would be replace by a % that allows me to calculate the real step value for the panning

Since these commands may be used quite frequently / repeatedly, they are quite verbose. Saying "Panning right" when you pan right does not provide any useful information, since as a user, I already know that I have pressed right arrow key; a user who needs confirmation that they have pressed the correct key can already enable "Echo command keys". My recommendations regarding command feedback would be that when pressing any panning (or jump to edge) command:

If the magnified view is actually being moved, just a slight beep confirms that the command has been executed

if the view does not move when the command has been called due to the fact that it has reached the edge of the screen, a different beep (louder / longer) to inform the user that the view cannot be moved. Alternatively, reporting "Left edge" / "Top edge" / etc. is nice too.

I guess there is a default bip sound for the good execution of a command? also I've tried to hold the command to pan at 1px and it sounds awfull, I don't know if having a bip would be better, but maybe no one will just hold down the panning command.

I would still keep the arrived to edge ones

Wording: What about using "Pan the magnified view" instead of "Pan the magnifier"? This seems clearer to me.

yes I don't mind that

CyrilleB79 · 2026-01-26T21:34:26Z

The paning commands work until the first focus change or the first caret move after the Magnifier is started. After that, they do not work anymore. This critical bug make them unuseful in practice.

I have tried getting this problem but it works fine for me, have you some settings that are not default that could be the reason of this issue?

I do not think so: I have tested with a brand new NVDA config with only few changes.
But I seem to have found why you cannot reproduce. You probably use the mouse, while I do not use it at all. Moving the mouse allow to make panning commands work again. Unfortunately, panning command would be actually the most useful for people like myself who do not use the mouse at all.

Being able to define the panning step size seems quite quite interesting, even if I do not remember to have seen this possibility in other magnifiers. I wonder though if it wouldn't be more interesting and useful to define it depending on how much the view is zoomed. E.g. step from 1% to 90% of the zoomed view; this way, I expect that the distance jumped on the magnified view be always the same, helping the eyes to jump at the right place (may be especially useful when user has difficulty to follow movements on screen due to narrow field of vision).

If I understand correctly, it we would change the pan steps value by a % step value so it feels the same for the user regardless of the zoom level? so the settings would be replace by a % that allows me to calculate the real step value for the panning

Yes, exact.

Since these commands may be used quite frequently / repeatedly, they are quite verbose. Saying "Panning right" when you pan right does not provide any useful information, since as a user, I already know that I have pressed right arrow key; a user who needs confirmation that they have pressed the correct key can already enable "Echo command keys". My recommendations regarding command feedback would be that when pressing any panning (or jump to edge) command:

If the magnified view is actually being moved, just a slight beep confirms that the command has been executed

if the view does not move when the command has been called due to the fact that it has reached the edge of the screen, a different beep (louder / longer) to inform the user that the view cannot be moved. Alternatively, reporting "Left edge" / "Top edge" / etc. is nice too.

I guess there is a default bip sound for the good execution of a command?

Do you mean in NVDA in general? (the answer is no) Or just about panning commands? (I cannot hear them; can you point in the code where it is located).

Maybe we should first wait this PR to be merged and have people experimenting with it before we decide what the most desirable audio feedback upon panning commands would be.

also I've tried to hold the command to pan at 1px and it sounds awfull, I don't know if having a bip would be better, but maybe no one will just hold down the panning command.

Yes, when I set step to 1px and hold panning keys pressed, I just hear the beginning of the word "Panning" repeated again and again, what is not very desirable.

With windows Magnifier + Windows Magnifier add-on, I sometimes hold panning keys (control+alt+arrows) to go faster. So with Windows Magnifier, it was clearly a real use case. I have configured Windows Magnifier feedback to beep on panning commands. It gives useful information. But I agree that:

the audio experience could probably be improved
holding panning commands has the downside that due to how key repetition works in Windows, you have the first step somewhat isolated and then a series of more frequent steps. That's probably not the best UX.

Alternatively, one can imagine the Zoomtext panning command approach which is much nicer from UX point of view.

Press NVDA+alt+leftArrow and maintain NVDA+alt modifiers down.
- The view pans left continuously (as long as you keep modifiers down)
Still keeping NVDA+alt modifiers down, press once again left arrow.
- The view pans left continuously (as long as you keep modifiers down), with a panning speed twice the panning speed at step 1.
Still keeping NVDA+alt modifiers down, press right arrow.
- The view pans left continuously (as long as you keep modifiers down), with a panning speed equal to the panning speed at step 1.
Release NVDA+alt modifiers
- Panning stops

That's an example and steps 2 and 3 can be omitted, or can also be repeated to increase or decrease the panning speed.

Though, such key commands may not fit well easily with NVDA input gestures system. So if possible, this may be thought and discussed in a separate subsequent issue and PR.

I would still keep the arrived to edge ones

Do you mean that you would keep the spoken message?
It's OK for me. I'd prefer the shorter "Left edge", "Top edge", etc. It seems to me that NVDA often tries to be short and efficient in its feedback messages.

Boumtchack · 2026-01-27T10:52:43Z

I think the audio issue could be discussed more thoroughly in an other PR with a proper issue.

I came accross an other problem, in my opinion is that if we deal with percents, panning top and right won't have the same value as screens are not squares, so it might feel a little weird.
Maybe I could calculate the value only based on width or height of screen.

For the message I changed it to "at top edge" as suggested by Sean

CyrilleB79 · 2026-01-27T12:07:07Z

I came accross an other problem, in my opinion is that if we deal with percents, panning top and right won't have the same value as screens are not squares, so it might feel a little weird. Maybe I could calculate the value only based on width or height of screen.

You raise a good point. I agree that the panning step should be the same vertically and horizontally. So IMO, use zoom level (or only one dimension) to compute the size of a step. The idea is that the size of the step should vary in inverse proportion with the zoom level.

Boumtchack · 2026-01-27T16:23:08Z

So I mannaged to go without having problem without markdownlint-cli2 in the pre commit, but I guess it's over now.
I tried to install it again without success, I broke the build and had to reinstall all the environement due to bad manipulation.

that's why the last commits are pretty much empty.

I'm still working on a fix.

sorry for the inconvenience

seanbudd · 2026-01-28T05:04:43Z

Hey @Boumtchack - you can skip jobs temporarily with pre-commit by setting SKIP as an environment variable

e.g.

PowerShell: $env:SKIP="markdownlint-cli2"; pre-commit run --all-files
Bash: SKIP=markdownlint-cli2 pre-commit run --all-files
Cmd: set "SKIP=markdownlint-cli2" && pre-commit run --all-files

Boumtchack · 2026-01-28T08:51:15Z

Ok but the problem, as for my last commit, the pre-commit.ci fails. And if I can run it on my computer, it actually changes the files that needs to be change and I do a clean commit after that.

From github I just get a log that is not really usefull

@CyrilleB79 if maybe you could pull last changes and run the markdownlint-cli2 for me it would be great, so all the test will pass.

CyrilleB79 · 2026-01-28T13:53:47Z

@Boumtchack I cannot probably push in your branch.

In any case, I have checked out the branch of this PR locally and run markdownlint-cli2 and there is no error.

I do not know why the test is failed, nor how to help you. Sorry.

seanbudd · 2026-01-30T01:08:55Z

@Boumtchack - could you ask the admins of France-Travail to set up pre-commit CI for your fork? that way it can fix things automatically when you push changes to your fork. I think it will save you a lot of headaches in the long term

seanbudd

another partial review - please make sure to review the diff and ensure everything is as expected before marking as ready

seanbudd · 2026-01-30T01:12:26Z

source/_magnifier/commands.py

+		if reachedEdge:
+			ui.message(
+				pgettext(
+					"magnifier",
+					# Translators: Message announced when arriving at the left edge.
+					"At left edge",
+				),
+			)
+		else:
+			ui.message(
+				pgettext(
+					"magnifier",
+					# Translators: Message announced when panning left.
+					"Panning left",
+				),
+			)


I agree with cyrille that this is currently too verbose. Lets just report when we hit the edge

Suggested change

if reachedEdge:

ui.message(

pgettext(

"magnifier",

# Translators: Message announced when arriving at the left edge.

"At left edge",

),

)

else:

ui.message(

pgettext(

"magnifier",

# Translators: Message announced when panning left.

"Panning left",

),

)

if reachedEdge:

ui.message(

pgettext(

"magnifier",

# Translators: Message announced when arriving at the left edge.

"left edge",

),

)

seanbudd · 2026-01-30T01:13:07Z

source/_magnifier/fullscreenMagnifier.py

@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2025 NV Access Limited, Antoine Haffreingue
+# Copyright (C) 2025-2026 NV Access Limited, Antoine Haffreingue


you generally don't need to update copyright headers unless you edit the file

seanbudd · 2026-01-30T01:13:44Z

source/config/configSpec.py

 # Magnifier settings
 [magnifier]
 	defaultZoomLevel = float(min=1.0, max=10.0, default=2.0)
+	defaultPanValue = integer(min=1, max=100, default=10)


Suggested change

defaultPanValue = integer(min=1, max=100, default=10)

defaultPanStep = integer(min=1, max=100, default=10)

seanbudd · 2026-01-30T01:13:57Z

source/_magnifier/config.py

 	config.conf["magnifier"]["defaultZoomLevel"] = zoomLevel


+def getDefaultPanValue() -> int:


Suggested change

def getDefaultPanValue() -> int:

def getDefaultPanStep() -> int:

seanbudd · 2026-01-30T01:14:09Z

source/_magnifier/config.py

+	return config.conf["magnifier"]["defaultPanValue"]
+
+
+def setDefaultPanValue(panValue: int) -> None:


Suggested change

def setDefaultPanValue(panValue: int) -> None:

def setDefaultPanStep(panStep: int) -> None:

seanbudd · 2026-01-30T01:15:06Z

user_docs/en/userGuide.md

@@ -20,40 +20,40 @@ A short video demonstration, ["What is NVDA?"](https://www.youtube.com/watch?v=t



this entire file was erroneously reformatted. Please undo the massive reformat and ensure you have only updated the user guide to add information about panning

seanbudd · 2026-01-30T01:15:25Z

tests/unit/nvda.ini.corrupted.bak

@@ -0,0 +1 @@
+schemaVersion = 20


this file should not have been committed

seanbudd · 2026-01-30T01:16:01Z

source/gui/settingsDialogs.py

+			max=100,
+		)
+		self.bindHelpEvent(
+			"magnifierDefaultPan",


Suggested change

"magnifierDefaultPan",

"MagnifierPanStep",

Boumtchack added 2 commits January 20, 2026 16:19

Gestures to pan screen with arrows

cd65eaa

pre-commit

2258cec

Boumtchack marked this pull request as ready for review January 20, 2026 16:13

Boumtchack requested a review from a team as a code owner January 20, 2026 16:13

Boumtchack requested review from SaschaCowley and Copilot January 20, 2026 16:13

Copilot started reviewing on behalf of Boumtchack January 20, 2026 16:13 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

seanbudd requested review from seanbudd and removed request for SaschaCowley January 21, 2026 04:51

seanbudd marked this pull request as draft January 21, 2026 04:51

Boumtchack and others added 3 commits January 21, 2026 09:41

Merge branch 'master' into zoomPanningGesture

2f0d8a0

copilot review + unit test

7a77b6f

pre-commit

14227e1

Boumtchack marked this pull request as ready for review January 21, 2026 14:25

seanbudd reviewed Jan 22, 2026

View reviewed changes

CyrilleB79 reviewed Jan 22, 2026

View reviewed changes

source/_magnifier/utils/types.py Outdated Show resolved Hide resolved

seanbudd marked this pull request as draft January 23, 2026 00:32

Merge branch 'nvaccess:master' into zoomPanningGesture

a7b0e63

Boumtchack added 2 commits January 26, 2026 16:41

review modification

c3eee24

pre-commit

6128894

Merge branch 'nvaccess:master' into zoomPanningGesture

88cebfd

Boumtchack added 5 commits January 27, 2026 13:43

fixed panning, changed to %

7d48d1b

pre-commit

984ec51

added 2026 in descriptions

8c91c72

added 2026 in descriptions

3f6ffcc

pre-commit

608552d

Boumtchack marked this pull request as ready for review January 28, 2026 14:12

Boumtchack requested a review from a team as a code owner January 28, 2026 14:12

Boumtchack requested a review from Qchristensen January 28, 2026 14:12

SaschaCowley added this to the 2026.2 milestone Jan 29, 2026

seanbudd requested changes Jan 30, 2026

View reviewed changes

seanbudd marked this pull request as draft January 30, 2026 01:17

	defaultPanValue = integer(min=1, max=100, default=10)
	defaultPanStep = integer(min=1, max=100, default=10)

		config.conf["magnifier"]["defaultZoomLevel"] = zoomLevel


		def getDefaultPanValue() -> int:

	def getDefaultPanValue() -> int:
	def getDefaultPanStep() -> int:

		return config.conf["magnifier"]["defaultPanValue"]


		def setDefaultPanValue(panValue: int) -> None:

	def setDefaultPanValue(panValue: int) -> None:
	def setDefaultPanStep(panStep: int) -> None:

		@@ -20,40 +20,40 @@ A short video demonstration, ["What is NVDA?"](https://www.youtube.com/watch?v=t

		@@ -0,0 +1 @@
		schemaVersion = 20

Uh oh!

Gestures to pan screen with arrows #19478

Are you sure you want to change the base?

Gestures to pan screen with arrows #19478

Conversation

Boumtchack commented Jan 20, 2026 • edited by seanbudd 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!

Boumtchack commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

seanbudd commented Jan 21, 2026

Uh oh!

cary-rowen commented Jan 21, 2026

Uh oh!

CyrilleB79 commented Jan 21, 2026

Uh oh!

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

CyrilleB79 commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Boumtchack commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CyrilleB79 commented Jan 26, 2026

Uh oh!

Boumtchack commented Jan 27, 2026

Uh oh!

CyrilleB79 commented Jan 27, 2026

Uh oh!

Boumtchack commented Jan 27, 2026

Uh oh!

seanbudd commented Jan 28, 2026

Uh oh!

Boumtchack commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CyrilleB79 commented Jan 28, 2026

Uh oh!

seanbudd commented Jan 30, 2026

Uh oh!

seanbudd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Boumtchack commented Jan 20, 2026 •

edited by seanbudd

Loading

Boumtchack commented Jan 20, 2026 •

edited

Loading

CyrilleB79 commented Jan 22, 2026 •

edited

Loading

Boumtchack commented Jan 26, 2026 •

edited

Loading

Boumtchack commented Jan 28, 2026 •

edited

Loading