Give ui.browseableMessage the ability to show copy and close buttons after the message, and add buttons to some instances

[XLTechie]

Link to issue number:

Fixes #14641

Summary of the issue:

@Qchristensen reported that some users are confused by browseableMessages, and their lack of definite closure mechanisms.
During the conversation, it was pointed out that in some cases, a user might also desire a copy button.

Description of user facing changes

Added copy and close buttons to some browseableMessages.

Description of development approach

• Thanks to @michaelDCurran's recent browseableMessage change--namely adding a Scripting.Dictionary to carry arbitrary query-string-equivalent style parameters to the mshtml instance behind browseableMessage, it is now possible to pass in values for two new buttons, and various translatable messages, without any contortions.
• Tried different methods in the JS and CSS of message.html, and eventually settled on one which displayed the two buttons side-by-side, under a separator. If neither button's label is supplied, the div containing the HR and buttons remains hidden.
• The "Copy" button can be activated with Alt+C, and the "Close" button by Escape. Alt+C is indicated to the user via an accessibility label.
• While the description of the key has been made translatable, the key itself can not be changed currently.
• Fixed up some docstring parameter listings to match modern format.
• Per the issue, modified the Report Link Destination message, to have both a copy button and a close button.
• Per the issue, added a close button to the Report Character Information message.
• Per request in PR comments, used a live region to present a "Copy complete" or "copy failed" message to the user. This message remains on screen for five seconds.
• The AI suggested covering for more failures in the initialization and configuration of MSHTML. I used its suggested exception checking, but added a private function to display an error message to the user when one of the components fail, so at least some kind of user notice can be given. I based it on the already extant private function for messaging the user if a browseableMessage is called on a secure screen.
• Added an immediate return if the MSHTML window is opened without providing the dialog arguments (i.e. the message and title, at least). That situation should never actually occur, but in the unlikely event that a failure passes the error checking we have in browseableMessage, this will return immediately, instead of stranding the user in a blank window with no obvious close mechanism.
• Tightened the handling of text vs. HTML, to possibly prevent some hypothetical cases of raw HTML being given to the browser instance when we don't expect that to be the case. In particular, messages are now always assumed to be text by the javascript processing, unless a specific flag is passed via the scriptable.dictionary, instructing the JS to allow the message to be treated as HTML.

Testing strategy:

Tested using mainly the report link destination window, and a few other core windows.

Known issues with pull request:

• In addition to the others, it was requested that the OCR results window provide a close button. This is more difficult, and I'd rather leave it to a separate PR in case it is not desired after all.
• I have not made any docs changes for this. I will look through existing docs and figure out if anything needs to be mentioned at appropriate places, in a follow-up PR, unless @seanbudd wants it here.
• The Alt+C key can not currently be changed to another key by keymap translators, because of the esoteric way javascript maps keys to known character sets. I continue to research this but didn't want to delay the PR for it.

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.

Summary by CodeRabbit

• New Features

  • Added "Copy" and customizable "Close" buttons to message dialogs for enhanced usability.
  • Users can now copy text directly from message dialogs.

• Documentation

  • Updated user documentation to reflect new "Copy" and "Close" button features in message dialogs.

[AppVeyorBot]

• FAIL: Translation comments check. Translation comments missing or unexpectedly included. See build log for more information.
• PASS: Unit tests.
• PASS: Lint check.
• PASS: System tests (tags: installer NVDA).
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/6fors0f1o4d2sq3a/artifacts/output/nvda_snapshot_pr16369-31560,29b526c9.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.9,
  INSTALL_END 0.8,
  BUILD_START 0.0,
  BUILD_END 25.4,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 2.1,
  FINISH_END 0.2

See test results for failed build of commit 29b526c98d

[XLTechie]

@Qchristensen would you mind trying this build, and commenting on the UX?
(Edit: link updated with June 19 build)

Specifically, try NVDA+k NVDA+k, and NVDA+f NVDA+f, and observe the buttons which appear in each message.
Please consider them in the light of #14641.

I haven't written dev or user documentation yet, but I want to make sure this is going in a reasonable direction.

Also note, that the copy button is optional. Further, note the comment below by @wmhn1872265132, and consider whether that would be a useful alternative.

[wmhn1872265132]

I prefer to change the behavior of copying to copy and exit, generally speaking once the information is copied the window loses its necessity to exist

[CyrilleB79]

I am not convinced of the usefulness of this PR. As an experimented user, the change in this PR is a degradation of my personal experience, due to the "select all" issue, i.e. when selecting all, you select both the content and the control buttons.

But I understand that this PR rather targets beginners. Though, it seems to me that there has not been so many reporting from beginners or teachers with the current browseable message. Escape or Alt+F4 are classical commands in Windows, so I guess many beginners learn it quite quickly in any case. Also aren't touch device users accustomated to go to previous object in fow to reach the close button?

In any case, I guess that teachers (@XLTechie, @britechguy, maybe @cary-rowen) are the best persons to indicate if this PR is useful or not; and I will not go against their choice.

I have various remarks though on this PR:

1. The button containing "Press escape to exit" is a strange UX. Either you put a button (or a link) with only "Exit" or just write "Press escape to exit" in static text, but not both. Did you ever see dialog boxes with a button labeled "Press escape to cancel"?
2. IMO, the user experience should be the same in all browseable messages, at least in NVDA core's ones. I do not know in which case the "Copy" and "Exit" button text should be configurable. Thus, the strings of the buttons should be defined in ui.browseableMessage (at least by default), not in the calling function. If we really want these buttons still to be configurable,maybe a simple True/False parameter would be enough?
3. When you press the "Copy" button, nothing is heard. If we keep this "Copy" button, a speech feedback is at least needed.
4. More specifically, I am not convinced of the "Copy" button. In NVDA 2024.1, we can easily copy the text with control+A and control+C. With this PR we add an additional footer with an "Exit" button which degrade the copy experience. Thus we need to add one more button which loads more this windows. I have the feeling that we have not found the good solution. Is there an alternative solution? E.g. a description of the document labelled "Press escape to exit".

Sorry Luke for this quite negative feedback, but I thought it was worth sharing.

[XLTechie]

I am not convinced of the usefulness of this PR. As an experimented user, the change in this PR is a degradation of my personal experience, due to the "select all" issue, i.e. when selecting all, you select both the content and the control buttons.

I believe that is why @nvdaes proposed the "copy" button in the original issue. The copy button specifically avoids copying the footer section.
For clarification: what is the purpose of selecting all and copying, if you can use the copy button provided? I think we could put a Alt+c keyboard shortcut on it if needed.

But I understand that this PR rather targets beginners. Though, it seems to me that there has not been so many reporting from beginners or teachers with the current browseable message.

@Qchristensen originally raised this. That was my only context; I am assuming he, as NV Access, had sufficient complaints to open an issue.

I think the debate is supposed to be done in the original issue. Certainly the context is there.

1. The button containing "Press escape to exit" is a strange UX. Either you put a button (or a link) with only "Exit" or just write "Press escape to exit" in static text, but not both. Did you ever see dialog boxes with a button labeled "Press escape to cancel"?

This is a rip-off of Jaws, and in part a response to the request in the original
issue. It would not bother me for this to be just "Close", leaving the escape
part out entirely. This was in part why I requested a pre-review from
@Qchristensen. I also do not care for this text.

The Jaws UI here, I believe, is just a text line saying "Press escape to close", that for some reason acts as a close button if you happen to interact with it. I could have done that here (with a clickable), but I thought people would find that as objectionable as you find this.
Jaws doesn't provide a copy button, and I often see their closing line show up in people's copied text from these Windows, which Jaws uses for more purposes I believe.

2. IMO, the user experience should be the same in all browseable messages, at least in NVDA core's ones.

I agree in general, and can easily do that. At this stage of the draft PR, I wished to demonstrate both possibilities.

However, add-ons may have other requirements, and I didn't want to insist that they have a copy button.

3. When you press the "Copy" button, nothing is heard. If we keep this "Copy" button, a speech feedback is at least needed.

Agreed. Done in a live region.

4. More specifically, I am not convinced of the "Copy" button. In NVDA 2024.1, we can easily copy the text with control+A and control+C. With this PR we add an additional footer with an "Exit" button which degrade the copy experience. Thus we need to add one more button which loads more this windows.

"Copy" exists to enable copying without inclusion of the footer. That may be what you're saying there, the translation is unclear of "which loads more this windows", although I think it means that it adds more content to the window. If that is what you meant, then the reason is to provide a copy function that doesn't capture the footer, which is what I got from #14641 (comment)

I have the feeling that we have not found the good solution. Is there an alternative solution? E.g. a description of the document labelled "Press escape to exit".

"Press escape to exit" could be added to the title bar of every message.

• I'm not sure how useful that is given that some title bars may already be quite long (if they contain the name of a link, for example), and visually I am not sure the title bar is even shown.
• That also still leaves us with the problem of touch users, which @josephsl raised originally.
• Lastly, @michaelDCurran preferred the footer close button in the original issue.

I am not sure there is a "good" solution to this.
Actually, there is: replace everything currently shown in a UI.browseableMessage, with a real dialog in an appropriate WX control. Then provide the close button only. That should solve the select all problem, if it's a read-only editable text field.
ui.browseableMessage is a convenient, but ultimately lazy, way to get a non-modal dialog with HTML side-benefits.

[CyrilleB79]

Re all the comments in #16369 (comment):

I have the feeling that we did not investigate enough #14641, i.e. why some people may have difficulty with the browseable message. Are there many such people? What is the profile of these people? Have these people switched recently from Jaws and do they expect the same from NVDA?
@Qchristensen, can you provide answers to these questions?

It seems to me that almost every blind windows user know that pressing Alt+F4 or Escape in any window or dialog allows to close it; a user that would not be aware of this is lacking important information and thus would need extra teaching.

My personal need for select all is only to copy the content. So I agree that the "Copy" button does the same thing.

Why I am a bit reluctant to the change in this PR is that it seems to me a UX degradation. The browseable message becomes heavier (in term of UX) with the Close button, and moreover adding the Close button causes a new issue, which is resolved by adding the Copy button, which makes this browseable message more heavy and complex. But people have not expressed difficulty in copying the content of current version of the browseable message.

Also, I understand why the buttons (presence or not and label) may need to be configurable. However, this configurability will make the experience of browseable message less unified, which is a UX degradation.

The wx dialog is not an option due to the isHtml option, except if you remove this possibility which is not used in NVDA's core in any case.

Bu if I am the only one feeling that it's a UX degradation, go ahead anyway. Especially if @Qchristensen confirms the "go" for this PR.

Thanks for having changed the label of the "Close" button. The speech feedback of the "Copy" button is still needed. And also, what is copied when isHtml is True?

[XLTechie]

@CyrilleB79 I just want to say that: Most dialogs in NVDA that are real dialogs (actually all, that I can think of), have some sort of active close feature, be it an OK button, a Close button, or such. So this is not so abnormal. The average user doesn't know that this is not a dialog. I think that may be where some of the confusion comes from.

[Adriani90]

In general this is not a dialog, and in fact it is even not visible on the screen as far as I know. NVDA reports "document" when opening them, and not "dialog" as it does when opening settings dialogs. I agree with @CyrilleB79's doubts on the usefullness of this PR.
I would rather vote to add some lines to the user guide explaining the difference between a dialog and a virtual browseable document.

@XLTechie wrote:

The average user doesn't know that this is not a dialog. I think that may be where some of the confusion comes from.

I think it would make more sense to tell users that there is a difference instead of changing the interface so the users don't notice a difference.

In NVDA terms virtual browseable documents are commonly used in many discussoins, so it is ok in my view not to treat them as if they were dialogs.

[XLTechie]

@Adriani90 wrote:

In general this is not a dialog, and in fact it is even not visible on the screen as far as I know.

It is absolutely visible on the screen.

[Adriani90]

Even the OCR window?Von meinem iPhone gesendetAm 15.04.2024 um 12:46 schrieb Luke Davis ***@***.***>: @Adriani90 wrote:

In general this is not a dialog, and in fact it is even not visible on the screen as far as I know.

It is absolutely visible on the screen. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[XLTechie]

@Adriani90 wrote:

Even the OCR window?

no, but that is a custom dialog, not an mshtml document. Not applicable to this conversation.

[seanbudd]

Is this ready for review?

[coderabbitai]

Walkthrough

The recent changes enhance user interaction in message dialogs by introducing new parameters to the ui.browseableMessage function, adding "Copy" and "Close" buttons. This improvement aims to make dialogs more accessible and user-friendly, allowing users to easily copy text and close dialogs directly, enhancing overall usability.

Changes

File Path	Change Summary
source/globalCommands.py	Updated multiple methods to utilize new parameters in ui.browseableMessage for enhanced user interaction.
source/message.html	Introduced onCopyButtonPress() and onCloseButtonPress() functions to manage new button actions.
source/ui.py	Modified browseableMessage to accept closeButton and copyButton parameters for improved functionality.
user_docs/en/changes.md	Updated documentation to reflect the addition of Copy and Close buttons, outlining enhancements to ui.browseableMessage.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant GlobalCommands
    participant UI
    participant MessageHtml
    
    User ->> GlobalCommands: Trigger Report Link Destination
    GlobalCommands ->> UI: Call browseableMessage with new parameters
    UI ->> MessageHtml: Render message with copy & close buttons
    User ->> MessageHtml: Click Copy Button
    MessageHtml ->> User: Handle copy action
    User ->> MessageHtml: Click Close Button
    MessageHtml ->> User: Handle close action

Loading

Assessment against linked issues

Objective	Addressed	Explanation
Add "press escape to close" to dialogs which may not be obvious to users (#14641)	✅
Include options for a copy button and customizable close button name in message dialogs	✅

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 3

Outside diff range and nitpick comments (1)

source/ui.py (1)

Line range hint 92-137: Review the integration of closeButtonText and copyButton parameters in browseableMessage.

The implementation of the browseableMessage function with additional parameters for button text and display options is a good enhancement. However, consider refactoring to encapsulate the button-related logic into a separate function or class. This would improve the maintainability of the code and make it easier to manage changes to the button logic in the future.

[XLTechie]

@seanbudd I have updated this and marked it as ready again, pursuant to my comment #16369 (comment)
If you disagree about NH3 being a separate action/API breaking, then we can put it back to draft again and I'll work on that.

Also, I am interested in the directions from which you see an injection threat coming?
Given that any code capable of launching ui.browseableMessage, and populating it with HTML, is also capable of much more effectively accessing the entire user space via Python, I'm trying to figure out what exactly we are protecting against.

Presumably a user could click a link in HTML provided by an add-on, which would then load a secondary malicious page, or could even pull something in via auto-loaded external refs of other kinds. But once the initial HTML is loaded, Python is out of the picture, and obviously we can't sanitize that.
We can only clean the HTML before it gets to the browser, and given anything able to put it in the browser could also unlink the whole filesystem from within Python, or exfiltrate anything via requests, I'm unclear on what door we are closing.

Even if an add-on pushes in a third party link via a refresh directive, short of banning those entirely, we wouldn't be able to do anything about it. And maybe we should ban those entirely, I'm just trying to get a sense of the threat vector.

[seanbudd]

@XLTechie - I'll need to discuss internally on whether we want to perform the sanitization in this release.

The vector we're concerned about is NVDA translations, as these are fairly unregulated, translation strings are the only "code" included in NVDA without a direct review from NV Access or as a dependency. If NVDA translations can perform RCE, we have a problem.
Considering no NVDA source code uses isHTML currently, this isn't an active vector.
However, if we ever start using isHTML, it becomes an active vector, which is something we want to avoid and prevent from becoming a possibility.

I think we can tackle this in 2025.1 as the sanitization rules might break add-on functionality, and there's no active risk right now.

[XLTechie]

The vector we're concerned about is NVDA translations, as these are fairly unregulated, translation strings are the only "code" included in NVDA without a direct review from NV Access. If NVDA translations can perform RCE, we have a problem.

Well, I would imagine they could, if we had any HTML based messages in play, which, as you say, we don't. I don't think there are any active proposals that would introduce one, either. I can even think of a policy based mitigation that would work for the time being, in case some weird need for an HTML message comes up before 2025.1 release. Specifically, require that all internal HTML messages have only their non-HTML strings translatable, and run those that are through one of the escaping functions.

[seanbudd]

@XLTechie I'll write up an issue to do this in 2025.1. I think we could make the sanitization rules for this message as part of our public API so add-ons can adjust them as necessary

[seanbudd]

I've opened #16985

[SaschaCowley]

Re the "ding" issue, did you try e.stopPropagation or e.preventDefault in the key handler?

[XLTechie]

@SaschaCowley Yes, with no change in outcome. I also tried other ways of picking up the event than the body onKeyDown handler, but was unsuccessful in even receiving the key then, unless I was doing it wrong. (E.g. an addEventListener on the button.)