increase magnifier zoom level to 5000% and change zoom to percentages

[seanbudd]

Link to issue number:

Fixes #19486

Summary of the issue:

• the magnifier zoom level is capped at 10x, which quite low
• the dropdown list of zoom in settings is quite awkward, particularly with more options

Description of user facing changes:

• higher zoom value (50x/5000%)
• zoom is a percentage now
• the zoom setting is a spin control rather than a drop down.

Description of developer facing changes:

Added a StepSpinCtrl that allows step values for integer spin controls

Description of development approach:

• Use integer zoom percentage values as wx.spinctrldouble is inaccessible

Testing strategy:

• tested manually by upping/lowering zoom values in settings with buttons and arrow keys
• tested upgrading a config

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.

[Copilot]

Pull request overview

This PR changes NVDA Magnifier zoom configuration from ratio values to percentage values, increases the maximum zoom level, and replaces the zoom combo box with an integer spin control.

Changes:

• Converts magnifier zoom config/schema from floats like 2.0 to integer percentages like 200.
• Updates magnifier calculations to convert percentage zoom back to ratio for Windows Magnification APIs.
• Adds a stepped spin control for zoom settings and a config upgrade step.

Reviewed changes

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

Show a summary per file

File	Description
user_docs/en/userGuide.md	Updates documented magnifier zoom options.
source/gui/settingsDialogs.py	Replaces the zoom choice control with a stepped spin control.
source/gui/nvdaControls.py	Adds SpinStepCtrl for stepped integer spin behavior.
source/config/profileUpgradeSteps.py	Adds schema upgrade logic for ratio-to-percentage zoom values.
source/config/configSpec.py	Bumps schema version and changes magnifier zoom config type/range.
source/_magnifier/magnifier.py	Adds percentage-to-ratio zoom handling and validates percentage zoom values.
source/_magnifier/fullscreenMagnifier.py	Uses ratio zoom values for fullscreen magnification calculations/API calls.
source/_magnifier/config.py	Updates zoom constants, formatting, getters, and setters for percentage values.

[Qchristensen]

I was curious about the desire to change from 1x, 2x, etc to a percentage. So, I went off to see what I could find about how other magnifiers work:

1. Zoomtext uses 1x, 2x, etc. https://support.freedomscientific.com/content/documents/manuals/ZoomText/ZoomText_User_Guide_English_US.pdf

2. Windows Magnifier (in Windows 11 at least) uses a percentage (though I couldn't readily find a help page showing this, I just turned it on and checked)

3. Dolphin supernova uses 1x, 2x, etc. https://yourdolphin.com/support/manuals?product=1&version=24&language=4&submitted=submitted

On Linux, I found a list of four of the most popular magnifiers: https://www.linuxlinks.com/best-free-open-source-linux-magnifying-tools/ so based on that:

4. Linux Kmagnifier seems to use a ratio 1:2 etc. https://www.linuxlinks.com/kmagnifier-screen-magnifier/

5. Magnifiqus uses "up to five times": https://github.com/qtilities/magnifiqus

6. Wooz uses percent: https://github.com/negrel/wooz

7. Magnus uses 1x, 2x, etc: https://www.linuxlinks.com/magnus-very-simple-screen-magnifier/

8. Mac zoom seems to use 1x, 2x, etc (based on screen shots).

9. Android's built in magnifier uses 1x, 2x, etc https://support.google.com/accessibility/android/answer/6006949?hl=en

10. Chrome has a magnifier.... but seemingly the nomenclature for magnification levels is a secret. In fact the one thing I have learnt through trying to look this up, is that most magnifiers describe themselves along the lines of "this makes the screen bigger" or "lets you zoom in" without saying much about zoom levels at all.

11. Glassbrick is an older free Windows magnifier, which doesn't have much online anymore, and which I still have a copy of so I ran.... and it manages to work without ever offering a term for the current magnification level.

12. Magic, the now defunct program from Freedom Scientific, used 1x, 2x, from screenshots online

So, to summarize, from the 12 I found:
7 use a multiplier: 1x, 2x
2 use percentage
1 uses a ratio
2 don't use a term (or at least don't make it easy to find if they do)

Given that, I'm half tempted to lean towards multiplier since it's what most use, but I can also see the attraction of percent, since it's what Windows magnifier uses.

[seanbudd]

@Qchristensen - do you have a suggestion for a type of control that will work for a ratio (e.g. float with decimal values)? The wxWidgets version of a spin control that goes by fractional increments isn't accessible so we can't use that. Previously we were using a dropdown, but that is way too long for a range that goes up to 30-40x. A slider seems awkward and inefficient.

[CyrilleB79]

@Qchristensen - do you have a suggestion for a type of control that will work for a ratio (e.g. float with decimal values)? The wxWidgets version of a spin control that goes by fractional increments isn't accessible so we can't use that. Previously we were using a dropdown, but that is way too long for a range that goes up to 30-40x. A slider seems awkward and inefficient.

In any case, with so many values, the zoom in / zoom out commands are quite inefficient at high zoom level because only one keypress has a quite unsignificant effect, i.e. zooming from 48x to 49x is hardly noticeable while zooming from 2x to 3x makes a great difference.

IIRC, Zoomtext uses a dropdown / combo box control and goes until 60x. But it uses a non-linear set of values, e.g. 1, 1.2, 1.4, 1.6, 1.8, 2, 2.25, 2.5, 2.75, 3, 3.5, 4, 4.5, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 42, 48, 54, 60.
More, I think that in current versions, you can even select a subset of these zoom levels to be reachable with zoom command.

If we go with a max level so high as 50x, I really think that such a non-linear scale should be implemented.

I also prefer 2x with respect to 200%. It's a bit easier to understand, especially at higher zoom levels, e.g. more than 200%. And it's also shorter to hear when spoken.
But if we face a technical difficulty, 200% is acceptable too. It's not a big deal.

[Qchristensen]

Perhaps a spin edit? While this PR is partly to increase the maximum zoom (whether we call it 5000% or 50x - and I tend to agree with using 1x, 2x, 50x etc rather than percent) - I expect the majority of users will want it set somewhere between 2x - 5x (200% - 500%).

I agree with using some kind of scale where there are more options at the lower end (1x, 1.25x, 1.5x) than the higher end (40x, 45x, 50x). In any case, if the spin adjusted to whatever scale we worked out there, it could be possible to manually enter a value of your own - whether that was 48x or 2.375x? which might also resolve the question of customisation beyond whatever defaults we put in?

[seanbudd]

As mentioned before, we don't have an accessible spin edit control available for decimal/fractional numbers. Our choices, as far as I know, are:

• Combobox/dropdown with pre-set values. Probably a max of 10-15 values otherwise it's too long.
• whole number spin control using percentages
• slider

[seanbudd]

@CyrilleB79 - we think it's valuable to be able to granularly increase the zoom size. I think we'd instead want a separate issue/feature to add the ability to create a preset list of preferred zoom values, and gestures to cycle back/forth through them.
I think due to technical issues to support smaller zoom increments, we will need to use percentages. We could perform reporting as 5x for brevity though? and just use percentages in the control? or would that be too inconsistent

[CyrilleB79]

@CyrilleB79 - we think it's valuable to be able to granularly increase the zoom size. I think we'd instead want a separate issue/feature to add the ability to create a preset list of preferred zoom values, and gestures to cycle back/forth through them.

Double checked in Zoomtext.

• The control in the GUI is a spin control with floating values, not vocalized by NVDA by the way. Due to floating value spin control not accessible with NVDA we cannot use it.
• Natively Zoomtext has 29 available zoom levels distributed on a non-linear (logarithmic) scale, containing decimal and integer values. In its options, it offers 3 choices to select the subset of levels reachable with zoom commands:
  • all levels
  • round levels (integers only)
  • or a list of favorite levels, selectable in a checkable list.

I think due to technical issues to support smaller zoom increments, we will need to use percentages. We could perform reporting as 5x for brevity though? and just use percentages in the control? or would that be too inconsistent

Yes, we may try this in alpha/beta and see if people make negative feedback.

[seanbudd]

Ok, I will open a new issue for adding a zoom preset list, and change the reporting for zoom in this PR to 5x style for brevity.

[seanbudd]

Unit tests need to be fixed it seems

[Qchristensen]

Reads well.