Repository: nvaccess/nvda

Issue:
Start and stop Braille viewer via a configurable command/Input Gesture
<!-- Please read the text in this edit field before filling it in.
Please thoroughly read NVDA's wiki article on how to fill in this template, including how to provide the required files.
Issues may be closed if the required information is not present.
https://github.com/nvaccess/nvda/blob/master/devDocs/githubIssueTemplateExplanationAndExamples.md
Please also note that the NVDA project has a Citizen and Contributor Code of Conduct which can be found at https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md. NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project. This includes creating or commenting on issues and pull requests. 

Each of the questions and sections below start with multiple hash symbols (#). Place your answers and information on the blank line below each question.
-->

### Is your feature request related to a problem? Please describe.
For deaf-blind users, who are interacting with the computer via a refreshable Braille display, the information given via speech is often not available. What is on the Braille display is what matters. The Braille viewer is aimed at sighted assistants who will then be able to get a visual Braille representation of the information the user is getting.

According to the user guide in NVDA 2021.3.1, it is only possible to turn the Braille Viewer on and off via the Tools menu. This is something that can be a bit complicated to quickly explain to a sighted helper.

### Describe the solution you'd like

A configurable command in the Input Gestures dialog to toggle the Braille Viewer similar to what we have for the Speech viewer.

### Describe alternatives you've considered

Using the Speech viewer instead. Is it the same as what is given in Braille? I haven't been able to get sighted verification, so if this is the case then the issue may be closed.

### Additional context

 As stated above, this issue may be irrelevant if the Speech viewer can be used instead.



Discussion:
> According to the user guide in NVDA 2021.3.1, it is only possible to turn the Braille Viewer on and off via the Tools menu. This is something that can be a bit complicated to quickly explain to a sighted helper.

You can explain it this way to sighted people:
"Right click on NVDA icon in the systray to open NVDA menu and click Tools, then Braille viewer"
Does it fit your needs?

> A configurable command in the Input Gestures dialog to toggle the Braille Viewer similar to what we have for the Speech viewer.

I agree however that it seems strange to have a shortcut for speech viewer and not for braille viewer that are quite similar. I do not know if it was a deliberate choice. If it was deliberate, maybe it's because the speech viewer window is bigger and covers a larger screen area, thus disturbing more often the activity on the screen.

> Using the Speech viewer instead. Is it the same as what is given in Braille? I haven't been able to get sighted verification, so if this is the case then the issue may be closed.

No: the speech viewer shows a list (or actually an edit field) which is appended with the spoken text each time something new is spoken. The Braille viewer on the contrary only shows what is currently brailled on the braille display. Moreover, what is brailled is not the same thing as what is spoken, e.g. "Button" is spoken when "btn" is brailled.

Thanks for explaining the difference between the viewers. Come to think of it, I think I would leave the Braille viewer on for this user, but for consistency and configurability, I agree that it is a bit odd not to have a script for toggling the Braille viewer on and off.
If there is a use case for a command to open close the braille viewer, I'm happy for that to be added.

I didn't add this because I didn't expect toggling it to be a common action, and the `NVDA+n, t, b` shortcut was quick enough for me. That sequence may be difficult for some.
@feerrenrut do you know what was the use case for the speech viewer shortcut?

@DGartmann let us know if leaving the braille viewer always on causes some issues, e.g. masking an area of interest on the screen.

It is going to be very difficult for me to get visual verification from that user. But I would be interested to know the reason for adding a shortcut key to the speech viewer and not to the Braille viewer. An unassigned script/command would also work in my scenario.
@CyrilleB79 I don't know, sorry. I'm happy for a command with no assigned gesture to be added. This should be fairly straightforward to add.

Resolving patch:
diff --git a/source/globalCommands.py b/source/globalCommands.py
--- a/source/globalCommands.py
+++ b/source/globalCommands.py
@@ -2714,6 +2714,28 @@ def script_toggleSpeechViewer(self,gesture):
 			gui.mainFrame.sysTrayIcon.menu_tools_toggleSpeechViewer.Check(True)
 		ui.message(state)
 
+	@script(
+		description=_(
+			# Translators: Input help mode message for toggle Braille viewer command.
+			"Toggles the NVDA Braille viewer, a floating window that allows you to view braille output, "
+			"and the text equivalent for each braille character"
+		),
+		category=SCRCAT_TOOLS
+	)
+	def script_toggleBrailleViewer(self, gesture):
+		import brailleViewer
+		if brailleViewer.isBrailleViewerActive():
+			# Translators: The message announced when disabling braille viewer.
+			state = _("Braille viewer disabled")
+			brailleViewer.destroyBrailleViewer()
+			gui.mainFrame.sysTrayIcon.menu_tools_toggleBrailleViewer.Check(False)
+		else:
+			# Translators: The message announced when enabling Braille viewer.
+			state = _("Braille viewer enabled")
+			brailleViewer.createBrailleViewerTool()
+			gui.mainFrame.sysTrayIcon.menu_tools_toggleBrailleViewer.Check(True)
+		ui.message(state)
+
 	@script(
 		# Translators: Input help mode message for toggle braille tether to command
 		# (tethered means connected to or follows).


Test patch: