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

[XLTechie]

Code complete, but docs pending.

Link to issue number:

Closes #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 optional copy and close buttons to all browseableMessages.
The "optional" part, means that they are optional to the caller of the browseableMessage, not optional to the user.

The text of each button can be supplied at call time, so may be translated.

Description of development approach

• Thanks to @michaelDCurran's recent browseableMessage change--namely adding a Scripting.Dictionary to carry GET style parameters to the mshtml instance behind browseableMessage, it was possible to pass in values for two new buttons 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.
• 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.
• In both cases, the close button is set to say "Press escape to close", even though the user can just press the button. I think this matches the Jaws experience, though not sure other SRs use these browseables the way we do.

Testing strategy:

• Created a scratchpad script, to test browseableMessages using both buttons, and a copy button, and a close button separately.
• After modifying the link destination and character info messages, tested those as well.

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.

Is it technically API breaking to add optional parameters to an existing function? I don't think so--we've done it before.

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.

[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?

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 Ctrl+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.

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.

My original reason for that, along with hesitating to insist that add-ons adopt the core phrasing, was because I originally planned to implement this PR just to add the functionality to browseableMessage, without including any uses for it in core. Then to add the implementation for various dialogs in a later PR. Again though, I would be fine if these were "copy" and "close".

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

Agreed.

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, as 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.

[XLTechie]

@CyrilleB79 did you notice my comment above? #16369 (comment) I would be interested in your further comments.
Note that I have placed the copy button in the character information window, and changed the button to just "Close" for that Window, while leaving it as "Press escape to close" in the link destination window, for the contrast. I'll settle on one based on @Qchristensen's preference before finalizing the PR.

[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: 1. 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. 2. The close text does not have to be configurable. I did that for add-ons, but I don't need to keep it. I have already removed it for the Copy button. 3. I didn't yet implement the message when copy is performed, awaiting Quentin's pre-review before spending any more time on this.

[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.