[orca: 1/2] braille: hand off Braille output on NoFocus

[Joanmarie Diggs <joanied src gnome org>]

commit 392380251f88f2679dec84feed78840dd4ca6ccc
Author: Samuel Thibault <samuel thibault ens-lyon org>
Date:   Wed Apr 29 01:04:04 2020 +0200

    braille: hand off Braille output on NoFocus
    
    so as to let other screen readers provide information (e.g. xbrlapi shows
    the window title) when we do not have any.

 src/orca/braille.py         | 105 ++++++++++++++++++++++++++++++++++----------
 src/orca/event_manager.py   |   1 +
 src/orca/orca_gui_prefs.py  |   4 ++
 src/orca/scripts/default.py |   9 ++++
 4 files changed, 97 insertions(+), 22 deletions(-)
---
diff --git a/src/orca/braille.py b/src/orca/braille.py
index 94c4c5a62..bb46d2471 100644
--- a/src/orca/braille.py
+++ b/src/orca/braille.py
@@ -191,6 +191,10 @@ _flashEventSourceId = 0
 #
 _saved = None
 
+# Set to True when we lower our output priority
+#
+idle = False
+
 # Translators: These are the braille translation table names for different
 # languages. You could read about braille tables at:
 # http://en.wikipedia.org/wiki/Braille
@@ -1074,6 +1078,72 @@ def setFocus(region, panToFocus=True, getLinkMask=True):
 
     viewport[0] = max(0, offset)
 
+def _idleBraille():
+    """Try to hand off control to other screen readers without completely
+    shutting down the BrlAPI connection"""
+    global idle
+
+    if not idle:
+        try:
+            _brlAPI.setParameter(brlapi.PARAM_CLIENT_PRIORITY, 0, False, 0)
+            idle = True
+        except:
+            # BrlAPI before 0.8
+            pass
+
+    return idle
+
+def _clearBraille():
+    """Clear Braille output, hand off control to other screen readers, without
+    completely shutting down the BrlAPI connection"""
+
+    if not _brlAPIRunning:
+        # We do want to try to clear the output we left on the device
+        init(_callback)
+
+    if _brlAPIRunning:
+        try:
+            _brlAPI.writeText("", 0)
+            _idleBraille()
+        except:
+            msg = "BRAILLE: BrlTTY seems to have disappeared."
+            debug.println(debug.LEVEL_WARNING, msg, True)
+            shutdown()
+
+def _enableBraille():
+    """Re-enable Braille output after making it idle or clearing it"""
+    global idle
+
+    if not _brlAPIRunning:
+        init(_callback)
+
+    if _brlAPIRunning:
+        if idle:
+            try:
+                # Restore default priority
+                _brlAPI.setParameter(brlapi.PARAM_CLIENT_PRIORITY, 0, False, 50)
+                idle = False
+            except:
+                msg = "BRAILLE: could not restore priority"
+                debug.println(debug.LEVEL_INFO, msg, True)
+
+def disableBraille():
+    """Hand off control to other screen readers, shutting down the BrlAPI
+    connection if needed"""
+    global idle
+
+    if _brlAPIRunning and not idle:
+        if not _idleBraille():
+            # BrlAPI before 0.8
+            msg = "BRAILLE: could not go idle, completely shut down"
+            debug.println(debug.LEVEL_INFO, msg, True)
+            shutdown()
+
+def checkBrailleSetting():
+    """Disable Braille if it got disabled in the preferences"""
+    if not _settingsManager.getSetting('enableBraille'):
+        disableBraille()
+
 def refresh(panToCursor=True, targetCursorCell=0, getLinkMask=True, stopFlash=True):
     """Repaints the Braille on the physical display.  This clips the entire
     logical structure by the viewport and also sets the cursor to the
@@ -1121,15 +1191,7 @@ def refresh(panToCursor=True, targetCursorCell=0, getLinkMask=True, stopFlash=Tr
         return
 
     if len(_lines) == 0:
-        if not _brlAPIRunning:
-            init(_callback)
-        if _brlAPIRunning:
-            try:
-                _brlAPI.writeText("", 0)
-            except:
-                msg = "BRAILLE: BrlTTY seems to have disappeared."
-                debug.println(debug.LEVEL_WARNING, msg, True)
-                shutdown()
+        _clearBraille()
         _lastTextInfo = (None, 0, 0, 0)
         return
 
@@ -1267,9 +1329,11 @@ def refresh(panToCursor=True, targetCursorCell=0, getLinkMask=True, stopFlash=Tr
         submask = ""
 
     submask += '\x00' * (len(substring) - len(submask))
-    if not _brlAPIRunning:
-        init(_callback)
-    if _brlAPIRunning:
+
+    if _settingsManager.getSetting('enableBraille'):
+        _enableBraille()
+
+    if _settingsManager.getSetting('enableBraille') and _brlAPIRunning:
         writeStruct = brlapi.WriteStruct()
         writeStruct.regionBegin = 1
         writeStruct.regionSize = len(substring)
@@ -1299,16 +1363,12 @@ def refresh(panToCursor=True, targetCursorCell=0, getLinkMask=True, stopFlash=Tr
         if attributeMask:
             writeStruct.attrOr = submask
 
-        if not _brlAPIRunning:
-            init(_callback)
-        if _brlAPIRunning:
-            try:
-                _brlAPI.write(writeStruct)
-            except:
-                debug.println(debug.LEVEL_WARNING,
-                              "BrlTTY seems to have disappeared:")
-                debug.printException(debug.LEVEL_WARNING)
-                shutdown()
+        try:
+            _brlAPI.write(writeStruct)
+        except:
+            msg = "BRAILLE: BrlTTY seems to have disappeared."
+            debug.println(debug.LEVEL_WARNING, msg, True)
+            shutdown()
 
     if settings.enableBrailleMonitor:
         if not _monitor:
@@ -1768,6 +1828,7 @@ def init(callback=None):
         return False
 
     _displaySize = [x, 1]
+    idle = False
 
     # The monitor will be created in refresh if needed.
     #
diff --git a/src/orca/event_manager.py b/src/orca/event_manager.py
index cab801691..20277e266 100644
--- a/src/orca/event_manager.py
+++ b/src/orca/event_manager.py
@@ -388,6 +388,7 @@ class EventManager:
 
         defaultScript = _scriptManager.getDefaultScript()
         _scriptManager.setActiveScript(defaultScript, 'No focus')
+        defaultScript.idleMessage()
         return False
 
     def _dequeue(self):
diff --git a/src/orca/orca_gui_prefs.py b/src/orca/orca_gui_prefs.py
index ea0c0838f..e25455bdd 100644
--- a/src/orca/orca_gui_prefs.py
+++ b/src/orca/orca_gui_prefs.py
@@ -3259,6 +3259,8 @@ class OrcaSetupGUI(orca_gtkbuilder.GtkBuilderWrapper):
 
         orca.loadUserSettings(self.script)
 
+        braille.checkBrailleSetting()
+
         self._initSpeechState()
 
         self._populateKeyBindings()
@@ -3471,6 +3473,8 @@ class OrcaSetupGUI(orca_gtkbuilder.GtkBuilderWrapper):
 
         self._initGUIState()
 
+        braille.checkBrailleSetting()
+
         self._initSpeechState()
 
         self._populateKeyBindings()
diff --git a/src/orca/scripts/default.py b/src/orca/scripts/default.py
index 196d47639..ce80fb723 100644
--- a/src/orca/scripts/default.py
+++ b/src/orca/scripts/default.py
@@ -852,6 +852,7 @@ class Script(script.Script):
         """Called when this script is activated."""
 
         _settingsManager.loadAppSettings(self)
+        braille.checkBrailleSetting()
         braille.setupKeyRanges(self.brailleBindings.keys())
         speech.updatePunctuationLevel()
         speech.updateCapitalizationStyle()
@@ -1924,6 +1925,8 @@ class Script(script.Script):
 
         _settingsManager.setProfile(profileID, updateLocale=True)
 
+        braille.checkBrailleSetting()
+
         speech.shutdown()
         speech.init()
 
@@ -3974,6 +3977,12 @@ class Script(script.Script):
 
             braille.displayMessage(message, flashTime=duration)
 
+    def idleMessage(self):
+        """Convenience method to tell speech and braille engines to hand off
+        control to other screen readers."""
+
+        braille.disableBraille()
+
     @staticmethod
     def __play(sounds, interrupt=True):
         if not sounds: