Toggle settings for magnifier focus by Boumtchack · Pull Request #19739 · nvaccess/nvda

Boumtchack · 2026-03-03T14:41:58Z

Link to issue number:

#19712

Summary of the issue:

NVDA's magnifier lacked per-source tracking toggles: mouse, system focus, review cursor and navigator object could not be independently enabled or disabled.

Description of user facing changes:

Four new checkboxes in the magnifier settings panel let users independently enable or disable tracking and four new gestures to toggle these settings (no key bidding yet).:

mouse pointer
system focus
review cursor
and navigator object.

Description of developer facing changes:

FocusType enum gains a REVIEW
FocusManager.getCurrentFocusCoordinates() now gates each source based on config.

Description of development approach:

The priority chains has been updated

Testing strategy:

Unit

Known issues with pull request:

Mouse disabling doesn't take effect properly:
Magnifier will follow mouse after disabling it until a new focus is given.

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.

Copilot

Pull request overview

This PR extends NVDA's built-in magnifier by adding per-source tracking toggle settings: users can now independently enable or disable magnifier tracking for mouse, system focus, review cursor, and navigator object via four new checkboxes in the Magnifier Settings panel, as well as via four new (mostly unbound) keyboard commands. Internally, the change adds a REVIEW member to FocusType, separates the review cursor into its own priority level (between system focus and navigator object), and gates each tracking source behind a configuration check.

Changes:

Adds FocusType.REVIEW enum value, new MagnifierFollowFocusType enum, and TOGGLE_FOLLOW_SETTINGS to MagnifierAction in types.py
Adds four follow-setting config accessors in config.py, four new [magnifier] boolean config spec entries, and a toggleFollow() command in commands.py
Adds four GUI checkboxes in settingsDialogs.py, four new scripts in globalCommands.py, and updates FocusManager with review cursor tracking, per-source gating, and a new UpdateFollowedFocus method

Reviewed changes

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

Show a summary per file

File	Description
`source/_magnifier/utils/types.py`	Adds `FocusType.REVIEW`, `MagnifierFollowFocusType` enum, and `TOGGLE_FOLLOW_SETTINGS` action
`source/_magnifier/utils/focusManager.py`	Adds review cursor tracking, per-source `follow*()` gating in priority chain, and `UpdateFollowedFocus` method
`source/_magnifier/config.py`	Adds four config accessor functions (`followMouse`, `followSystemFocus`, `followReview`, `followNavigatorObject`)
`source/_magnifier/commands.py`	Adds `toggleFollow()` command that toggles each follow setting and announces the new state
`source/config/configSpec.py`	Adds four boolean config spec entries with `default=True`
`source/gui/settingsDialogs.py`	Adds four new checkboxes in the magnifier settings panel with context-sensitive help bindings
`source/globalCommands.py`	Adds four new toggle scripts (one with a default gesture, three without)
`tests/unit/test_magnifier/test_focusManager.py`	Adds tests for review cursor position, per-source follow gating, and a new `TestFollowSettings` class

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

source/globalCommands.py

source/gui/settingsDialogs.py

source/_magnifier/config.py

source/_magnifier/utils/focusManager.py

source/_magnifier/commands.py

source/globalCommands.py

seanbudd · 2026-03-24T04:27:04Z

Is this ready for review?

source/_magnifier/magnifier.py

source/config/configSpec.py

source/_magnifier/utils/types.py

seanbudd · 2026-04-01T03:20:25Z

user_docs/en/userGuide.md

+#### Follow mouse {#MagnifierFollowMouse}
+
+This checkbox controls whether the magnifier should follow the mouse pointer.
+When enabled, the magnified area will automatically move to follow the mouse pointer, which can be helpful for users who navigate primarily using the mouse rather than the keyboard.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow system focus {#MagnifierFollowSystemFocus}
+
+This checkbox controls whether the magnifier should follow the system focus.
+When enabled, the magnified area will automatically move to follow the system focus, which can be helpful for users who navigate primarily using the keyboard and want the magnifier to track their navigation.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow review cursor {#MagnifierFollowReviewCursor}
+
+This checkbox controls whether the magnifier should follow the review cursor.
+When enabled, the magnified area will automatically move to follow the review cursor, which can be helpful for users who use the review cursor to navigate through content and want the magnifier to track their navigation.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow navigator object {#MagnifierFollowNavigatorObject}
+
+This checkbox controls whether the magnifier should follow the navigator object.


I think rather than a set of checkboxes, we should use a system like the speech modes list, where you select multiple items. see nvdaControls.CustomCheckListBox and excludedSpeechModes for examples.

Thoughts @CyrilleB79 @Boumtchack ?

I am tempted to keep separated checkboxes here instead, so that one accelerator shortcut key can be attributed to each one of these items.

I think checkboxes are the best, I could create a visual box tho to make it prettier

do you mean as a sub group? I think thats a good idea

I will do a pr for settings dialog, I'll include it in that if that's ok for you

I don't think we need a separate PR, just move the code added in source/gui/settingsDialogs.py into a groupbox

source/globalCommands.py

…feature/MagnifierClarityTracking

seanbudd · 2026-04-07T23:21:08Z

source/_magnifier/config.py

+def toggleAllFollowStates() -> bool:
 	"""
-	Check if magnifier should follow navigator object.
+		Toggle all follow states between forced-active and previously saved states.


Suggested change

Toggle all follow states between forced-active and previously saved states.

Toggle all follow states between forced-active and previously saved states.

seanbudd · 2026-04-07T23:22:31Z

source/_magnifier/config.py

-	"""
-	Set whether the magnifier should follow system focus.
+_savedFollowStates: dict[MagnifierFollowFocusType, bool] = {}

-	:param value: True to follow system focus, False otherwise.
-	"""
-	config.conf["magnifier"]["followSystemFocus"] = value
+_allFollowStatesForcedActive = False


could this be combined into a single dataclass forceFollowState or similar

seanbudd · 2026-04-07T23:26:32Z

user_docs/en/userGuide.md

+#### Follow mouse {#MagnifierFollowMouse}
+
+This checkbox controls whether the magnifier should follow the mouse pointer.
+When enabled, the magnified area will automatically move to follow the mouse pointer, which can be helpful for users who navigate primarily using the mouse rather than the keyboard.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow system focus {#MagnifierFollowSystemFocus}
+
+This checkbox controls whether the magnifier should follow the system focus.
+When enabled, the magnified area will automatically move to follow the system focus, which can be helpful for users who navigate primarily using the keyboard and want the magnifier to track their navigation.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow review cursor {#MagnifierFollowReviewCursor}
+
+This checkbox controls whether the magnifier should follow the review cursor.
+When enabled, the magnified area will automatically move to follow the review cursor, which can be helpful for users who use the review cursor to navigate through content and want the magnifier to track their navigation.
+
+This option is enabled by default.
+
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Disabled, Enabled|
+|Default |Enabled|
+
+#### Follow navigator object {#MagnifierFollowNavigatorObject}
+
+This checkbox controls whether the magnifier should follow the navigator object.


I don't think we need a separate PR, just move the code added in source/gui/settingsDialogs.py into a groupbox

…feature/MagnifierClarityTracking

Toggle settings for magnifier focus

5fd6d97

Boumtchack marked this pull request as ready for review March 3, 2026 15:57

Boumtchack requested a review from a team as a code owner March 3, 2026 15:57

Boumtchack requested review from SaschaCowley and Copilot March 3, 2026 15:57

Boumtchack marked this pull request as draft March 3, 2026 15:58

Copilot started reviewing on behalf of Boumtchack March 3, 2026 15:58 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

seanbudd mentioned this pull request Mar 4, 2026

Add touch based web element navigation in browse mode #19414

Merged

5 tasks

Boumtchack added 2 commits March 4, 2026 13:47

copilot review fix

87f2cb4

handle disabling last focus

cf547c2

seanbudd requested review from seanbudd and removed request for SaschaCowley March 5, 2026 02:42

seanbudd self-assigned this Mar 5, 2026

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

Boumtchack added 2 commits March 30, 2026 16:58

conflict resolve

bab13ae

getters and setters for better handling

fd52a91

Boumtchack marked this pull request as ready for review March 31, 2026 12:21

Boumtchack requested a review from a team as a code owner March 31, 2026 12:21

Boumtchack requested a review from Qchristensen March 31, 2026 12:21

seanbudd reviewed Apr 1, 2026

View reviewed changes

seanbudd marked this pull request as draft April 1, 2026 03:21

Boumtchack added 4 commits April 1, 2026 11:30

Merge branch 'master' of https://github.com/France-Travail/nvda into …

9603399

…feature/MagnifierClarityTracking

merging Focus type into MagnifierFollowFocusType

e11d5d3

adding a toggle all command. simplified config

1d3dd07

Merge branch 'master' of https://github.com/France-Travail/nvda into …

b7b9c1c

…feature/MagnifierClarityTracking

Boumtchack marked this pull request as ready for review April 7, 2026 09:20

seanbudd reviewed Apr 7, 2026

View reviewed changes

seanbudd marked this pull request as draft April 7, 2026 23:26

This was referenced Apr 7, 2026

preparing the new magnifier types #19915

Closed

initial commit #19913

Closed

Boumtchack added 2 commits April 14, 2026 11:17

Merge branch 'master' of https://github.com/France-Travail/nvda into …

4fa2d44

…feature/MagnifierClarityTracking

settings dialog + dataclass for follow state

b390189

Boumtchack marked this pull request as ready for review April 14, 2026 13:21

	Toggle all follow states between forced-active and previously saved states.
	Toggle all follow states between forced-active and previously saved states.

Uh oh!

Conversation

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

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!

seanbudd commented Mar 24, 2026

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Boumtchack commented Mar 3, 2026 •

edited

Loading