[orca] Create new tutorial message for activating browse mode

[Joanmarie Diggs <joanied src gnome org>]

commit eebba606961f81fc82d272834f5d9aa40c95d448
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Sat Sep 20 21:55:05 2014 -0400

    Create new tutorial message for activating browse mode

 src/orca/messages.py                               |   19 +++++++++++
 .../scripts/toolkits/Gecko/tutorial_generator.py   |   14 ++++++--
 src/orca/tutorialgenerator.py                      |   34 +++++++++++++++++---
 3 files changed, 59 insertions(+), 8 deletions(-)
---
diff --git a/src/orca/messages.py b/src/orca/messages.py
index 9ab7d24..b8f7476 100644
--- a/src/orca/messages.py
+++ b/src/orca/messages.py
@@ -1105,6 +1105,25 @@ MODE_BROWSE = _("Browse mode")
 # This string is the message presented when Orca switches to focus mode.
 MODE_FOCUS = _("Focus mode")
 
+# Translators: Orca has a number of commands that override the default
+# behavior within an application. For instance, on a web page, "h" moves
+# you to the next heading. What should happen when you press an "h" in
+# an entry on a web page depends: If you want to resume reading content,
+# "h" should move to the next heading; if you want to enter text, "h"
+# should not not move you to the next heading. Similarly, if you are
+# at the bottom of an entry and press Down arrow, should you leave the
+# entry? Again, it depends on if you want to resume reading content or
+# if you are editing the text in the entry. Because Orca doesn't know
+# what you want to do, it has two modes: In browse mode, Orca treats
+# key presses as commands to read the content; in focus mode, Orca treats
+# key presses as something that should be handled by the focused widget.
+# This string is a tutorial message presented to the user who has just
+# navigated to a widget in browse mode to inform them of the keystroke
+# they must press to enable focus mode for the purposes of interacting
+# with the widget. The substituted string is a human-consumable keybinding
+# such as "Alt+Shift+A."
+MODE_FOCUS_TUTORIAL = _("To enable focus mode press %s.")
+
 # Translators: (Please see the previous, detailed translator notes about
 # Focus mode and Browse mode.) In order to minimize the amount of work Orca
 # users need to do to switch between focus mode and browse mode, Orca attempts
diff --git a/src/orca/scripts/toolkits/Gecko/tutorial_generator.py 
b/src/orca/scripts/toolkits/Gecko/tutorial_generator.py
index 63cd4cd..9f95072 100644
--- a/src/orca/scripts/toolkits/Gecko/tutorial_generator.py
+++ b/src/orca/scripts/toolkits/Gecko/tutorial_generator.py
@@ -23,16 +23,24 @@ __date__      = "$Date$"
 __copyright__ = "Copyright (c) 2014 Orca Team."
 __license__   = "LGPL"
 
+import orca.messages as messages
 import orca.tutorialgenerator as tutorial_generator
 
 class TutorialGenerator(tutorial_generator.TutorialGenerator):
     def __init__(self, script):
         tutorial_generator.TutorialGenerator.__init__(self, script)
 
-    def getTutorial(self, obj, alreadyFocused, forceTutorial=False):
+    def _getFocusModeTutorial(self, obj, alreadyFocused, forceTutorial):
+        binding = self._getBindingsForHandler("togglePresentationModeHandler")
+        if not binding:
+            return []
+
+        return [messages.MODE_FOCUS_TUTORIAL % binding]
+
+    def _getModeTutorial(self, obj, alreadyFocused, forceTutorial):
         if self._script.utilities.isFocusModeWidget(obj) \
            and not self._script.useFocusMode(obj):
-            return []
+            return self._getFocusModeTutorial(obj, alreadyFocused, forceTutorial)
 
-        return tutorial_generator.TutorialGenerator.getTutorial(
+        return tutorial_generator.TutorialGenerator._getModeTutorial(
             self, obj, alreadyFocused, forceTutorial)
diff --git a/src/orca/tutorialgenerator.py b/src/orca/tutorialgenerator.py
index e20f2f7..e16b100 100644
--- a/src/orca/tutorialgenerator.py
+++ b/src/orca/tutorialgenerator.py
@@ -51,6 +51,8 @@ class TutorialGenerator:
         # storing the last spoken message.
         self.lastTutorial = ""
 
+        self.lastRole = None
+
         # Set up a dictionary that maps role names to functions
         # that generate tutorial strings for objects that implement that role.
         #
@@ -764,6 +766,21 @@ class TutorialGenerator:
 
         return utterances
 
+    def _getBindingsForHandler(self, handlerName):
+        handler = self._script.inputEventHandlers.get(handlerName)
+        if not handler:
+            return None
+
+        bindings = self._script.keyBindings.getBindingsForHandler(handler)
+        if not bindings:
+            return None
+
+        binding = bindings[0]
+        return binding.asString()
+
+    def _getModeTutorial(self, obj, alreadyFocused, forceTutorial):
+        return []
+
     def getTutorial(self, obj, alreadyFocused, forceTutorial=False):
         """Get the tutorial for an Accessible object.  This will look
         first to the specific tutorial generators and if this
@@ -787,16 +804,23 @@ class TutorialGenerator:
 
         utterances = []
         role = obj.getRole()
-        if role in self.tutorialGenerators:
-            generator = self.tutorialGenerators[role]
-        else:
-            generator = self._getDefaultTutorial
-        msg = generator(obj, alreadyFocused, forceTutorial)
+        msg = self._getModeTutorial(obj, alreadyFocused, forceTutorial)
+        if not msg:
+            if role in self.tutorialGenerators:
+                generator = self.tutorialGenerators[role]
+            else:
+                generator = self._getDefaultTutorial
+            msg = generator(obj, alreadyFocused, forceTutorial)
+        elif msg == self.lastTutorial and role == self.lastRole \
+             and not forceTutorial:
+            msg = []
         if msg:
             utterances = [" ".join(msg)]
             self.lastTutorial = msg
+            self.lastRole = role
         if forceTutorial:
             self.lastTutorial = ""
+            self.lastRole = None
 
         self._debugGenerator("getTutorial",
                              obj,