[orca/570658-whereami] Simplify how formatting strings are obtained

[William Walker <wwalker src gnome org>]

commit 2ecd41d2ff57ccf72df9d91e34507f11058c5d63
Author: Willie Walker <william walker sun com>
Date:   Wed Jun 3 23:09:43 2009 -0400

    Simplify how formatting strings are obtained
---
 src/orca/formatting.py                        |  106 +++++++++++--------------
 src/orca/scripts/toolkits/Gecko/formatting.py |    6 +-
 src/orca/speech_generator.py                  |   54 +++++++++----
 src/orca/where_am_I.py                        |   21 ++---
 4 files changed, 97 insertions(+), 90 deletions(-)

diff --git a/src/orca/formatting.py b/src/orca/formatting.py
index 45ca67f..0696c1b 100644
--- a/src/orca/formatting.py
+++ b/src/orca/formatting.py
@@ -249,73 +249,59 @@ class Formatting(dict):
             else:
                 self[key] = val
 
-    def getPrefix(self, mode, **args):
-        alreadyFocused = args.get('alreadyFocused', False)
-        if alreadyFocused:
-            # TODO - JD: This seems rather silly/hacky.
-            #
-            where_am_i_type = args.get('where_am_i_type', None)
-            if where_am_i_type == None:
-                focusType = 'focused'
-            elif where_am_i_type == True:
-                focusType = 'basicWhereAmI'
-            else:
-                focusType = 'detailedWhereAmI'
-        else:
-            focusType = 'unfocused'
-        try:
-            prefix = self[mode]['prefix'][focusType]
-        except:
-            prefix = self[mode]['prefix']['unfocused']
+    def getPrefix(self, **args):
+        """Get a formatting string to add on to the end of
+        formatting strings obtained by getFormat.
+
+        Arguments expected in args:
+        - mode: output mode, such as 'speech', 'braille'.
+        - formatType: the type of formatting, such as
+          'focused', 'basicWhereAmI', etc.
+        """
+        prefix = self[args['mode']]['prefix'][args['formatType']]
         return prefix
 
-    def getSuffix(self, mode, **args):
-        alreadyFocused = args.get('alreadyFocused', False)
-        if alreadyFocused:
-            # TODO - JD: This seems rather silly/hacky.
-            #
-            where_am_i_type = args.get('where_am_i_type', None)
-            if where_am_i_type == None:
-                focusType = 'focused'
-            elif where_am_i_type == True:
-                focusType = 'basicWhereAmI'
-            else:
-                focusType = 'detailedWhereAmI' 
-        else:
-            focusType = 'unfocused'
-        try:
-            suffix = self[mode]['suffix'][focusType]
-        except:
-            suffix = self[mode]['suffix']['unfocused']
-        return suffix
+    def getSuffix(self, **args):
+        """Get a formatting string to add on to the end of
+        formatting strings obtained by getFormat.
 
-    def getFormat(self, mode, **args):
-        alreadyFocused = args.get('alreadyFocused', False)
-        if alreadyFocused:
-            # TODO - JD: This seems rather silly/hacky.
-            #
-            where_am_i_type = args.get('where_am_i_type', None)
-            if where_am_i_type == None:
-                focusType = 'focused'
-            elif where_am_i_type == True:
-                focusType = 'basicWhereAmI'
-            else:
-                focusType = 'detailedWhereAmI'
-        else:
-            focusType = 'unfocused'
+        Arguments expected in args:
+        - mode: output mode, such as 'speech', 'braille'.
+        - role: the role, such as pyatspi.ROLE_TEXT
+        - formatType: the type of formatting, such as
+          'focused', 'basicWhereAmI', etc.
+        """
+        suffix = self[args['mode']]['suffix'][args['formatType']]
+        return suffix
 
-        role = args.get('role', None)
-        try:
-            roleDict = self[mode][role]
-        except:
-            roleDict = self[mode]['default']
+    def getFormat(self, **args):
+        """Get a formatting string for the given mode and
+        formatType.
 
+        Arguments expected in args:
+        - mode: output mode, such as 'speech', 'braille'.
+        - role: the role, such as pyatspi.ROLE_TEXT
+        - formatType: the type of formatting, such as
+          'focused', 'basicWhereAmI', etc.
+        """
         try:
-            format = roleDict[focusType]
+            # First try to find the exact match.
+            #
+            format = self[args['mode']][args['role']][args['formatType']]
         except:
             try:
-                format = roleDict['unfocused']
+                # Failing that, fallback to the 'unfocused' formatType
+                # for the mode and role, if it exists.
+                #
+                format = self[args['mode']][args['role']]['unfocused']
             except:
-                format = self[mode]['default'][focusType]
-
+                try:
+                    # Failing that, fallback to the default for the
+                    # formatType
+                    #
+                    format = self[args['mode']]['default'][args['formatType']]
+                except:
+                    # Failing that, just used the default 'unfocused' format
+                    #
+                    format = self[args['mode']]['default']['unfocused']
         return format
diff --git a/src/orca/scripts/toolkits/Gecko/formatting.py b/src/orca/scripts/toolkits/Gecko/formatting.py
index 55d64bc..c0a5c9f 100644
--- a/src/orca/scripts/toolkits/Gecko/formatting.py
+++ b/src/orca/scripts/toolkits/Gecko/formatting.py
@@ -76,10 +76,10 @@ class Formatting(orca.formatting.Formatting):
         #
         self._defaultFormatting = orca.formatting.Formatting(script)
 
-    def getFormat(self, dictType, **args):
+    def getFormat(self, **args):
         # ARIA widgets get treated like regular default widgets.
         #
         if args.get('isAria', False):
-            return self._defaultFormatting.getFormat(dictType, **args)
+            return self._defaultFormatting.getFormat(**args)
         else:
-            return orca.formatting.Formatting.getFormat(self, dictType, **args)
+            return orca.formatting.Formatting.getFormat(self, **args)
diff --git a/src/orca/speech_generator.py b/src/orca/speech_generator.py
index a6282a6..8b19957 100644
--- a/src/orca/speech_generator.py
+++ b/src/orca/speech_generator.py
@@ -718,7 +718,8 @@ class SpeechGenerator:
                     text = desc
                     if settings.speechVerbosityLevel \
                             == settings.VERBOSITY_LEVEL_VERBOSE \
-                       and args.get('where_am_i_type', None) == None:
+                       and not args.get('formatType', None) \
+                           in ['basicWhereAmI', 'detailedWhereAmI']:
                         text += " " \
                             + rolenames.rolenames[\
                             pyatspi.ROLE_ROW_HEADER].speech
@@ -806,7 +807,8 @@ class SpeechGenerator:
                     text = desc
                     if settings.speechVerbosityLevel \
                             == settings.VERBOSITY_LEVEL_VERBOSE \
-                       and args.get('where_am_i_type', None) == None:
+                       and not args.get('formatType', None) \
+                           in ['basicWhereAmI', 'detailedWhereAmI']:
                         text += " " \
                             + rolenames.rolenames[\
                             pyatspi.ROLE_COLUMN_HEADER].speech
@@ -980,7 +982,7 @@ class SpeechGenerator:
             parentTable = obj.parent.queryTable()
         except NotImplementedError:
             parentTable = None
-        isDetailedWhereAmI = args.get('where_am_i_type', None) == False
+        isDetailedWhereAmI = args.get('formatType', None) == 'detailedWhereAmI'
         if (settings.readTableCellRow or isDetailedWhereAmI) and parentTable \
            and (not self._script.isLayoutOnly(obj.parent)):
             parent = obj.parent
@@ -1558,7 +1560,8 @@ class SpeechGenerator:
         specifications) containing the role name of the parent of obj.
         """
         if args.get('role', obj.getRole()) == pyatspi.ROLE_ICON \
-           and args.get('where_am_i_type', None) != None:
+           and args.get('formatType', None) \
+               in ['basicWhereAmI', 'detailedWhereAmI']:
             # Translators: this is an alternative name for the
             # parent object of a series of icons.
             #
@@ -1848,6 +1851,22 @@ class SpeechGenerator:
         specifications) that represent the complete speech for the
         object.  The speech to be generated depends highly upon the
         speech formatting strings in formatting.py.
+
+        args is a dictionary that may contain any of the following:
+        - alreadyFocused: if True, we're getting speech for an object
+          that previously had focus
+        - priorObj: if set, represents the object that had focus before
+          this object
+        - includeContext: boolean (default=True) which says whether
+          the context for an object should be included as a prefix
+          and suffix
+        - role: a role to override the object's role
+        - formatType: the type of formatting, such as
+          'focused', 'basicWhereAmI', etc.
+        - forceMnemonic: boolean (default=False) which says if we
+          should ignore the settings.enableMnemonicSpeaking setting
+        - forceTutorial: boolean (default=False) which says if we
+          should force a tutorial to be spoken or not
         """
         result = []
         methods = {}
@@ -1869,26 +1888,31 @@ class SpeechGenerator:
             # and get its results, placing them in the globals for the
             # the call to eval.
             #
-            format = self._script.formatting.getFormat('speech',
-                                                       **args)
+            args['mode'] = 'speech'
+            if not args.get('formatType', None):
+                if args.get('alreadyFocused', False):
+                    args['formatType'] = 'focused'
+                else:
+                    args['formatType'] = 'unfocused'
+
+            format = self._script.formatting.getFormat(**args)
 
             # Add in the speech context if this is the first time
             # we've been called.
             #
             if not args.get('recursing', False):
                 if args.get('includeContext', True):
-                    prefix = self._script.formatting.getPrefix('speech',
-                                                               **args)
-                    suffix = self._script.formatting.getSuffix('speech',
-                                                               **args)
+                    prefix = self._script.formatting.getPrefix(**args)
+                    suffix = self._script.formatting.getSuffix(**args)
                     format = '%s + %s + %s' % (prefix, format, suffix)
-                debug.println(debug.LEVEL_ALL, "getSpeech for %s using '%s'" \
-                              % (repr(args), format))
                 args['recursing'] = True
                 firstTimeCalled = True
             else:
                 firstTimeCalled = False
 
+            debug.println(debug.LEVEL_ALL, "getSpeech for %s using '%s'" \
+                          % (repr(args), format))
+
             assert(format)
             while True:
                 try:
@@ -1913,7 +1937,7 @@ class SpeechGenerator:
             debug.printException(debug.LEVEL_SEVERE)
             result = []
 
-        if firstTimeCalled:
-            debug.println(debug.LEVEL_ALL,
-                          "getSpeech generated '%s'" % repr(result))
+        debug.println(debug.LEVEL_ALL,
+                      "getSpeech generated '%s'" % repr(result))
+
         return result
diff --git a/src/orca/where_am_I.py b/src/orca/where_am_I.py
index 30fc947..7c700a3 100644
--- a/src/orca/where_am_I.py
+++ b/src/orca/where_am_I.py
@@ -568,15 +568,12 @@ class WhereAmI:
         object.  The speech to be generated depends highly upon the
         speech formatting strings in formatting.py.
         """
-
-        # TODO - JD: I don't think this is how we should do things.
-        # I'm just in the process of moving things out of here and
-        # into speech_generator.py or default.py (and the app scripts)
-        # as approriate. This keeps things working in the meantime.
-        #
-        return self._script.speechGenerator.\
-            getSpeech(obj,
-                      alreadyFocused = True,
-                      where_am_i_type = basicOnly,
-                      forceMnemonic=True,
-                      forceTutorial=True)
+        if basicOnly:
+            formatType = 'basicWhereAmI'
+        else:
+            formatType = 'detailedWhereAmI'
+        return self._script.speechGenerator.getSpeech(obj,
+                                                      alreadyFocused=True,
+                                                      formatType=formatType,
+                                                      forceMnemonic=True,
+                                                      forceTutorial=True)