generator.py 60.1 KB
Newer Older
1 2 3
# Orca
#
# Copyright 2009 Sun Microsystems Inc.
4
# Copyright 2015-2016 Igalia, S.L.
5 6
#
# This library is free software; you can redistribute it and/or
7
# modify it under the terms of the GNU Lesser General Public
8
# License as published by the Free Software Foundation; either
9
# version 2.1 of the License, or (at your option) any later version.
10 11 12 13
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14
# Lesser General Public License for more details.
15
#
16
# You should have received a copy of the GNU Lesser General Public
17 18 19 20 21 22 23 24 25
# License along with this library; if not, write to the
# Free Software Foundation, Inc., Franklin Street, Fifth Floor,
# Boston MA  02110-1301 USA.

"""Superclass of classes used to generate presentations for objects."""

__id__        = "$Id:$"
__version__   = "$Revision:$"
__date__      = "$Date:$"
26 27
__copyright__ = "Copyright (c) 2009 Sun Microsystems Inc." \
                "Copyright (c) 2015-2016 Igalia, S.L."
28 29
__license__   = "LGPL"

30 31
import collections
import pyatspi
32
import sys
33
import time
34
import traceback
35
from gi.repository import Atspi, Atk
36

37 38
from . import braille
from . import debug
39
from . import messages
40
from . import object_properties
41
from . import settings
42
from . import settings_manager
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

def _formatExceptionInfo(maxTBlevel=5):
    cla, exc, trbk = sys.exc_info()
    excName = cla.__name__
    try:
        excArgs = exc.args
    except KeyError:
        excArgs = "<no args>"
    excTb = traceback.format_tb(trbk, maxTBlevel)
    return (excName, excArgs, excTb)

# [[[WDW - general note -- for all the _generate* methods, it would be great if
# we could return an empty array if we can determine the method does not
# apply to the object.  This would allow us to reduce the number of strings
# needed in formatting.py.]]]

# The prefix to use for the individual generator methods
#
METHOD_PREFIX = "_generate"

63 64
_settingsManager = settings_manager.getManager()

65 66 67 68 69 70 71 72
class Generator:
    """Takes accessible objects and generates a presentation for those
    objects.  See the generate method, which is the primary entry
    point."""

    # pylint: disable-msg=W0142

    def __init__(self, script, mode):
73 74 75

        # pylint: disable-msg=W0108

76 77
        self._mode = mode
        self._script = script
78
        self._activeProgressBars = {}
79 80
        self._methodsDict = {}
        for method in \
81
            [z for z in [getattr(self, y).__get__(self, self.__class__) for y in [x for x in dir(self) if x.startswith(METHOD_PREFIX)]] if isinstance(z, collections.Callable)]:
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
            name = method.__name__[len(METHOD_PREFIX):]
            name = name[0].lower() + name[1:]
            self._methodsDict[name] = method
        self._verifyFormatting()

    def _addGlobals(self, globalsDict):
        """Other things to make available from the formatting string.
        """
        globalsDict['obj'] = None
        globalsDict['role'] = None
        globalsDict['pyatspi'] = pyatspi

    def _verifyFormatting(self):

        # Verify the formatting strings are OK.  This is only
        # for verification and does not effect the function of
        # Orca at all.

        # Populate the entire globals with empty arrays
        # for the results of all the legal method names.
        #
        globalsDict = {}
Mario Lang's avatar
Mario Lang committed
104
        for key in self._methodsDict.keys():
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
            globalsDict[key] = []
        self._addGlobals(globalsDict)

        for roleKey in self._script.formatting[self._mode]:
            for key in ["focused", "unfocused"]:
                try:
                    evalString = \
                        self._script.formatting[self._mode][roleKey][key]
                except:
                    continue
                else:
                    if not evalString:
                        # It's legal to have an empty string.
                        #
                        continue
                    while True:
                        try:
                            eval(evalString, globalsDict)
                            break
                        except NameError:
                            info = _formatExceptionInfo()
                            arg = info[1][0]
                            arg = arg.replace("name '", "")
                            arg = arg.replace("' is not defined", "")
129
                            if arg not in self._methodsDict:
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
                                debug.printException(debug.LEVEL_SEVERE)
                            globalsDict[arg] = []
                        except:
                            debug.printException(debug.LEVEL_SEVERE)
                            break

    def _overrideRole(self, newRole, args):
        """Convenience method to allow you to temporarily override the role in
        the args dictionary.  This changes the role in args ags
        returns the old role so you can pass it back to _restoreRole.
        """
        oldRole = args.get('role', None)
        args['role'] = newRole
        return oldRole

    def _restoreRole(self, oldRole, args):
        """Convenience method to restore the old role back in the args
        dictionary.  The oldRole should have been obtained from
        _overrideRole.  If oldRole is None, then the 'role' key/value
        pair will be deleted from args.
        """
        if oldRole:
            args['role'] = oldRole
        else:
            del args['role']

156 157 158
    def generateContents(self, contents, **args):
        return []

159 160 161
    def generateContext(self, obj, **args):
        return []

162 163
    def generate(self, obj, **args):
        """Returns an array of strings (and possibly voice and audio
Ville Skyttä's avatar
Ville Skyttä committed
164 165
        specifications) that represent the complete presentation for the
        object.  The presentation to be generated depends highly upon the
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
        formatting strings in formatting.py.

        args is a dictionary that may contain any of the following:
        - alreadyFocused: if True, we're getting 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
        """
184 185 186 187 188 189

        if self._script.utilities.isDead(obj):
            msg = 'ERROR: Cannot generate presentation dead obj'
            debug.println(debug.LEVEL_INFO, msg, True)
            return []

190
        startTime = time.time()
191 192 193 194
        result = []
        globalsDict = {}
        self._addGlobals(globalsDict)
        globalsDict['obj'] = obj
195 196 197
        try:
            globalsDict['role'] = args.get('role', obj.getRole())
        except:
198 199
            msg = 'ERROR: Cannot generate presentation for: %s. Aborting' % obj
            debug.println(debug.LEVEL_INFO, msg, True)
200
            return result
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
        try:
            # We sometimes want to override the role.  We'll keep the
            # role in the args dictionary as a means to let us do so.
            #
            args['role'] = globalsDict['role']

            # We loop through the format string, catching each error
            # as we go.  Each error should always be a NameError,
            # where the name is the name of one of our generator
            # functions.  When we encounter this, we call the function
            # and get its results, placing them in the globals for the
            # the call to eval.
            #
            args['mode'] = self._mode
            if not args.get('formatType', None):
                if args.get('alreadyFocused', False):
                    args['formatType'] = 'focused'
                else:
                    args['formatType'] = 'unfocused'

221
            formatting = self._script.formatting.getFormat(**args)
222 223 224 225 226 227 228 229

            # Add in the 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(**args)
                    suffix = self._script.formatting.getSuffix(**args)
230
                    formatting = '%s + %s + %s' % (prefix, formatting, suffix)
231 232 233 234 235
                args['recursing'] = True
                firstTimeCalled = True
            else:
                firstTimeCalled = False

236 237
            msg = '%s GENERATOR: Starting generation for %s' % (self._mode.upper(), obj)
            debug.println(debug.LEVEL_INFO, msg, True)
238

Joanmarie Diggs's avatar
Joanmarie Diggs committed
239
            debuginfo = lambda x: self._resultElementToString(x, False)
240
            assert(formatting)
241
            while True:
242
                currentTime = time.time()
243
                try:
244
                    result = eval(formatting, globalsDict)
245 246 247 248 249 250 251
                    break
                except NameError:
                    result = []
                    info = _formatExceptionInfo()
                    arg = info[1][0]
                    arg = arg.replace("name '", "")
                    arg = arg.replace("' is not defined", "")
252
                    if arg not in self._methodsDict:
253 254 255
                        debug.printException(debug.LEVEL_SEVERE)
                        break
                    globalsDict[arg] = self._methodsDict[arg](obj, **args)
256
                    duration = "%.4f" % (time.time() - currentTime)
Joanmarie Diggs's avatar
Joanmarie Diggs committed
257 258 259 260 261
                    if isinstance(globalsDict[arg], list):
                        stringResult = " ".join(filter(lambda x: x, map(debuginfo, globalsDict[arg])))
                        debug.println(debug.LEVEL_ALL,
                                      "%sGENERATION TIME: %s  ---->  %s=[%s]" \
                                      % (" " * 18, duration, arg, stringResult))
262

263 264 265 266
        except:
            debug.printException(debug.LEVEL_SEVERE)
            result = []

267
        duration = "%.4f" % (time.time() - startTime)
Joanmarie Diggs's avatar
Joanmarie Diggs committed
268
        debug.println(debug.LEVEL_ALL, "%sCOMPLETION TIME: %s" % (' ' * 18, duration))
Joanmarie Diggs's avatar
Joanmarie Diggs committed
269
        self._debugResultInfo(result)
270 271 272
        if args.get('isProgressBarUpdate') and result:
            self.setProgressBarUpdateTimeAndValue(obj)

273
        return result
274

Joanmarie Diggs's avatar
Joanmarie Diggs committed
275 276 277 278 279 280 281 282 283 284 285 286 287 288
    def _resultElementToString(self, element, includeAll=True):
        if not includeAll:
            return str(element)

        return "\n%s'%s'" % (" " * 18, element)

    def _debugResultInfo(self, result):
        if debug.LEVEL_ALL < debug.debugLevel:
            return

        info = "%s%s GENERATOR: Results: " % (" " * 18, self._mode.upper())
        info += "%s" % " ".join(map(self._resultElementToString, result))
        debug.println(debug.LEVEL_ALL, info)

289 290 291 292 293 294
    #####################################################################
    #                                                                   #
    # Name, role, and label information                                 #
    #                                                                   #
    #####################################################################

295 296 297 298 299 300 301 302 303
    def _generateRoleName(self, obj, **args):
        """Returns the role name for the object in an array of strings, with
        the exception that the pyatspi.ROLE_UNKNOWN role will yield an
        empty array.  Note that a 'role' attribute in args will
        override the accessible role of the obj.
        """
        # Subclasses must override this.
        return []

304 305 306 307 308 309 310
    def _fallBackOnDescriptionForName(self, obj, **args):
        role = args.get('role', obj.getRole())
        if role == pyatspi.ROLE_LABEL:
            return False

        return True

311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
    def _generateName(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the name of the object.  If the object is directly
        displaying any text, that text will be treated as the name.
        Otherwise, the accessible name of the object will be used.  If
        there is no accessible name, then the description of the
        object will be used.  This method will return an empty array
        if nothing can be found.  [[[WDW - I wonder if we should just
        have _generateName, _generateDescription,
        _generateDisplayedText, etc., that don't do any fallback.
        Then, we can allow the formatting to do the fallback (e.g.,
        'displayedText or name or description'). [[[JD to WDW - I
        needed a _generateDescription for whereAmI. :-) See below.
        """
        result = []
326
        self._script.pointOfReference['usedDescriptionForName'] = False
327
        name = obj.name
328 329
        if name:
            result.append(name)
330
        elif self._fallBackOnDescriptionForName(obj, **args):
331 332
            try:
                description = obj.description
333
            except (LookupError, RuntimeError):
334 335 336
                return result
            if description:
                result.append(description)
337
                self._script.pointOfReference['usedDescriptionForName'] = True
338 339 340 341
            else:
                link = None
                if obj.getRole() == pyatspi.ROLE_LINK:
                    link = obj
Joanmarie Diggs's avatar
Joanmarie Diggs committed
342
                elif obj.parent and obj.parent.getRole() == pyatspi.ROLE_LINK:
343 344 345
                    link = obj.parent
                if link:
                    basename = self._script.utilities.linkBasename(link)
346
                    if basename and basename.isalpha():
347
                        result.append(basename)
348
        # To make the unlabeled icons in gnome-panel more accessible.
349 350 351 352
        try:
            role = args.get('role', obj.getRole())
        except (LookupError, RuntimeError):
            return result
353 354 355 356
        if not result and obj.getRole() == pyatspi.ROLE_ICON \
           and obj.parent.getRole() == pyatspi.ROLE_PANEL:
            return self._generateName(obj.parent)

357 358
        return result

359 360 361 362 363 364 365 366
    def _generatePlaceholderText(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the 'placeholder' text. This is typically text that
        serves as a functional label and is found in a text widget until
        that widget is given focus at which point the text is removed,
        the assumption being that the user was able to see the text prior
        to giving the widget focus.
        """
367 368 369 370 371
        attrs = self._script.utilities.objectAttributes(obj)
        placeholder = attrs.get('placeholder-text')
        if placeholder:
            return [placeholder]

372 373 374 375
        placeholder = attrs.get('placeholder')
        if placeholder:
            return [placeholder]

376
        return []
377

378 379 380 381 382 383 384 385
    def _generateLabelAndName(self, obj, **args):
        """Returns the label and the name as an array of strings for speech
        and braille.  The name will only be present if the name is
        different from the label.
        """
        result = []
        label = self._generateLabel(obj, **args)
        name = self._generateName(obj, **args)
386 387 388 389 390
        role = args.get('role', obj.role)
        if not (label or name) and role == pyatspi.ROLE_TABLE_CELL:
            descendant = self._script.utilities.realActiveDescendant(obj)
            name = self._generateName(descendant)

391 392 393
        result.extend(label)
        if not len(label):
            result.extend(name)
394 395
        elif len(name) and name[0].split() != label[0].split() \
             and not label[0].startswith(name[0]):
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
            result.extend(name)
        return result

    def _generateLabelOrName(self, obj, **args):
        """Returns the label as an array of strings for speech and braille.
        If the label cannot be found, the name will be used instead.
        If the name cannot be found, an empty array will be returned.
        """
        result = []
        result.extend(self._generateLabel(obj, **args))
        if not result:
            if obj.name and (len(obj.name)):
                result.append(obj.name)
        return result

    def _generateDescription(self, obj, **args):
        """Returns an array of strings fo use by speech and braille that
        represent the description of the object, if that description
        is different from that of the name and label.
        """
416

417 418 419
        if self._script.pointOfReference.get('usedDescriptionForName'):
            return []

420 421
        role = args.get('role', obj.getRole())

422 423 424 425 426 427
        # Unity Panel Service menubar items are labels which claim focus and
        # have an accessible description of the text + underscore symbol used
        # to create the mnemonic. We'll work around that here for now.
        if role == pyatspi.ROLE_LABEL:
            return []

428 429 430 431 432 433 434 435 436
        try:
            name = obj.name
            description = obj.description
        except:
            msg = "ERROR: Exception getting name and description for %s" % obj
            debug.println(debug.LEVEL_INFO, msg, True)
            name = ""
            description = ""

437 438 439
        if role == pyatspi.ROLE_ICON:
            name = self._script.utilities.displayedText(obj) or ""

440
        result = []
441
        if description:
442
            label = self._script.utilities.displayedLabel(obj) or ""
443
            desc = description.lower()
444 445
            if not (desc in name.lower() or desc in label.lower()):
                result.append(obj.description)
446 447 448 449 450 451

        if not result:
            desc = self._script.utilities.displayedDescription(obj)
            if desc:
                result.append(desc)

452 453
        return result

454 455
    def _generateLabel(self, obj, **args):
        """Returns the label for an object as an array of strings for use by
456 457 458
        speech and braille.  The label is determined by the displayedLabel
        method of the script utility, and an empty array will be returned if
        no label can be found.
459 460
        """
        result = []
461
        label = self._script.utilities.displayedLabel(obj)
462 463 464 465
        if label:
            result.append(label)
        return result

466 467 468 469 470
    def generateStatusBar(self, obj, **args):
        """Returns an array of strings that represent a status bar."""

        return self._generateStatusBar(obj, **args)

471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
    #####################################################################
    #                                                                   #
    # Image information                                                 #
    #                                                                   #
    #####################################################################

    def _generateImageDescription(self, obj, **args ):
        """Returns an array of strings for use by speech and braille that
        represent the description of the image on the object, if it
        exists.  Otherwise, an empty array is returned.
        """
        result = []
        try:
            image = obj.queryImage()
        except NotImplementedError:
            pass
        else:
            description = image.imageDescription
            if description and len(description):
                result.append(description)
        return result

493 494 495 496 497 498
    #####################################################################
    #                                                                   #
    # State information                                                 #
    #                                                                   #
    #####################################################################

Joanmarie Diggs's avatar
Joanmarie Diggs committed
499 500 501
    def _generateClickable(self, obj, **args):
        return []

Joanmarie Diggs's avatar
Joanmarie Diggs committed
502 503 504
    def _generateHasLongDesc(self, obj, **args):
        return []

505 506 507
    def _generateHasDetails(self, obj, **args):
        return []

508 509 510
    def _generateDetailsFor(self, obj, **args):
        return []

511 512 513
    def _generateAllDetails(self, obj, **args):
        return []

514 515 516
    def _generateHasPopup(self, obj, **args):
        return []

517 518 519 520 521 522 523 524 525 526 527 528 529 530
    def _generateAvailability(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the grayed/sensitivity/availability state of the
        object, but only if it is insensitive (i.e., grayed out and
        inactive).  Otherwise, and empty array will be returned.
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'insensitive'
        if not obj.getState().contains(pyatspi.STATE_SENSITIVE):
            result.append(self._script.formatting.getString(**args))
        return result

Joanmarie Diggs's avatar
Joanmarie Diggs committed
531 532 533 534 535 536 537 538 539 540 541 542
    def _generateInvalid(self, obj, **args):
        error = self._script.utilities.getError(obj)
        if not error:
            return []

        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'invalid'
        indicators = self._script.formatting.getString(**args)

        if error == 'spelling':
543
            indicator = indicators[1]
Joanmarie Diggs's avatar
Joanmarie Diggs committed
544
        elif error == 'grammar':
545
            indicator = indicators[2]
Joanmarie Diggs's avatar
Joanmarie Diggs committed
546
        else:
547 548 549 550 551 552 553 554
            indicator = indicators[0]

        errorMessage = self._script.utilities.getErrorMessage(obj)
        if errorMessage:
            result.append("%s: %s" % (indicator, errorMessage))
        else:
            result.append(indicator)

Joanmarie Diggs's avatar
Joanmarie Diggs committed
555 556
        return result

557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
    def _generateRequired(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the required state of the object, but only if it is
        required (i.e., it is in a dialog requesting input and the
        user must give it a value).  Otherwise, and empty array will
        be returned.
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'required'
        if obj.getState().contains(pyatspi.STATE_REQUIRED) \
           or (obj.getRole() == pyatspi.ROLE_RADIO_BUTTON \
               and obj.parent.getState().contains(pyatspi.STATE_REQUIRED)):
            result.append(self._script.formatting.getString(**args))
        return result

    def _generateReadOnly(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the read only state of this object, but only if it
        is read only (i.e., it is a text area that cannot be edited).
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'readonly'
583
        if self._script.utilities.isReadOnlyTextArea(obj):
584 585 586
            result.append(self._script.formatting.getString(**args))
        return result

587 588 589 590 591 592 593
    def _generateCellCheckedState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the checked state of the object.  This is typically
        for check boxes that are in a table. An empty array will be
        returned if this is not a checkable cell.
        """
        result = []
Joanmarie Diggs's avatar
Joanmarie Diggs committed
594 595 596 597 598
        if self._script.utilities.hasMeaningfulToggleAction(obj):
            oldRole = self._overrideRole(pyatspi.ROLE_CHECK_BOX, args)
            result.extend(self.generate(obj, **args))
            self._restoreRole(oldRole, args)

599 600
        return result

601 602 603 604 605 606 607 608 609 610
    def _generateCheckedState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the checked state of the object.  This is typically
        for check boxes. [[[WDW - should we return an empty array if
        we can guarantee we know this thing is not checkable?]]]
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'checkbox'
611
        indicators = self._script.formatting.getString(**args)
612
        state = obj.getState()
613
        if state.contains(pyatspi.STATE_CHECKED):
614
            result.append(indicators[1])
615 616
        elif state.contains(pyatspi.STATE_INDETERMINATE):
            result.append(indicators[2])
617
        else:
618
            result.append(indicators[0])
619 620 621 622 623 624 625 626 627 628 629 630
        return result

    def _generateRadioState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the checked state of the object.  This is typically
        for check boxes. [[[WDW - should we return an empty array if
        we can guarantee we know this thing is not checkable?]]]
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'radiobutton'
631
        indicators = self._script.formatting.getString(**args)
632 633
        state = obj.getState()
        if state.contains(pyatspi.STATE_CHECKED):
634
            result.append(indicators[1])
635
        else:
636
            result.append(indicators[0])
637 638
        return result

639 640
    def _generateChildWidget(self, obj, **args):
        widgetRoles = [pyatspi.ROLE_CHECK_BOX,
641
                       pyatspi.ROLE_COMBO_BOX,
642
                       pyatspi.ROLE_PUSH_BUTTON,
643
                       pyatspi.ROLE_RADIO_BUTTON,
644
                       pyatspi.ROLE_SLIDER,
645 646 647 648 649 650 651 652 653 654 655
                       pyatspi.ROLE_TOGGLE_BUTTON]
        isWidget = lambda x: x and x.getRole() in widgetRoles

        # For GtkListBox, such as those found in the control center
        if obj.parent and obj.parent.getRole() == pyatspi.ROLE_LIST_BOX:
            widget = pyatspi.findDescendant(obj, isWidget)
            if widget:
                return self.generate(widget, includeContext=False)

        return []

656 657 658 659 660 661 662 663 664 665 666 667 668 669
    def _generateSwitchState(self, obj, **args):
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'switch'
        indicators = self._script.formatting.getString(**args)
        state = obj.getState()
        if state.contains(pyatspi.STATE_CHECKED) \
           or state.contains(pyatspi.STATE_PRESSED):
            result.append(indicators[1])
        else:
            result.append(indicators[0])
        return result

670 671 672 673 674 675 676 677 678 679
    def _generateToggleState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the checked state of the object.  This is typically
        for check boxes. [[[WDW - should we return an empty array if
        we can guarantee we know this thing is not checkable?]]]
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'togglebutton'
680
        indicators = self._script.formatting.getString(**args)
681 682 683
        state = obj.getState()
        if state.contains(pyatspi.STATE_CHECKED) \
           or state.contains(pyatspi.STATE_PRESSED):
684
            result.append(indicators[1])
685
        else:
686
            result.append(indicators[0])
687 688
        return result

Joanmarie Diggs's avatar
Joanmarie Diggs committed
689 690 691 692 693
    def _generateCheckedStateIfCheckable(self, obj, **args):
        if obj.getState().contains(pyatspi.STATE_CHECKABLE) \
           or obj.getRole() == pyatspi.ROLE_CHECK_MENU_ITEM:
            return self._generateCheckedState(obj, **args)

694 695 696
        if obj.getState().contains(pyatspi.STATE_CHECKED):
            return self._generateCheckedState(obj, **args)

Joanmarie Diggs's avatar
Joanmarie Diggs committed
697 698
        return []

699 700 701 702 703 704 705 706 707
    def _generateMenuItemCheckedState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the checked state of the menu item, only if it is
        checked. Otherwise, and empty array will be returned.
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'checkbox'
708
        indicators = self._script.formatting.getString(**args)
709
        if obj.getState().contains(pyatspi.STATE_CHECKED):
710
            result.append(indicators[1])
711 712 713 714 715 716 717 718 719 720 721 722
        return result

    def _generateExpandableState(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the expanded/collapsed state of an object, such as a
        tree node. If the object is not expandable, an empty array
        will be returned.
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'expansion'
723
        indicators = self._script.formatting.getString(**args)
724
        state = obj.getState()
725 726 727 728 729 730 731
        if state.contains(pyatspi.STATE_COLLAPSED):
            result.append(indicators[0])
        elif state.contains(pyatspi.STATE_EXPANDED):
            result.append(indicators[1])
        elif state.contains(pyatspi.STATE_EXPANDABLE):
            result.append(indicators[0])

732 733
        return result

734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749
    def _generateMultiselectableState(self, obj, **args):
        """Returns an array of strings (and possibly voice and audio
        specifications) that represent the multiselectable state of
        the object.  This is typically for list boxes. If the object
        is not multiselectable, an empty array will be returned.
        """

        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'multiselect'
        if obj.getState().contains(pyatspi.STATE_MULTISELECTABLE) \
           and obj.childCount:
            result.append(self._script.formatting.getString(**args))
        return result

750 751 752 753 754 755 756 757 758 759 760
    #####################################################################
    #                                                                   #
    # Table interface information                                       #
    #                                                                   #
    #####################################################################

    def _generateRowHeader(self, obj, **args):
        """Returns an array of strings to be used in speech and braille that
        represent the row header for an object that is in a table, if
        it exists.  Otherwise, an empty array is returned.
        """
761 762 763 764

        if args.get('readingRow'):
            return []

765
        result = []
766 767
        header = self._script.utilities.rowHeaderForCell(obj)
        if not header:
768 769
            return result

770
        text = self._script.utilities.displayedText(header)
771 772 773
        if not text:
            return result

774
        roleString =  self.getLocalizedRoleName(obj, role=pyatspi.ROLE_ROW_HEADER)
775 776 777 778 779 780 781 782
        if args.get('mode') == 'speech':
            if settings.speechVerbosityLevel == settings.VERBOSITY_LEVEL_VERBOSE \
               and not args.get('formatType') in ['basicWhereAmI', 'detailedWhereAmI']:
                text = "%s %s" % (text, roleString)
        elif args.get('mode') == 'braille':
            text = "%s %s" % (text, roleString)

        result.append(text)
783 784 785 786 787 788 789 790 791
        return result

    def _generateColumnHeader(self, obj, **args):
        """Returns an array of strings (and possibly voice and audio
        specifications) that represent the column header for an object
        that is in a table, if it exists.  Otherwise, an empty array
        is returned.
        """
        result = []
792 793
        header = self._script.utilities.columnHeaderForCell(obj)
        if not header:
794 795
            return result

796
        text = self._script.utilities.displayedText(header)
797 798 799
        if not text:
            return result

800
        roleString =  self.getLocalizedRoleName(obj, role=pyatspi.ROLE_COLUMN_HEADER)
801 802 803 804 805 806 807 808
        if args.get('mode') == 'speech':
            if settings.speechVerbosityLevel == settings.VERBOSITY_LEVEL_VERBOSE \
               and not args.get('formatType') in ['basicWhereAmI', 'detailedWhereAmI']:
                text = "%s %s" % (text, roleString)
        elif args.get('mode') == 'braille':
            text = "%s %s" % (text, roleString)

        result.append(text)
809 810
        return result

811 812 813 814 815 816 817 818 819 820 821 822
    def _generateSortOrder(self, obj, **args):
        if not self._script.utilities.isSorted(obj):
            return []

        if self._script.utilities.isAscending(obj):
            return [object_properties.SORT_ORDER_ASCENDING]

        if self._script.utilities.isDescending(obj):
            return [object_properties.SORT_ORDER_DESCENDING]

        return [object_properties.SORT_ORDER_OTHER]

823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841
    def _generateTableCell2ChildLabel(self, obj, **args):
        """Returns an array of strings for use by speech and braille for the
        label of a toggle in a table cell that has a special 2 child
        pattern that we run into.  Otherwise, an empty array is
        returned.
        """
        result = []

        # If this table cell has 2 children and one of them has a
        # 'toggle' action and the other does not, then present this
        # as a checkbox where:
        # 1) we get the checked state from the cell with the 'toggle' action
        # 2) we get the label from the other cell.
        # See Orca bug #376015 for more details.
        #
        if obj.childCount == 2:
            cellOrder = []
            hasToggle = [False, False]
            for i, child in enumerate(obj):
Joanmarie Diggs's avatar
Joanmarie Diggs committed
842 843 844
                if self._script.utilities.hasMeaningfulToggleAction(child):
                    hasToggle[i] = True
                    break
845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873
            if hasToggle[0] and not hasToggle[1]:
                cellOrder = [ 1, 0 ]
            elif not hasToggle[0] and hasToggle[1]:
                cellOrder = [ 0, 1 ]
            if cellOrder:
                for i in cellOrder:
                    if not hasToggle[i]:
                        result.extend(self.generate(obj[i], **args))
        return result

    def _generateTableCell2ChildToggle(self, obj, **args):
        """Returns an array of strings for use by speech and braille for the
        toggle value of a toggle in a table cell that has a special 2
        child pattern that we run into.  Otherwise, an empty array is
        returned.
        """
        result = []

        # If this table cell has 2 children and one of them has a
        # 'toggle' action and the other does not, then present this
        # as a checkbox where:
        # 1) we get the checked state from the cell with the 'toggle' action
        # 2) we get the label from the other cell.
        # See Orca bug #376015 for more details.
        #
        if obj.childCount == 2:
            cellOrder = []
            hasToggle = [False, False]
            for i, child in enumerate(obj):
Joanmarie Diggs's avatar
Joanmarie Diggs committed
874 875 876
                if self._script.utilities.hasMeaningfulToggleAction(child):
                    hasToggle[i] = True
                    break
877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898
            if hasToggle[0] and not hasToggle[1]:
                cellOrder = [ 1, 0 ]
            elif not hasToggle[0] and hasToggle[1]:
                cellOrder = [ 0, 1 ]
            if cellOrder:
                for i in cellOrder:
                    if hasToggle[i]:
                        result.extend(self.generate(obj[i], **args))
        return result

    def _generateColumnHeaderIfToggleAndNoText(self, obj, **args):
        """If this table cell has a "toggle" action, and doesn't have any
        label associated with it then also speak the table column
        header.  See Orca bug #455230 for more details.
        """
        # If we're reading just a single cell in speech, the new
        # header portion is going to give us this information.
        #
        if args['mode'] == 'speech' and not args.get('readingRow', False):
            return []

        result = []
899 900 901 902 903
        descendant = self._script.utilities.realActiveDescendant(obj)
        label = self._script.utilities.displayedText(descendant)
        if not label and self._script.utilities.hasMeaningfulToggleAction(obj):
            accHeader = self._script.utilities.columnHeaderForCell(obj)
            result.append(accHeader.name)
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919
        return result

    def _generateRealTableCell(self, obj, **args):
        """Orca has a feature to automatically read an entire row of a table
        as the user arrows up/down the roles.  This leads to
        complexity in the code.  This method is used to return an
        array of strings for use by speech and braille for a single
        table cell itself.  The string, 'blank', is added for empty
        cells.
        """
        result = []
        oldRole = self._overrideRole('REAL_ROLE_TABLE_CELL', args)
        result.extend(self.generate(obj, **args))
        self._restoreRole(oldRole, args)
        return result

920 921 922 923
    def _generateTable(self, obj, **args):
        """Returns an array of strings for use by speech and braille to present
        the size of a table."""

924 925 926
        if self._script.utilities.isLayoutOnly(obj):
            return []

927 928
        rows, cols = self._script.utilities.rowAndColumnCount(obj)
        if rows < 0 or cols < 0:
929
            return []
930

931
        return [messages.tableSize(rows, cols)]
932

933 934 935 936 937 938 939 940 941 942
    def _generateTableCellRow(self, obj, **args):
        """Orca has a feature to automatically read an entire row of a table
        as the user arrows up/down the roles.  This leads to complexity in
        the code.  This method is used to return an array of strings
        (and possibly voice and audio specifications) for an entire row
        in a table if that's what the user has requested and if the row
        has changed.  Otherwise, it will return an array for just the
        current cell.
        """

943 944 945 946
        presentAll = args.get('readingRow') == True \
            or args.get('formatType') == 'detailedWhereAmI' \
            or self._mode == 'braille' \
            or self._script.utilities.shouldReadFullRow(obj)
947

948 949 950 951 952 953
        if not presentAll:
            return self._generateRealTableCell(obj, **args)

        args['readingRow'] = True
        result = []
        cells = self._script.utilities.getShowingCellsInSameRow(obj, forceFullRow=True)
954 955 956 957 958 959 960

        # Remove any pre-calcuated values which only apply to obj and not row cells.
        doNotInclude = ['startOffset', 'endOffset', 'string']
        otherCellArgs = args.copy()
        for arg in doNotInclude:
            otherCellArgs.pop(arg, None)

961
        for cell in cells:
962 963 964 965
            if cell == obj:
                cellResult = self._generateRealTableCell(cell, **args)
            else:
                cellResult = self._generateRealTableCell(cell, **otherCellArgs)
966 967 968 969 970
            if cellResult and result and self._mode == 'braille':
                result.append(braille.Region(object_properties.TABLE_CELL_DELIMITER_BRAILLE))
            result.extend(cellResult)

        result.extend(self._generatePositionInList(obj, **args))
971 972
        return result

973 974 975 976 977 978
    #####################################################################
    #                                                                   #
    # Text interface information                                        #
    #                                                                   #
    #####################################################################

979 980 981 982
    def _generateExpandedEOCs(self, obj, **args):
        """Returns the expanded embedded object characters for an object."""
        return []

983 984 985
    def _generateSubstring(self, obj, **args):
        start = args.get('startOffset')
        end = args.get('endOffset')
986
        if start is None or end is None:
987 988
            return []

989
        substring = args.get('string', self._script.utilities.substring(obj, start, end))
990
        if substring and not self._script.EMBEDDED_OBJECT_CHARACTER in substring:
991 992 993 994 995 996 997 998 999 1000
            return [substring]

        return []

    def _generateStartOffset(self, obj, **args):
        return args.get('startOffset')

    def _generateEndOffset(self, obj, **args):
        return args.get('endOffset')

1001 1002 1003 1004 1005 1006
    def _generateCurrentLineText(self, obj, **args ):
        """Returns an array of strings for use by speech and braille
        that represents the current line of text, if
        this is a text object.  [[[WDW - consider returning an empty
        array if this is not a text object.]]]
        """
1007 1008 1009 1010
        result = self._generateSubstring(obj, **args)
        if result:
            return result

1011
        [text, caretOffset, startOffset] = self._script.getTextLineAtCaret(obj)
1012 1013 1014 1015
        if text and not self._script.EMBEDDED_OBJECT_CHARACTER in text:
            return [text]

        return []
1016

1017 1018
    def _generateDisplayedText(self, obj, **args ):
        """Returns an array of strings for use by speech and braille that
1019
        represents all the text being displayed by the object.
1020
        """
1021 1022 1023 1024
        result = self._generateSubstring(obj, **args)
        if result:
            return result

1025 1026 1027 1028 1029
        displayedText = self._script.utilities.displayedText(obj)
        if not displayedText:
            return []

        return [displayedText]
1030

1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045
    #####################################################################
    #                                                                   #
    # Tree interface information                                        #
    #                                                                   #
    #####################################################################

    def _generateNodeLevel(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represents the tree node level of the object, or an empty
        array if the object is not a tree node.
        """
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'nodelevel'
1046
        level = self._script.utilities.nodeLevel(obj)
1047 1048 1049 1050 1051
        if level >= 0:
            result.append(self._script.formatting.getString(**args)\
                          % (level + 1))
        return result

1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064
    #####################################################################
    #                                                                   #
    # Value interface information                                       #
    #                                                                   #
    #####################################################################

    def _generateValue(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represents the value of the object.  This is typically the
        numerical value, but may also be the text of the 'value'
        attribute if it exists on the object.  [[[WDW - we should
        consider returning an empty array if there is no value.
        """
1065 1066 1067 1068 1069 1070

        role = args.get('role', obj.getRole())
        if role == pyatspi.ROLE_COMBO_BOX:
            value = self._script.utilities.getComboBoxValue(obj)
            return [value]

1071 1072 1073
        if role == pyatspi.ROLE_SEPARATOR and not obj.getState().contains(pyatspi.STATE_FOCUSED):
            return []

1074
        return [self._script.utilities.textForValue(obj)]
1075 1076 1077 1078 1079 1080 1081 1082 1083

    #####################################################################
    #                                                                   #
    # Hierarchy and related dialog information                          #
    #                                                                   #
    #####################################################################

    def _generateApplicationName(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
Ville Skyttä's avatar
Ville Skyttä committed
1084
        represents the name of the application for the object.
1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096
        """
        result = []
        try:
            result.append(obj.getApplication().name)
        except:
            pass
        return result

    def _generateNestingLevel(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represent the nesting level of an object in a list.
        """
1097 1098 1099 1100 1101
        start = args.get('startOffset')
        end = args.get('endOffset')
        if start is not None and end is not None:
            return []

1102 1103 1104 1105
        result = []
        if not args.get('mode', None):
            args['mode'] = self._mode
        args['stringType'] = 'nestinglevel'
1106
        nestingLevel = self._script.utilities.nestingLevel(obj)
1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117
        if nestingLevel:
            result.append(self._script.formatting.getString(**args)\
                          % nestingLevel)
        return result

    def _generateRadioButtonGroup(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represents the radio button group label for the object, or an
        empty array if the object has no such label.
        """
        result = []
1118 1119 1120 1121 1122
        try:
            role = obj.getRole()
        except:
            role = None
        if role == pyatspi.ROLE_RADIO_BUTTON:
1123 1124 1125 1126 1127 1128 1129 1130 1131
            radioGroupLabel = None
            relations = obj.getRelationSet()
            for relation in relations:
                if (not radioGroupLabel) \
                    and (relation.getRelationType() \
                         == pyatspi.RELATION_LABELLED_BY):
                    radioGroupLabel = relation.getTarget(0)
                    break
            if radioGroupLabel:
1132 1133
                result.append(self._script.utilities.\
                                  displayedText(radioGroupLabel))
1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153
            else:
                parent = obj.parent
                while parent and (parent.parent != parent):
                    if parent.getRole() in [pyatspi.ROLE_PANEL,
                                            pyatspi.ROLE_FILLER]:
                        label = self._generateLabelAndName(parent)
                        if label:
                            result.extend(label)
                            break
                    parent = parent.parent
        return result

    def _generateRealActiveDescendantDisplayedText(self, obj, **args ):
        """Objects, such as tables and trees, can represent individual cells
        via a complicated nested hierarchy.  This method returns an
        array of strings for use by speech and braille that represents
        the text actually being painted in the cell, if it can be
        found.  Otherwise, an empty array is returned.
        """
        result = []
1154
        rad = self._script.utilities.realActiveDescendant(obj)
1155 1156 1157 1158

        if not (rad.getRole() == pyatspi.ROLE_TABLE_CELL and rad.childCount):
            return self._generateDisplayedText(rad, **args)

1159
        content = set([self._script.utilities.displayedText(x).strip() for x in rad])
1160
        return [" ".join(filter(lambda x: x, content))]
1161 1162 1163 1164 1165 1166 1167

    def _generateRealActiveDescendantRoleName(self, obj, **args ):
        """Objects, such as tables and trees, can represent individual cells
        via a complicated nested hierarchy.  This method returns an
        array of strings for use by speech and braille that represents
        the role of the object actually being painted in the cell.
        """
1168
        rad = self._script.utilities.realActiveDescendant(obj)
1169 1170
        args['role'] = rad.getRole()
        return self._generateRoleName(rad, **args)
1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185

    def _generateNamedContainingPanel(self, obj, **args):
        """Returns an array of strings for use by speech and braille that
        represents the nearest ancestor of an object which is a named panel.
        """
        result = []
        parent = obj.parent
        while parent and (parent.parent != parent):
            if parent.getRole() == pyatspi.ROLE_PANEL:
                label = self._generateLabelAndName(parent)
                if label:
                    result.extend(label)
                    break
            parent = parent.parent
        return result
1186 1187 1188

    def _generatePageSummary(self, obj, **args):
        return []
Joanmarie Diggs's avatar
Joanmarie Diggs committed
1189

1190 1191 1192
    def _generatePositionInList(self, obj, **args):
        return []

Joanmarie Diggs's avatar
Joanmarie Diggs committed
1193 1194 1195 1196 1197
    def _generateProgressBarIndex(self, obj, **args):
        return []

    def _generateProgressBarValue(self, obj, **args):
        return []
1198

1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247
    def _getProgressBarUpdateInterval(self):
        return int(_settingsManager.getSetting('progressBarUpdateInterval'))

    def _shouldPresentProgressBarUpdate(self, obj, **args):
        percent = self._script.utilities.getValueAsPercent(obj)
        lastTime, lastValue = self.getProgressBarUpdateTimeAndValue(obj, type=self)
        if percent == lastValue:
            return False

        if percent == 100:
            return True

        interval = int(time.time() - lastTime)
        return interval >= self._getProgressBarUpdateInterval()

    def _cleanUpCachedProgressBars(self):
        isValid = lambda x: not (self._script.utilities.isZombie(x) or self._script.utilities.isDead(x))
        bars = list(filter(isValid, self._activeProgressBars))
        self._activeProgressBars = {x:self._activeProgressBars.get(x) for x in bars}

    def _getMostRecentProgressBarUpdate(self):
        self._cleanUpCachedProgressBars()
        if not self._activeProgressBars.values():
            return None, 0.0, None

        sortedValues = sorted(self._activeProgressBars.values(), key=lambda x: x[0])
        prevTime, prevValue = sortedValues[-1]
        return list(self._activeProgressBars.keys())[-1], prevTime, prevValue

    def getProgressBarNumberAndCount(self, obj):
        self._cleanUpCachedProgressBars()
        if not obj in self._activeProgressBars:
            self._activeProgressBars[obj] = 0.0, None

        thisValue = self.getProgressBarUpdateTimeAndValue(obj)
        index = list(self._activeProgressBars.values()).index(thisValue)
        return index + 1, len(self._activeProgressBars)

    def getProgressBarUpdateTimeAndValue(self, obj, **args):
        if not obj in self._activeProgressBars:
            self._activeProgressBars[obj] = 0.0, None

        return self._activeProgressBars.get(obj)

    def setProgressBarUpdateTimeAndValue(self, obj, lastTime=None, lastValue=None):
        lastTime = lastTime or time.time()
        lastValue = lastValue or self._script.utilities.getValueAsPercent(obj)
        self._activeProgressBars[obj] = lastTime, lastValue

1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263
    def _getAlternativeRole(self, obj, **args):
        if self._script.utilities.isMath(obj):
            if self._script.utilities.isMathSubOrSuperScript(obj