Added descriptive text to more of the settings panels #17160

XLTechie · 2024-09-11T11:16:28Z

Link to issue number:

Summary of the issue:

Several settings panels were missing friendly introductory text.
While some have names that are so obvious they do not need introductory text (Speech, Braille, Keyboard, Mouse), others do need it (Input Composition, Browse Mode).

Description of user facing changes

The following settings panels now have some introductory text.

Input Composition
Review Cursor
browse mode
Document Nav
Add-on Store
Windows OCR

Description of development approach

Wrote, or mostly copied from the user guide with minor alterations, descriptions for the above listed settings panels.

Testing strategy:

Built, made sure the modified panels spoke correctly.
Some with vision may want to check that they show up right.

Known issues with pull request:

None, unless you count that i didn't label the more obvious panels.

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.

@coderabbitai summary

XLTechie · 2024-09-11T11:21:47Z

@josephsl, if you can, please verify the description of Input Composition.
@Qchristensen You may want to look at these settings panels when it builds.

SaschaCowley

Thanks for making a start on this @XLTechie. There's still a bit of work to go with regard to making the descriptions visible in the GUI, and I've also provided some thoughts on the wording.

source/gui/settingsDialogs.py

SaschaCowley · 2024-09-12T00:42:35Z

source/gui/settingsDialogs.py

+		"Adjust certain aspects of the Add-on Store, including whether you want to be notified "
+		"when your add-ons have updates available.",


This feels fairly self-explanatory to me.

SaschaCowley · 2024-09-12T00:46:51Z

source/gui/settingsDialogs.py

@@ -3246,6 +3269,10 @@ def onSave(self):
 class UwpOcrPanel(SettingsPanel):
 	# Translators: The title of the Windows OCR panel.
 	title = _("Windows OCR")
+	panelDescription = _(
+		# Translators: This is descriptive text shown at the top of the Windows OCR settings panel.
+		"Configure some elements of the Windows optical character recognition feature which NVDA makes available.",


This wording feels a little clunky, but I'm not sure I can come up with much better. How about:

Suggested change

"Configure some elements of the Windows optical character recognition feature which NVDA makes available.",

"Configure NVDA's Windows optical character recognition support.",

Yeah, most of what I came up with was clunky too. I'd apply this, but GH won't let me for unknown reasons (the diff is up to date). I'll change it manually.

SaschaCowley · 2024-09-12T01:03:40Z

source/gui/settingsDialogs.py

The panel descriptions are not visible in the UI. Take a look at ObjectPresentationPanel.makeSettings to see how they're being added visually. Though given similar code is increasingly going to be repeated all over the place, I wonder if it's worth refactoring SettingsPanel to visually add panelDescription itself to keep things DRY.

@SaschaCowley
That would be a heck of a refactor, given that makeSettings is abstract.
I hadn't looked at that code in a while, and forgot how it worked.
It would break a lot of add-ons to change the way this is handled, although I suppose now is the time.

I thought of trying to add it to the sizer using the metaclass, and have it be dependent on whether makeSettings does anything with the intro text, but inspect.getsource() is not going to be able to read makeSettings for one of the gui.SettingsPanel subclasses. At least, as far as I know.
Not sure of any other "gentle" way of doing things.
It's either break API here and refactor the whole thing; or duplicate the code.
Unless you can think of an alternative.

Yes, you're right... Two thoughts come to mind, though I haven't thought through these at great length:

Add the panel description in SettingsPanel._buildGui. Add a class attribute, automaticallyAddPanelDescription (or similar) to override this behaviour if not desired. This could be set to False to maintain backwards compatibility, or True to make things "just work". This will be needed, at the very least, for the advanced settings panel, which has a warning banner and descriptive text that are added separately, but concatenated to form its panelDescription.

Add a helper function to SettingsPanel that will handle adding the description from panelDescription appropriately. Manually call the helper function whenever we want a visible description. This way, we aren't repeating all of the layout logic, but aren't changing the API in any backwards-incompatible way. Theoretically, I think this would only need to be passed the box sizer helper as it will be able to get everything else from instance attributes.

My inclination is to go the automatic route, as SettingsPanelAccessible automatically adds panelDescription from the screen-reader user's point of view, so why shouldn't it be there visually? I'm not sure how many things this would break though.

Co-authored-by: Sascha Cowley <[email protected]>

This reverts commit e994f06.

CyrilleB79

Thanks @XLTechie.

Only some minor suggestions.

Also, I wonder if it wouldn't be useful to add a description in all panels for consistency?

source/gui/settingsDialogs.py

Co-authored-by: Cyrille Bougot <[email protected]>

SaschaCowley · 2024-10-28T23:31:24Z

@XLTechie what is the status of this PR?

XLTechie · 2024-10-28T23:45:06Z

@SaschaCowley I don't think I can get back to this until December or January. I still plan to, but my office was partially demolished thanks to a toxic mold invasion. Working out of a temporary location while rebuilding, with only a third of my usual infrastructure, has derailed anything not high priority. If you need to close it to get it out of the way, it's fine.

SaschaCowley · 2024-10-29T00:05:55Z

I'm happy to keep this open, I just wanted to check it wasn't abandoned. Best of luck with the repairs!

XLTechie · 2024-10-29T00:19:22Z

Thanks!

Luke Davis added 7 commits September 11, 2024 06:07

Add Input Composition panel description

b24841a

Add Review Cursor panel description

b321c02

Added browse mode panel description

dae1f66

Add Document Nav panel description

ce53e4a

Add Add-on Store panel description

e994f06

Add Windows OCR panel description

b0e47b9

changes

118f039

XLTechie requested a review from a team as a code owner September 11, 2024 11:16

XLTechie requested a review from SaschaCowley September 11, 2024 11:16

pre-commit-ci bot and others added 2 commits September 11, 2024 11:17

Pre-commit auto-fix

8d9a000

Added PR number to changes.

e92e396

SaschaCowley requested changes Sep 12, 2024

View reviewed changes

SaschaCowley marked this pull request as draft September 12, 2024 01:07

XLTechie and others added 3 commits September 11, 2024 22:10

Update Browse Mode settings description.

17b7054

Co-authored-by: Sascha Cowley <[email protected]>

Revert "Add Add-on Store panel description"

9a09156

This reverts commit e994f06.

Update the OCR settings description.

6eccf72

CyrilleB79 reviewed Sep 12, 2024

View reviewed changes

source/gui/settingsDialogs.py Outdated Show resolved Hide resolved

source/gui/settingsDialogs.py Outdated Show resolved Hide resolved

XLTechie and others added 2 commits September 13, 2024 05:21

Update Review Cursor settings description per @CyrilleB79's suggestion

720d2ed

Co-authored-by: Cyrille Bougot <[email protected]>

Update Document Nav settings description per @CyrilleB79

50ce7ac

Co-authored-by: Cyrille Bougot <[email protected]>

seanbudd added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Sep 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added descriptive text to more of the settings panels #17160

Added descriptive text to more of the settings panels #17160

XLTechie commented Sep 11, 2024

XLTechie commented Sep 11, 2024

SaschaCowley left a comment

SaschaCowley Sep 12, 2024

SaschaCowley Sep 12, 2024

XLTechie Sep 12, 2024

SaschaCowley Sep 12, 2024

XLTechie Sep 12, 2024

SaschaCowley Sep 13, 2024

CyrilleB79 left a comment

SaschaCowley commented Oct 28, 2024

XLTechie commented Oct 28, 2024 via email

SaschaCowley commented Oct 29, 2024

XLTechie commented Oct 29, 2024 via email

		"Adjust certain aspects of the Add-on Store, including whether you want to be notified "
		"when your add-ons have updates available.",

	"Configure some elements of the Windows optical character recognition feature which NVDA makes available.",
	"Configure NVDA's Windows optical character recognition support.",

Added descriptive text to more of the settings panels #17160

Are you sure you want to change the base?

Added descriptive text to more of the settings panels #17160

Conversation

XLTechie commented Sep 11, 2024

Link to issue number:

Summary of the issue:

Description of user facing changes

Description of development approach

Testing strategy:

Known issues with pull request:

Code Review Checklist:

XLTechie commented Sep 11, 2024

SaschaCowley left a comment

Choose a reason for hiding this comment

SaschaCowley Sep 12, 2024

Choose a reason for hiding this comment

SaschaCowley Sep 12, 2024

Choose a reason for hiding this comment

XLTechie Sep 12, 2024

Choose a reason for hiding this comment

SaschaCowley Sep 12, 2024

Choose a reason for hiding this comment

XLTechie Sep 12, 2024

Choose a reason for hiding this comment

SaschaCowley Sep 13, 2024

Choose a reason for hiding this comment

CyrilleB79 left a comment

Choose a reason for hiding this comment

SaschaCowley commented Oct 28, 2024

XLTechie commented Oct 28, 2024 via email

SaschaCowley commented Oct 29, 2024

XLTechie commented Oct 29, 2024 via email