Clarity improvement in magnifier naming by Boumtchack · Pull Request #20281 · nvaccess/nvda

Boumtchack · 2026-06-03T09:37:20Z

Link to issue number:

Closes #20126

Summary of the issue:

At the moment, the magnifier module lacks clarity in naming, it uses several terms to talk about the same things and that can lead to confusions

Description of user facing changes:

Users will have a better and clearer desciption and settings of the magnifier

Description of developer facing changes:

Variables and naming will be more consistent and logical

Description of development approach:

Adapting code naming to the User guide terms

Testing strategy:

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-06-03T09:38:43Z

@CyrilleB79 I started rewritting the user docs and I'll do the same in the settings when #19913 is closed.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR updates the magnifier “follow focus” terminology to “tracking” across the codebase, user docs, and scripts, and renames the fullscreen mode action from “toggle” to “cycle” for clarity.

Changes:

Renamed MagnifierFollowFocusType to MagnifierFollowTrackingType and updated related call sites.
Updated user documentation to reflect the new “tracking” terminology and revised descriptions.
Renamed the fullscreen magnifier mode command from toggleFullscreenMode to cycleFullscreenMode.

Reviewed changes

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

Show a summary per file

File	Description
user_docs/en/userGuide.md	Renames “focus tracking” language to “tracking” and adjusts magnifier documentation/anchors.
tests/unit/test_magnifier/test_focusManager.py	Updates unit tests to use the renamed follow/tracking enum.
source/gui/settingsDialogs.py	Renames magnifier UI “Focus” group to “Tracking” and updates follow checkbox plumbing; also changes review cursor config key usage.
source/globalCommands.py	Updates scripts to use the renamed enum and cycles fullscreen mode via the renamed command.
source/_magnifier/utils/types.py	Renames the follow enum type and updates translation contexts/labels.
source/_magnifier/utils/focusManager.py	Migrates focus manager to the renamed tracking enum type.
source/_magnifier/config.py	Updates follow-state config mapping and public API parameter naming to “tracking”.
source/_magnifier/commands.py	Updates toggle-follow API to accept tracking type and renames fullscreen mode function to “cycle”.

CyrilleB79 · 2026-06-10T13:13:53Z

FYI, I have made modifications in #20261 which update UI strings and even more sometimes. These may conflict with this PR, sorry (especially regarding "follow mode" / "tracking type").

CyrilleB79 · 2026-06-10T13:52:39Z

Also are we sure that "tracking mode" (previously "focus mode" / "full-screen mode") only applies to full-screen? Couldn't a docked mode user choose between "center" and "Border"? This PR is probably not the place to change that, but at least keep it in mind when/if changing variable/options names to avoid "full-screen" if the option may be moved in the future.

And another question:
"Center" / "Border" are names while "Relative" is an adjective. This makes the GUI reading a bit strange. Of course, we understand that they all are tracking modes names in any case. But I wonder if we cannot find better names. I have no ideal solution though.
We could change "to Keep centered on the screen" and "Keep within the borders of the screen" as Windows Magnifier uses; but I have no idea how "Relative" would be renamed in this case...

Boumtchack · 2026-06-10T14:30:13Z

FYI, I have made modifications in #20261 which update UI strings and even more sometimes. These may conflict with this PR, sorry (especially regarding "follow mode" / "tracking type").

Yes I will wait for your modification, I reverted to draft.

Also are we sure that "tracking mode" (previously "focus mode" / "full-screen mode") only applies to full-screen? Couldn't a docked mode user choose between "center" and "Border"? This PR is probably not the place to change that, but at least keep it in mind when/if changing variable/options names to avoid "full-screen" if the option may be moved in the future.

for now it's a fullscreen thing, because It's a fullscreen thing for Windows Magnifier, but nothing is fixed and this could be applied to other types of view, I think we could keep it as it is for know and change it if we want to add this to other modes, like spotlight (wich would be change to overview)

And another question:
"Center" / "Border" are names while "Relative" is an adjective. This makes the GUI reading a bit strange. Of course, we understand that they all are tracking modes names in any case. But I wonder if we cannot find better names. I have no ideal solution though.
We could change "to Keep centered on the screen" and "Keep within the borders of the screen" as Windows Magnifier uses; but I have no idea how "Relative" would be renamed in this case...

sometimes I feel like removing relatives would just save us some times, ahah

Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>

CyrilleB79

Partial review.
I've not had time to give all feedback or provide more suggestions.

CyrilleB79 · 2026-06-16T07:37:34Z

As explained in the initial issue, "Relative" should be explained without referring to Windows Magnifier.

Since you indicate the goal of each mode:
I think that Relative mode is useful if one wants to figure where the tracked element / the zoomed area is located with respect to the whole screen.

I thought I had changed it, my bad

I thought I had changed it, my bad

Indeed, you had. But it has been lost somewhere, maybe while merging latest changes in beta.
Let's hope you have not lost other parts of your work.

CyrilleB79 · 2026-06-16T11:10:42Z

Also, it may be interesting to rename "focus manager" to "tracking manager" (file name, class, etc.)

Boumtchack · 2026-06-16T11:21:27Z

should I rename the "follow" functions to "tracking" as well? like toggleAllFollow() and toggleFollow()

…avail/nvda into MagnifierNamingClarity

seanbudd · 2026-06-17T02:10:53Z

This is way too much unnecessary code churn for beta. Can we please avoid any large code changes and instead only keep updating user facing strings and other necessary beta changes?

Boumtchack · 2026-06-17T08:00:08Z

well I'm not sure this pr really is needed for the beta as the goal was to rename variables and not so much a userchange issue, I think @CyrilleB79 already covered a lot of this in #20261.

Maybe I there's some changes that can be made to userSettings and Userguide, but the main goal of this pr was to rename all functions for developers more than users

CyrilleB79 · 2026-06-17T21:17:02Z

-		fullscreenModeLabelText = _("Focus &mode:")
+		fullscreenModeLabelText = _("Tracking &mode:")
 		fullscreenModeChoices = [mode.displayString for mode in FullScreenMode] if FullScreenMode else []
 		self.fullscreenModeList = fullscreenGroup.addLabeledControl(


I'd rename this one since it is part of the (public) API:

Suggested change

self.fullscreenModeList = fullscreenGroup.addLabeledControl(

self.trackingModeList = fullscreenGroup.addLabeledControl(

rewritting userdoc

0879474

CyrilleB79 mentioned this pull request Jun 4, 2026

Magnifier UI improvement #20261

Merged

5 tasks

Boumtchack added 2 commits June 10, 2026 10:24

Merge branch 'beta' into MagnifierNamingClarity

cd222b7

removed unecessary focus naming

2ce2521

Boumtchack marked this pull request as ready for review June 10, 2026 11:36

Boumtchack requested review from a team as code owners June 10, 2026 11:36

Boumtchack requested review from Qchristensen, SaschaCowley and Copilot June 10, 2026 11:36

Boumtchack marked this pull request as draft June 10, 2026 11:36

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Boumtchack added 2 commits June 10, 2026 14:04

copilot review

1f277f1

little changes

86de732

CyrilleB79 reviewed Jun 10, 2026

View reviewed changes

Comment thread source/gui/settingsDialogs.py Outdated

Boumtchack marked this pull request as ready for review June 10, 2026 13:49

Boumtchack marked this pull request as draft June 10, 2026 14:23

Boumtchack added 2 commits June 15, 2026 10:23

Merge branch 'beta' into MagnifierNamingClarity

f4625d2

revert unwanted change

4687dfe

Boumtchack marked this pull request as ready for review June 15, 2026 13:37

CyrilleB79 reviewed Jun 15, 2026

View reviewed changes

Comment thread source/_magnifier/utils/types.py Outdated

Update source/_magnifier/utils/types.py

c12cebe

Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>

seanbudd reviewed Jun 16, 2026

View reviewed changes

Comment thread source/_magnifier/utils/types.py Outdated

Comment thread source/gui/settingsDialogs.py Outdated

Comment thread user_docs/en/userGuide.md Outdated

CyrilleB79 reviewed Jun 16, 2026

View reviewed changes

Boumtchack added 2 commits June 16, 2026 14:00

changed focus or follow to track

f4d34cf

Merge branch 'MagnifierNamingClarity' of https://github.com/France-Tr…

c11516f

…avail/nvda into MagnifierNamingClarity

seanbudd added this to the 2026.2 milestone Jun 17, 2026

seanbudd marked this pull request as draft June 17, 2026 02:10

Boumtchack added 3 commits June 17, 2026 13:13

revert changes for simplification

1c79e85

some leftover change that had been reverted

39220b1

setting dialog bad change reverted

564bc6a

CyrilleB79 reviewed Jun 17, 2026

View reviewed changes

	self.fullscreenModeList = fullscreenGroup.addLabeledControl(
	self.trackingModeList = fullscreenGroup.addLabeledControl(

Uh oh!

Conversation

Boumtchack commented Jun 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!

Boumtchack commented Jun 3, 2026

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!

Uh oh!

CyrilleB79 commented Jun 10, 2026

Uh oh!

Uh oh!

CyrilleB79 commented Jun 10, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

CyrilleB79 Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Boumtchack Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

CyrilleB79 Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

CyrilleB79 commented Jun 16, 2026

Uh oh!

Boumtchack commented Jun 16, 2026

Uh oh!

seanbudd commented Jun 17, 2026

Uh oh!

Boumtchack commented Jun 17, 2026

Uh oh!

CyrilleB79 Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

Boumtchack commented Jun 3, 2026 •

edited

Loading

Boumtchack commented Jun 10, 2026 •

edited

Loading