Task.Tools.View

31 ''' 32 Provides methods for reading information from accessible objects and for 33 navigating relative to a L{POR}. 34 35 Methods prefixed with I{get} do not modify the L{task_por} variable. They 36 only return the L{POR} of interest. Methods prefixed with I{move} do modify 37 these variables. Methods prefixed with I{set} actually change properties of 38 the accessible itself. 39 40 @note: Selected and editable states not being announced because they happen a 41 unexpected times or on undesireable accessibles. Selection can probably be 42 done properly with events. Editable we will just avoid for the time being. 43 44 @cvar _state_descriptions: Mapping from state name/value pairs to localized 45 string 46 @type _state_descriptions: dictionary of 2-tuple, string pairs 47 ''' 48 _state_descriptions = {('checked', False) : _('unchecked'), 49 ('enabled', False) : _('disabled'), 50 #('selected', False) : _('not selected'), 51 ('collapsed', False) : _('expanded'), 52 ('expanded', False) : _('collapsed'), 53 ('animated', False) : _('not animated'), 54 #('editable', False) : _('not editable'), 55 ('checked', True) : _('checked'), 56 ('unchecked', True) : _('unchecked'), 57 #('selected', True) : _('selected'), 58 ('collapsed', True) : _('collapsed'), 59 ('expanded', True) : _('expanded'), 60 ('animated', True) : _('animated'), 61 ('disabled', True) : _('disabled'), 62 #('editable', True) : _('editable') 63 } 64

65 - def getAccFloatValue(self, por=None):

66 ''' 67 Gets the floating point value at the given L{POR}. 68 When L{por} is None, the L{task_por} is used. 69 70 @param por: A point of regard; uses the current task's POR if none supplied 71 @type por: L{POR} 72 @return: Floating point value 73 @rtype: float 74 @raise PORError: When the L{POR} is invalid 75 ''' 76 por = por or self.task_por 77 try: 78 ai = IAccessibleInfo(por) 79 return ai.getAccFloatValue() 80 except LookupError: 81 raise PORError 82 except NotImplementedError: 83 return None

84

85 - def getAccFloatValueExtents(self, por=None):

86 ''' 87 Get the extents and step size of the floating point value at the L{POR}. 88 When L{por} is None, the L{task_por} is used. 89 90 @param por: A point of regard; uses the current task's POR if none supplied 91 @type por: L{POR} 92 @return: The minimum possible value, the maximum possible value, and the 93 step size for the floating point value 94 @rtype: 3-tuple of float 95 @raise PORError: When the L{POR} is invalid 96 ''' 97 por = por or self.task_por 98 try: 99 ai = IAccessibleInfo(por) 100 return ai.getAccFloatValueExtents() 101 except LookupError: 102 raise PORError 103 except NotImplementedError: 104 return None

105

106 - def getAccDefTextAttrs(self, por=None):

107 ''' 108 Gets a dictionary of name:value default text attribute pairs at the provided 109 L{POR}. When L{por} is None, the L{task_por} is used. 110 111 @param por: A point of regard; uses the current task's POR if none supplied 112 @type por: L{POR} 113 @return: Name/value pairs for all available attributes 114 @rtype: dictionary 115 @raise PORError: When the L{POR} is invalid 116 ''' 117 por = por or self.task_por 118 try: 119 # get the info interface 120 ai = IAccessibleInfo(por) 121 return ai.getAccDefTextAttrs() 122 except LookupError: 123 # raise POR error if some accessible was dead, bad or missing 124 raise PORError 125 except NotImplementedError: 126 return None

127

128 - def getAccTextSelection(self, n=None, por=None):

129 ''' 130 Gets a list of all selected text if n is None, or the nth selection if it 131 is specified, at the L{POR}. When L{por} is None, the L{task_por} is used. 132 133 @param n: Index of text selection to get or None 134 @type n: integer 135 @param por: A point of regard; uses the current task's POR if none supplied 136 @type por: L{POR} 137 @return: List of selected text strings 138 @rtype: list of string 139 @raise PORError: When the L{POR} is invalid 140 ''' 141 por = por or self.task_por 142 try: 143 ai = IAccessibleInfo(por) 144 return ai.getAccTextSelection(n) 145 except LookupError: 146 raise PORError 147 except NotImplementedError: 148 return None

149

150 - def getAccText(self, start=None, end=None):

151 ''' 152 Gets all of the text from the starting offset to the ending offset at the 153 given L{POR}s. If start is None, defaults to the beginning of the text. If 154 end is None, defaults to the end of the text. When L{start} or L{end} is 155 None, the L{task_por} is used possibly for both cases. 156 157 @param start: Point of regard to the start of the text run; use the current 158 task's L{POR} if none supplied 159 @type start: L{POR} 160 @param end: Point of regard to the end of the text run; use the current 161 task's L{POR} if none supplied 162 @type end: L{POR} 163 @return: Text between start and end offsets 164 @rtype: string 165 @raise PORError: When the L{POR} is invalid 166 ''' 167 start = start or self.task_por 168 end = end or self.task_por 169 try: 170 return IAccessibleInfo(start).getAccText(end) 171 except LookupError: 172 raise PORError 173 except NotImplementedError: 174 return None

175

176 - def getWindowTitle(self, por=None):

177 ''' 178 Gets the accessible name of the window containing the L{POR}. 179 When L{por} is None, the L{task_por} is used. 180 181 @param por: A point of regard; uses the current task's POR if none supplied 182 @type por: L{POR} 183 @return: Name of the window 184 @rtype: string 185 @raise PORError: When the L{POR} is invalid 186 ''' 187 por = por or self.task_por 188 frame_por = self.getRootAcc(por) 189 try: 190 return IAccessibleInfo(frame_por).getAccName() 191 except LookupError: 192 raise PORError 193 except NotImplementedError: 194 return None

195

196 - def getAppName(self, por=None):

197 ''' 198 Gets the accessible name of the application containing the L{POR}. 199 When L{por} is None, the L{task_por} is used. 200 201 @param por: A point of regard; uses the current task's POR if none supplied 202 @type por: L{POR} 203 @return: Name of the application 204 @rtype: string 205 @raise PORError: When the L{POR} is invalid 206 ''' 207 por = por or self.task_por 208 try: 209 return IAccessibleInfo(por).getAccAppName() 210 except LookupError: 211 raise PORError 212 except NotImplementedError: 213 return None

214

215 - def getAccAppLocale(self, por=None):

216 ''' 217 Gets the POSIX locale of the application containing the L{POR} as a string. 218 When L{por} is None, the L{task_por} is used. 219 220 @param por: A point of regard; uses the current task's POR if none supplied 221 @type por: L{POR} 222 @return: POSIX locale of the application 223 @rtype: string 224 @raise PORError: When the L{POR} is invalid 225 ''' 226 por = por or self.task_por 227 try: 228 return IAccessibleInfo(por).getAccAppLocale() 229 except LookupError: 230 raise PORError 231 except NotImplementedError: 232 return None

233

234 - def getAccAttrs(self, por=None):

235 ''' 236 Gets a dictionary of name:value attribute pairs at the provided L{POR}. 237 When L{por} is None, the L{task_por} is used. 238 239 @param por: A point of regard; uses the current task's POR if none supplied 240 @type por: L{POR} 241 @return: Name/value pairs for all available attributes 242 @rtype: dictionary of string 243 @raise PORError: When the L{POR} is invalid 244 ''' 245 por = por or self.task_por 246 try: 247 # get the info interface 248 ai = IAccessibleInfo(por) 249 return ai.getAccAttrs() 250 except LookupError: 251 # raise POR error if some accessible was dead, bad or missing 252 raise PORError 253 except NotImplementedError: 254 return None

255

256 - def getAccName(self, por=None):

257 ''' 258 Gets the accessible name of the component at the provided L{POR}. 259 When L{por} is None, the L{task_por} is used. 260 261 @param por: A point of regard; uses the current task's POR if none supplied 262 @type por: L{POR} 263 @return: The accessible name of the control of the at the point of regard 264 @rtype: string 265 @raise PORError: When the L{POR} is invalid 266 ''' 267 por = por or self.task_por 268 try: 269 return IAccessibleInfo(por).getAccName() 270 except LookupError: 271 raise PORError 272 except NotImplementedError: 273 return None

274

275 - def getAccDesc(self, por=None):

276 ''' 277 Gets the accessible description of the component at the provided L{POR}. 278 When L{por} is None, the L{task_por} is used. 279 280 @param por: A point of regard; uses the current task's POR if none supplied 281 @type por: L{POR} 282 @return: The accessible description of the control of the at the point of 283 regard 284 @rtype: string 285 @raise PORError: When the L{POR} is invalidd 286 ''' 287 por = por or self.task_por 288 try: 289 return IAccessibleInfo(por).getAccDescription() 290 except LookupError: 291 raise PORError 292 except NotImplementedError: 293 return None

294

295 - def getAccCount(self, por=None):

296 ''' 297 Gets the number of child accessibles of the accessible indicated by 298 the given L{POR}. When L{por} is None, the L{task_por} is used. 299 300 @param por: A point of regard; uses the current task's POR if none supplied 301 @type por: L{POR} 302 @return: Number of accessible children 303 @rtype: integer 304 @raise PORError: When the L{POR} is invalid 305 ''' 306 por = por or self.task_por 307 try: 308 ai = IAccessibleInfo(por) 309 return ai.getAccChildCount() 310 except LookupError: 311 raise PORError 312 except NotImplementedError: 313 return None

314

315 - def getAccRoleName(self, por=None):

316 ''' 317 Gets the localized role name for the accessible at the provided L{POR}. 318 When L{por} is None, the L{task_por} is used. 319 320 The return value of this method is suitable for output. It is not suitable 321 for comparison to known role values. 322 323 @param por: A point of regard; uses the current task's POR if none supplied 324 @type por: L{POR} 325 @return: The role name of the control of the at the point of regard 326 @rtype: string 327 @raise PORError: When the L{POR} is invalid 328 ''' 329 por = por or self.task_por 330 try: 331 return IAccessibleInfo(por).getAccRoleName() 332 except LookupError: 333 raise PORError 334 except NotImplementedError: 335 return None

336

337 - def getAccRole(self, por=None):

338 ''' 339 Gets the unlocalized role for the accessible at the provided L{POR}. 340 When L{por} is None, the L{task_por} is used. 341 342 The return value of this method is not suitable for output. It is suitable 343 for comparison to known role values. 344 345 @param por: A point of regard; uses the current task's POR if none supplied 346 @type por: L{POR} 347 @return: The role name of the control of the at the point of regard 348 @rtype: string 349 @raise PORError: When the L{POR} is invalid 350 ''' 351 por = por or self.task_por 352 try: 353 return IAccessibleInfo(por).getAccRole() 354 except LookupError: 355 raise PORError 356 except NotImplementedError: 357 return None

358

359 - def getAccActionNames(self, por=None):

360 ''' 361 Gets the names of the actions that can be performed at the provided L{POR}. 362 When L{por} is None, the L{task_por} is used. 363 364 @note: The names appear to be unlocalized. 365 366 @param por: A point of regard; uses the current task's POR if none supplied 367 @type por: L{POR} 368 @return: Names of the actions at the point of regard 369 @rtype: list of string 370 @raise PORError: When the L{POR} is invalid 371 ''' 372 por = por or self.task_por 373 try: 374 return IAccessibleInfo(por).getAccActionNames() 375 except LookupError: 376 raise PORError 377 except NotImplementedError: 378 return None

379

380 - def getAccActionDescs(self, por=None):

381 ''' 382 Gets the descriptions of the actions that can be performed at the 383 provided L{POR}. When L{por} is None, the L{task_por} is used. 384 385 @note: Unsure if the descriptions are localized or not. 386 387 @param por: A point of regard; uses the current task's POR if none supplied 388 @type por: L{POR} 389 @return: Descriptions of the actions at the point of regard 390 @rtype: list of string 391 @raise PORError: When the L{POR} is invalid 392 ''' 393 por = por or self.task_por 394 try: 395 return IAccessibleInfo(por).getAccActionDescs() 396 except LookupError: 397 raise PORError 398 except NotImplementedError: 399 return None

400

401 - def getAccActionKeys(self, por=None):

402 ''' 403 Gets the key bindings associated with the actions at the given L{POR}. 404 When L{por} is None, the L{task_por} is used. 405 406 @param por: A point of regard; uses the current task's POR if none supplied 407 @type por: L{POR} 408 @return: Names of key sequences that all trigger the same action 409 @rtype: list of tuple of string 410 @raise PORError: When the L{POR} is invalid 411 ''' 412 por = por or self.task_por 413 try: 414 return IAccessibleInfo(por).getAccActionKeys() 415 except LookupError: 416 raise PORError 417 except NotImplementedError: 418 return None

419

420 - def getAccClickKey(self, por=None):

421 ''' 422 Gets the key binding associated with the common "click" action which 423 appears to be the action most commonly accessed by a hotkey. Only returns 424 the last of all defined hotkey sequences as it is usually the globally 425 available hotkey rather than the local menu mnemonic or a sequence for 426 activating the menu followed by the mnemonic. When L{por} is None, 427 the L{task_por} is used. 428 429 @param por: A point of regard; uses the current task's POR if none supplied 430 @type por: L{POR} 431 @return: Hotkey sequence 432 @rtype: string 433 @raise PORError: When the L{POR} is invalid 434 ''' 435 por = por or self.task_por 436 names = self.getAccActionNames(por) 437 try: 438 i = names.index('click') 439 except (ValueError, NotImplementedError, AttributeError): 440 return None 441 keys = self.getAccActionKeys(por) 442 try: 443 # return None if the key is blank 444 return keys[i][-1] or None 445 except IndexError: 446 return None

447

448 - def getAccLevel(self, por=None):

449 ''' 450 Gets the tree level of the item indicated by the given L{POR}. When L{por} 451 is None, the L{task_por} is used. 452 453 @param por: A point of regard; uses the current task's POR if none supplied 454 @type por: L{POR} 455 @return: Zero indexed level of the item 456 @rtype: integer 457 @raise PORError: When the L{POR} is invalid 458 ''' 459 por = por or self.task_por 460 try: 461 ai = IAccessibleInfo(por) 462 return ai.getAccLevel() 463 except LookupError: 464 raise PORError 465 except NotImplementedError: 466 return None

467

468 - def getAccTableExtents(self, por=None):

469 ''' 470 Returns the number of rows and columns in a table indicated by the given 471 L{POR}. When L{por} is None, the L{task_por} is used. 472 473 @param por: A point of regard; uses the current task's POR if none supplied 474 @type por: L{POR} 475 @return: Count of rows and columns 476 @rtype: 2-tuple of integer 477 @raise PORError: When the L{POR} is invalid 478 ''' 479 por = por or self.task_por 480 try: 481 ai = IAccessibleInfo(por) 482 return ai.getAccTableExtents() 483 except LookupError: 484 raise PORError 485 except NotImplementedError: 486 return None

487

488 - def getAccVisualExtents(self, por=None):

489 ''' 490 Returns the extents of a visual component at the L{POR}. When L{por} is 491 None, the L{task_por} is used. 492 493 @param por: A point of regard; uses the current task's POR if none supplied 494 @type por: L{POR} 495 @return: Width and height of the point of regard 496 @rtype: 2-tuple of integer 497 @raise PORError: When the L{POR} is invalid 498 ''' 499 por = por or self.task_por 500 try: 501 ai = IAccessibleInfo(por) 502 return ai.getAccVisualExtents() 503 except LookupError: 504 raise PORError 505 except NotImplementedError: 506 return None

507

508 - def getAccVisualPoint(self, por=None):

509 ''' 510 Returns the focal point of a visual component at the L{POR}. When L{por} is 511 None, the L{task_por} is used. 512 513 @param por: A point of regard; uses the current task's POR if none supplied 514 @type por: L{POR} 515 @return: x,y coordinates of the focal point of the point of regard 516 @rtype: 2-tuple of integer 517 @raise PORError: When the L{POR} is invalid 518 ''' 519 por = por or self.task_por 520 try: 521 ai = IAccessibleInfo(por) 522 return ai.getAccVisualPoint() 523 except LookupError: 524 raise PORError 525 except NotImplementedError: 526 return None

527

528 - def getAccPosition(self, por=None):

529 ''' 530 Gets the position of the accessible object, usually upper-left corner 531 532 @param por: A point of regard; uses the current task's POR if none supplied 533 @type por: L{POR} 534 @return: x,y coordinates of the accessible's position 535 @rtype: 2-tuple of integer 536 @raise PORError: When the L{POR} is invalid 537 ''' 538 por = por or self.task_por 539 try: 540 ai = IAccessibleInfo(por) 541 return ai.getAccPosition() 542 except LookupError: 543 raise PORError 544 except NotImplementedError: 545 return None

546

547 - def getAccRow(self, por=None):

548 ''' 549 Gets the row index of the L{POR} within some 2D ordered collection. When 550 L{por} is None, the L{task_por} is used. 551 552 @param por: A point of regard; uses the current task's POR if none supplied 553 @type por: L{POR} 554 @return: Zero indexed row of the item 555 @rtype: integer 556 @raise PORError: When the L{POR} is invalid 557 ''' 558 por = por or self.task_por 559 try: 560 ai = IAccessibleInfo(por) 561 return ai.getAccRow() 562 except LookupError: 563 raise PORError 564 except NotImplementedError: 565 return None

566

567 - def getAccColumn(self, por=None):

568 ''' 569 Gets the column index of the L{POR} within some 2D ordered collection. When 570 L{por} is None, the L{task_por} is used. 571 572 @param por: A point of regard; use the current task's POR if none supplied 573 @type por: L{POR} 574 @return: Zero indexed column of the item 575 @rtype: integer 576 @raise PORError: When the L{POR} is invalid 577 ''' 578 por = por or self.task_por 579 try: 580 ai = IAccessibleInfo(por) 581 return ai.getAccColumn() 582 except LookupError: 583 raise PORError 584 except NotImplementedError: 585 return None

586

587 - def getAccAtRowColumn(self, row, col, por=None):

588 ''' 589 Gets the L{POR} to the cell in the given L{POR} at the given row and 590 column. When L{por} is None, the L{task_por} is used. 591 592 @param por: A point of regard; uses the current task's POR if none supplied 593 @type por: L{POR} 594 @param row: Row offset 595 @type row: integer 596 @param col: Column offset 597 @type col: integer 598 @return: Point of regard to the given row and column 599 @rtype: L{POR} 600 @raise PORError: When the L{POR} is invalid 601 ''' 602 por = por or self.task_por 603 try: 604 ai = IAccessibleInfo(por) 605 index = ai.getAccRowColIndex(row, col) 606 return POR(por.accessible, index) 607 except LookupError: 608 raise PORError 609 except NotImplementedError: 610 return None

611

612 - def getAccRowHeader(self, por=None):

613 ''' 614 Gets the text description of a row in a table. When L{por} is None, the 615 L{task_por} is used. 616 617 @param por: A point of regard; use the current task's POR if none supplied 618 @type por: L{POR} 619 @return: text description of the row, if there is one. 620 @rtype: string 621 @raise PORError: When the L{POR} is invalid 622 ''' 623 por = por or self.task_por 624 try: 625 ai = IAccessibleInfo(por) 626 return ai.getAccRowHeader() 627 except LookupError: 628 raise PORError 629 except NotImplementedError: 630 return None

631

632 - def getAccColumnHeader(self, por=None):

633 ''' 634 Gets the text description of a column in a table. When L{por} is None, the 635 L{task_por} is used. 636 637 @param por: A point of regard; use the current task's POR if none supplied 638 @type por: L{POR} 639 @return: text description of the column, if there is one. 640 @rtype: string 641 @raise PORError: When the L{POR} is invalid 642 ''' 643 por = por or self.task_por 644 try: 645 ai = IAccessibleInfo(por) 646 return ai.getAccColumnHeader() 647 except LookupError: 648 raise PORError 649 except NotImplementedError: 650 return None

651

652 - def getAccIndex(self, por=None):

653 ''' 654 Gets the index the L{POR} within some 1D ordered collection. When L{por} is 655 None, the L{task_por} is used. 656 657 @param por: A point of regard; use the current task's POR if none supplied 658 @type por: L{POR} 659 @return: Zero index of the item 660 @rtype: integer 661 @raise PORError: When the L{POR} is invalid 662 ''' 663 por = por or self.task_por 664 try: 665 ai = IAccessibleInfo(por) 666 return ai.getAccIndex() 667 except LookupError: 668 raise PORError 669 except NotImplementedError: 670 return None

671

672 - def getAccLabel(self, por=None):

673 ''' 674 Gets the label for the accessible at the provided L{POR}. When L{por} is 675 None, the L{task_por} is used. 676 677 @param por: A point of regard; uses the current task's POR if none supplied 678 @type por: L{POR} 679 @return: The AccessibleName of the component that labels the component at 680 the given location. 681 @rtype: string 682 @raise PORError: When the L{POR} is invalid 683 ''' 684 por = por or self.task_por 685 try: 686 # get the accessible info interface 687 ai = IAccessibleInfo(por) 688 # get all labelled by relations 689 pors = ai.getAccRelations('labelled by') 690 except LookupError: 691 raise PORError 692 except NotImplementedError: 693 return None 694 # get names of all label accessibles 695 label = [] 696 for por in pors: 697 try: 698 label.append(self.getItemText(por)) 699 except PORError: 700 # ignore POR errors 701 pass 702 # join names into a string 703 if not label: 704 return None 705 return ' '.join(label)

706

707 - def getAccRelations(self, relation, por=None):

708 ''' 709 Gets the L{POR}s to accessibles related to the given L{POR} in the manner 710 stated by the given relation. When L{por} is None, the L{task_por} is used. 711 712 @param por: A point of regard; uses the current task's POR if none supplied 713 @type por: L{POR} 714 @param relation: Type of relation 715 @type relation: string 716 @return: Point of regard to related accessibles 717 @rtype: list of L{POR}s 718 @raise PORError: When the L{POR} is invalid 719 ''' 720 por = por or self.task_por 721 try: 722 # get the accessible info interface 723 ai = IAccessibleInfo(por) 724 # get all labelled by relations 725 return ai.getAccRelations(relation) 726 except LookupError: 727 raise PORError 728 except NotImplementedError: 729 return None

730

731 - def hasAccState(self, state, por=None):

732 ''' 733 Gets if the accessible at the given L{POR} has the given state. When L{por} 734 is None, the L{task_por} is used. The state is assumed to be a string that 735 can be mapped to an appropriate state constant on the platform or indicates 736 an extension state that is represented by a string. 737 738 @param state: Name of a state (e.g. 'focused', 'selected', 'selectable') 739 @type state: string 740 @param por: A point of regard; uses the current task's POR if none supplied 741 @type por: L{POR} 742 @return: Does the L{POR} have the given state? 743 @rtype: boolean 744 @raise PORError: When the L{POR} is invalid 745 ''' 746 por = por or self.task_por 747 try: 748 ai = IAccessibleInfo(por) 749 return ai.hasAccState(state) 750 except LookupError: 751 raise PORError 752 except NotImplementedError: 753 return False

754

755 - def hasOneAccState(self, por=None, *states):

756 ''' 757 Gets if the accessible at the given L{POR} has one of the given states. 758 When L{por} is None, the L{task_por} is used. The state is assumed to be a 759 string that can be mapped to an appropriate state constant on the platform 760 or indicates an extension state that is represented by a string. 761 762 This method is more efficient than calling L{hasAccState} multiple times. 763 764 @param states: Names of states (e.g. 'focused', 'selected', 'selectable') 765 @type states: string 766 @param por: A point of regard; uses the current task's POR if none supplied 767 @type por: L{POR} 768 @return: Does the L{POR} have the given state? 769 @rtype: boolean 770 @raise PORError: When the L{POR} is invalid 771 ''' 772 por = por or self.task_por 773 try: 774 ai = IAccessibleInfo(por) 775 return ai.hasAccOneState(*states) 776 except LookupError: 777 raise PORError 778 except NotImplementedError: 779 return False

780

781 - def hasAccRole(self, role, por=None):

782 ''' 783 Gets if the accessible at the given L{POR} has the given role. When 784 L{por} is None, the L{task_por} is used. The role is assumed to be a string 785 that can be mapped to an appropriate role constant on the platform or 786 indicates an extension role that is represented by a string. 787 788 @param role: Name of a role (e.g. 'terminal', 'glass pane', 'button') 789 @type role: string 790 @param por: A point of regard; use the current task's POR if none supplied 791 @type por: L{POR} 792 @return: Does the L{POR} have the given role? 793 @rtype: boolean 794 @raise PORError: When the L{POR} is invalid 795 ''' 796 por = por or self.task_por 797 try: 798 ai = IAccessibleInfo(por) 799 return ai.hasAccRole(role) 800 except LookupError: 801 raise PORError 802 except NotImplementedError: 803 return False

804

805 - def hasOneAccRole(self, por=None, *roles):

806 ''' 807 Gets if the accessible at the given L{POR} has any one of the given roles. 808 When L{por} is None, the L{task_por} is used. The role is assumed to be a 809 string that can be mapped to an appropriate role constant on the platform 810 or indicates an extension role that is represented by a string. 811 812 This method is more efficient than calling L{hasAccRole} multiple times. 813 814 @param roles: Name of a role (e.g. 'terminal', 'glass pane', 'button') 815 @type roles: string 816 @param por: A point of regard; use the current task's POR if none supplied 817 @type por: L{POR} 818 @return: Does the L{POR} have the given role? 819 @rtype: boolean 820 @raise PORError: When the L{POR} is invalid 821 ''' 822 por = por or self.task_por 823 try: 824 ai = IAccessibleInfo(por) 825 return ai.hasAccOneRole(*roles) 826 except LookupError: 827 raise PORError 828 except NotImplementedError: 829 return False

830

831 - def getStateText(self, por=None, name=None, value=None):

832 ''' 833 Gets text describing the states of the given L{POR} that might be of 834 interest to the user. When L{por} is None, the L{task_por} is used. If 835 name is specified, only gets the text describing the state with that 836 non-translated name. If name is not specified, gets text describing all 837 states of interest. 838 839 @param por: A point of regard; use the current task's POR if none supplied 840 @type por: L{POR} 841 @param name: Name of the state to describe 842 @type name: string 843 @param value: Value of the state to describe 844 @type value: string 845 @return: String describing the state(s), None if named state not found 846 @rtype: string 847 @raise PORError: When the L{POR} is invalid 848 ''' 849 # look up just the give name and value 850 if name is not None and value is not None: 851 return self._state_descriptions.get((name, value)) 852 853 por = por or self.task_por 854 try: 855 # get all states 856 states = IAccessibleInfo(por).getAccStates() 857 except LookupError: 858 raise PORError 859 except NotImplementedError: 860 return None 861 862 text = [] 863 for name in states: 864 try: 865 # localize all state strings 866 desc = self._state_descriptions[(name, True)] 867 except KeyError: 868 continue 869 text.append(desc) 870 if not text: 871 return None 872 return ' '.join(text)

873

874 - def getItemText(self, por=None):

875 ''' 876 Gets the text of the complete item that includes the specified L{POR}. When 877 L{por} is None, the L{task_por} is used. 878 879 @param por: A point of regard; uses the current task's POR if none supplied 880 @type por: L{POR} 881 @return: Item text at the given point of regard 882 @rtype: string 883 @raise PORError: When the L{POR} is invalid 884 ''' 885 por = por or self.task_por 886 try: 887 text = IAccessibleInfo(por).getAccItemText() 888 return text 889 except LookupError: 890 raise PORError 891 except NotImplementedError: 892 return None

893

894 - def getCharText(self, por=None):

895 ''' 896 Gets the text of the current character at the specified L{POR}. When L{por} 897 is None, the L{task_por} is used. 898 899 @param por: A point of regard; uses the current task's POR if none supplied 900 @type por: L{POR} 901 @return: Character at the given point of regard 902 @rtype: string 903 @raise PORError: When the L{POR} is invalid 904 ''' 905 por = por or self.task_por 906 try: 907 text = IAccessibleInfo(por).getAccItemText() 908 if len(text) <= por.char_offset: 909 return u'' 910 else: 911 return text[por.char_offset] 912 except LookupError: 913 raise PORError 914 except NotImplementedError: 915 return None

916

917 - def getWordText(self, por=None):

918 ''' 919 Gets the text of the current word at the specified L{POR}. When L{por} is 920 None, the L{task_por} is used. 921 922 @param por: A point of regard; uses the current task's POR if none supplied 923 @type por: L{POR} 924 @return: Word text at the given point of regard 925 @rtype: string 926 @raise PORError: When the L{POR} is invalid 927 ''' 928 por = por or self.task_por 929 try: 930 text = IAccessibleInfo(por).getAccItemText() 931 except LookupError: 932 raise PORError 933 except NotImplementedError: 934 return None 935 prev, curr, next = Word.getContextFromString(text, por) 936 return str(curr)

937

938 - def getAllSelected(self, por=None):

939 ''' 940 Gets all of the selected items or accessible children in the accessible 941 indicated by the given L{POR}. When L{por} is None, the L{task_por} is used. 942 943 @param por: A point of regard; uses the current task's POR if none supplied 944 @type por: L{POR} 945 @return: Points of regard to selected items or accessibles 946 @rtype: list of L{POR} 947 @raise PORError: When the L{POR} is invalid 948 ''' 949 por = por or self.task_por 950 try: 951 return IAccessibleInfo(por).getAccSelection() 952 except LookupError: 953 raise PORError 954 except NotImplementedError: 955 return None

956

957 - def setAllSelected(self, por=None):

958 ''' 959 Selects all of the items or accessible children in the accessible indicated 960 by the given L{POR}. When L{por} is None, the L{task_por} is used. 961 962 @param por: A point of regard; uses the current task's POR if none supplied 963 @type por: L{POR} 964 @return: Is setting the focus supported? 965 @rtype: boolean 966 @raise PORError: When the L{POR} is invalid 967 @raise SelectError: When selecting is supported but rejected by the system 968 for some reason 969 ''' 970 por = por or self.task_por 971 try: 972 rv = IAccessibleAction(por).selectAcc(all=True) 973 except LookupError: 974 raise PORError 975 except NotImplementedError: 976 # selection not supported 977 return False 978 else: 979 if not rv: 980 # raise an error if supported but failed 981 raise SelectError 982 return True

983

984 - def setAllDeselected(self, por=None):

985 ''' 986 Deselects all of the items or accessible children in the accessible 987 indicated by the given L{POR}. When L{por} is None, the L{task_por} is 988 used. 989 990 @param por: A point of regard; uses the current task's POR if none supplied 991 @type por: L{POR} 992 @return: Is setting the focus supported? 993 @rtype: boolean 994 @raise PORError: When the L{POR} is invalid 995 @raise SelectError: When deselecting is supported but rejected by the 996 system for some reason 997 ''' 998 por = por or self.task_por 999 try: 1000 rv = IAccessibleAction(por).deselectAcc(True) 1001 except LookupError: 1002 raise PORError 1003 except NotImplementedError: 1004 # selection not supported 1005 return False 1006 else: 1007 if not rv: 1008 # raise an error if supported but failed 1009 raise SelectError 1010 return True

1011

1012 - def getFirstSelected(self, por=None):

1013 ''' 1014 Gets the first selected items or accessible children in the accessible 1015 indicated by the given L{POR}. When L{por} is None, the L{task_por} is 1016 used. 1017 1018 @param por: A point of regard; uses the current task's POR if none supplied 1019 @type por: L{POR} 1020 @return: Point of regard to the first selected item or accessible 1021 @rtype: L{POR} 1022 @raise PORError: When the L{POR} is invalid 1023 ''' 1024 all = self.getAllSelected(por) 1025 try: 1026 return all[0] 1027 except TypeError: 1028 return None

1029

1030 - def doAction(self, index, por=None):

1031 ''' 1032 Executes the action at the given index in the list of all actions named 1033 in the return value from L{getAccActionNames}. When L{por} is None, the 1034 L{task_por} is used. 1035 1036 @param index: Index of the action to execute. 1037 @type index: integer 1038 @param por: A point of regard; uses the current task's POR if none supplied 1039 @type por: L{POR} 1040 @raise PORError: When the L{POR} is invalid 1041 @raise ActionError: When executing the action fails for some reason 1042 ''' 1043 por = por or self.task_por 1044 try: 1045 # try to set the focus 1046 ia = IAccessibleAction(por) 1047 rv = ia.doAccAction(index) 1048 except LookupError: 1049 # the provided por was invalid 1050 raise PORError 1051 except NotImplementedError: 1052 # just return if actions aren't supported 1053 return 1054 else: 1055 if not rv: 1056 # raise an error if the action is supported by was not executed 1057 raise ActionError

1058

1059 - def getAccFocus(self, search=False):

1060 ''' 1061 Gets the L{POR} representing the focus of the foreground application. If 1062 no focus event has been received yet by this L{Tier} and search is True, 1063 performs a search for an accessible with state focus. 1064 1065 @note: Setting search to True can result in a very long search operation. 1066 Be careful. 1067 @return: Point of regard to the focused accessible 1068 @rtype: L{POR} 1069 ''' 1070 por = self.tier.getFocus() 1071 if por is None and search: 1072 # find the focus by looking at states 1073 pred = lambda por: IAccessibleInfo(por).hasAccState('focused') 1074 return self.findAccByPredicate(pred, self.getViewRootAcc(), False) 1075 return por

1076

1077 - def setAccFocus(self, por=None):

1078 ''' 1079 Sets the system input focus to the accessible in the provided L{POR}. When 1080 L{por} is None, the L{task_por} is used. 1081 1082 @param por: A point of regard; uses the current task's POR if none supplied 1083 @type por: L{POR} 1084 @return: Is setting the focus supported? 1085 @rtype: boolean 1086 @raise PORError: When the L{POR} is invalid 1087 @raise FocusError: When focusing on the L{POR} is supported but rejected by 1088 the system for some reason 1089 ''' 1090 por = por or self.task_por 1091 try: 1092 # try to set the focus 1093 ia = IAccessibleAction(por) 1094 rv = ia.setAccFocus() 1095 except LookupError: 1096 # the provided por was invalid 1097 raise PORError 1098 except NotImplementedError: 1099 # return False if not supported 1100 return False 1101 else: 1102 if not rv: 1103 # raise an error if supported but failed 1104 raise FocusError 1105 return True

1106

1107 - def setAccSelected(self, por=None):

1108 ''' 1109 Selects the item or accessible indicated by the given L{POR}. When L{por} 1110 is None, the L{task_por} is used. 1111 1112 @param por: A point of regard; uses the current task's POR if none supplied 1113 @type por: L{POR} 1114 @return: Is setting the selection supported? 1115 @rtype: boolean 1116 @raise PORError: When the L{POR} is invalid 1117 @raise SelectError: When selecting the L{POR} is supported but rejected by 1118 the system for some reason 1119 ''' 1120 por = por or self.task_por 1121 try: 1122 rv = IAccessibleAction(por).selectAcc(False) 1123 except LookupError: 1124 raise PORError 1125 except NotImplementedError: 1126 # return False if not supported 1127 return False 1128 else: 1129 if not rv: 1130 # raise an error if supported but failed 1131 raise SelectError 1132 return True

1133

1134 - def setAccDeselected(self, por=None):

1135 ''' 1136 Deselects the item or accessible indicated by the given L{POR}. When L{por} 1137 is None, the L{task_por} is used. 1138 1139 @param por: A point of regard; uses the current task's POR if none supplied 1140 @type por: L{POR} 1141 @return: Is setting the selection supported? 1142 @rtype: boolean 1143 @raise PORError: When the L{POR} is invalid 1144 @raise SelectError: When deselecting the L{POR} is supported but rejected 1145 by the system for some reason 1146 ''' 1147 por = por or self.task_por 1148 try: 1149 rv = IAccessibleAction(por).deselectAcc(False) 1150 except LookupError: 1151 raise PORError 1152 except NotImplementedError: 1153 # return False if not supported 1154 return False 1155 else: 1156 if not rv: 1157 # raise an error if supported but failed 1158 raise SelectError 1159 return True

1160

1161 - def getAccCaret(self, por=None):

1162 ''' 1163 Gets the text input caret L{POR} within the given accessible L{POR}. 1164 When L{por} is None, the L{task_por} is used. 1165 1166 @param por: A point of regard; uses the current task's POR if none supplied 1167 @type por: L{POR} 1168 @return: Point of regard to the text insertion caret 1169 @rtype: L{POR} 1170 @raise PORError: When the L{POR} is invalid 1171 ''' 1172 por = por or self.task_por 1173 try: 1174 return IAccessibleInfo(por).getAccCaret() 1175 except LookupError: 1176 raise PORError 1177 except NotImplementedError: 1178 # return None if not supported 1179 return None

1180

1181 - def setAccCaret(self, por=None):

1182 ''' 1183 Moves the text input caret to offset indicated by the given L{POR}. 1184 When L{por} is None, the L{task_por} is used. 1185 1186 @param por: A point of regard; uses the current task's POR if none supplied 1187 @type por: L{POR} 1188 @return: Is setting the caret supported? 1189 @rtype: boolean 1190 @raise PORError: When the L{POR} is invalid 1191 @raise CaretError: When moving the caret is supported but rejected by the 1192 system for some reason 1193 ''' 1194 por = por or self.task_por 1195 try: 1196 rv = IAccessibleAction(por).setAccCaret() 1197 except LookupError: 1198 raise PORError 1199 except NotImplementedError: 1200 # return False if not supported 1201 return False 1202 else: 1203 if not rv: 1204 # raise an error if supported but failed 1205 raise CaretError 1206 return True

1207

1208 - def setAccPOR(self, por=None):

1209 ''' 1210 Sets the system input focus, selection, and caret offset to the provided 1211 L{POR}. Ignores errors trying each as focus, selection, and caret offset 1212 are not all supported by every control. When L{por} is None, the 1213 L{task_por} is used. 1214 1215 @param por: A point of regard; uses the current task's POR if none supplied 1216 @type por: L{POR} 1217 @return: False if none of focus, selection, or caret can be set; True if 1218 at least one was set 1219 @rtype: boolean 1220 @raise PORError: When the L{POR} is invalid 1221 ''' 1222 por = por or self.task_por 1223 count = 0 1224 try: 1225 self.setAccFocus(por) 1226 except (NotImplementedError, ActionError): 1227 count += 1 1228 try: 1229 self.setAccSelected(por) 1230 except (NotImplementedError, ActionError): 1231 count += 1 1232 try: 1233 self.setAccCaret(por) 1234 except (NotImplementedError, ActionError): 1235 count += 1 1236 return count != 3

1237

1238 - def getFirstPeerAcc(self, por=None):

1239 ''' 1240 Gets the L{POR} of the first accessible peer of a given L{POR}. When L{por} 1241 is None, the L{task_por} is used. 1242 1243 @param por: A point of regard; uses the current task's POR if none supplied 1244 @type por: L{POR} 1245 @return: Point of regard to the first peer accessible 1246 @rtype: L{POR} 1247 ''' 1248 por = por or self.task_por 1249 try: 1250 p = IAccessibleNav(por).getParentAcc() 1251 return IAccessibleNav(p).getFirstAccChild() 1252 except (NotImplementedError, IndexError, LookupError): 1253 return None

1254

1255 - def getLastPeerAcc(self, por=None):

1256 ''' 1257 Gets the L{POR} of the last accessible peer of a given L{POR}. When L{por} 1258 is None, the L{task_por} is used. 1259 1260 @param por: A point of regard; uses the current task's POR if none supplied 1261 @type por: L{POR} 1262 @return: Point of regard to the first peer accessible 1263 @rtype: L{POR} 1264 ''' 1265 por = por or self.task_por 1266 try: 1267 p = IAccessibleNav(por).getParentAcc() 1268 return IAccessibleNav(p).getLastAccChild() 1269 except (NotImplementedError, IndexError, LookupError): 1270 return None

1271

1272 - def getNextPeerAcc(self, por=None):

1273 ''' 1274 Gets the L{POR} of the next accessible peer of a given L{POR}. When L{por} 1275 is None, the L{task_por} is used. 1276 1277 @param por: A point of regard; uses the current task's POR if none supplied 1278 @type por: L{POR} 1279 @return: Point of regard to the next peer accessible 1280 @rtype: L{POR} 1281 ''' 1282 por = por or self.task_por 1283 try: 1284 return IAccessibleNav(por).getNextAcc() 1285 except (IndexError, NotImplementedError, LookupError): 1286 return None

1287

1288 - def getPrevPeerAcc(self, por=None):

1289 ''' 1290 Gets the L{POR} of the previous accessible peer of a given L{POR}. When 1291 L{por} is None, the L{task_por} is used. 1292 1293 @param por: A point of regard; uses the current task's POR if none supplied 1294 @type por: L{POR} 1295 @return: Point of regard to the next peer accessible 1296 @rtype: L{POR} 1297 ''' 1298 por = por or self.task_por 1299 try: 1300 return IAccessibleNav(por).getPrevAcc() 1301 except (IndexError, NotImplementedError, LookupError): 1302 return None

1303

1304 - def getNextAcc(self, por=None):

1305 ''' 1306 Gets the L{POR} of the next accessible of a given L{POR} in the 1307 L{AccessibleWalker} order. When L{por} is None, the L{task_por} is used. 1308 1309 @param por: A point of regard; uses the current task's POR if none supplied 1310 @type por: L{POR} 1311 @return: Point of regard to the next accessible 1312 @rtype: L{POR} 1313 ''' 1314 por = por or self.task_por 1315 w = AccessibleWalker(por) 1316 try: 1317 return w.getNextPOR() 1318 except NotImplementedError: 1319 return None

1320

1321 - def getPrevAcc(self, por=None):

1322 ''' 1323 Gets the L{POR} of the previous accessible of a given L{POR}. When L{por} 1324 is None, the L{task_por} is used. 1325 1326 @param por: A point of regard; uses the current task's POR if none supplied 1327 @type por: L{POR} 1328 @return: Point of regard to the previous accessible or None if not found 1329 @rtype: L{POR} 1330 ''' 1331 por = por or self.task_por 1332 w = AccessibleWalker(por) 1333 try: 1334 return w.getPrevPOR() 1335 except NotImplementedError: 1336 return None

1337

1338 - def getNextItem(self, por=None, wrap=False, only_visible=False):

1339 ''' 1340 Gets the L{POR} of the next item in the given L{POR}. When L{por} is None, 1341 the L{task_por} is used. 1342 1343 @param por: A point of regard; uses the current task's POR if none supplied 1344 @type por: L{POR} 1345 @param wrap: Consider a next item outside this accessible if there is no 1346 next item in this accessible? Defaults to False. 1347 @type wrap: boolean 1348 @param only_visible: Only consider visible items? Defaults to False. 1349 @type only_visible: boolean 1350 @return: Point of regard to the previous item or None if not found 1351 @rtype: L{POR} 1352 ''' 1353 por = por or self.task_por 1354 w = AccessibleItemWalker(por, only_visible=only_visible) 1355 try: 1356 next_por = w.getNextPOR() 1357 except NotImplementedError: 1358 return None 1359 if wrap: 1360 # return whatever the walker returned 1361 return next_por 1362 elif next_por is not None and not next_por.isSameAcc(por): 1363 # there is no next POR when wrapping is off 1364 return None 1365 return next_por

1366

1367 - def getCurrItem(self, por=None):

1368 ''' 1369 Gets the L{POR} of the start of the item. When L{por} is None, the 1370 L{task_por} is used. 1371 1372 @param por: A point of regard; use the current task's POR if none supplied 1373 @type por: L{POR} 1374 @return: Point of regard to the first character in the item or None if not 1375 found 1376 @rtype: L{POR} 1377 ''' 1378 por = por or self.task_por 1379 return POR(por.accessible, por.item_offset, 0)

1380

1381 - def getPrevItem(self, por=None, wrap=False, only_visible=False):

1382 ''' 1383 Gets the L{POR} of the previous item in the given L{POR}. When L{por} is 1384 None, the L{task_por} is used. 1385 1386 @param por: A point of regard; use the current task's POR if none supplied 1387 @type por: L{POR} 1388 @param wrap: Consider a previous item outside this accessible if there is 1389 no previous item in this accessible? Defaults to False. 1390 @type wrap: boolean 1391 @param only_visible: Only consider visible items? Defaults to False. 1392 @type only_visible: boolean 1393 @return: Point of regard to the previous item or None if not found 1394 @rtype: L{POR} 1395 ''' 1396 por = por or self.task_por 1397 w = AccessibleItemWalker(por, only_visible=only_visible) 1398 try: 1399 prev_por = w.getPrevPOR() 1400 except NotImplementedError: 1401 return None 1402 if wrap: 1403 # return whatever the walker returned 1404 return prev_por 1405 elif not prev_por.isSameAcc(por): 1406 # there is no previous POR when wrapping is off 1407 return None 1408 return prev_por

1409

1410 - def getNextWord(self, por=None):

1411 ''' 1412 Get the L{POR} of the next word in the item indicated by the given L{POR}. 1413 When L{por} is None, the L{task_por} is used. 1414 1415 @param por: A point of regard; use the current task's POR if none supplied 1416 @type por: L{POR} 1417 @return: Point of regard to the next word or None if not found 1418 @rtype: L{POR} 1419 ''' 1420 por = por or self.task_por 1421 # get the current item text 1422 try: 1423 text = IAccessibleInfo(por).getAccItemText() 1424 except (LookupError, NotImplementedError): 1425 return None 1426 # parse the text for the next word 1427 prev, curr, next = Word.getContextFromString(text, por) 1428 if next is not None: 1429 # if we found a next word, return its POR 1430 return next.getPOR() 1431 else: 1432 return None

1433

1434 - def getCurrWord(self, por=None):

1435 ''' 1436 Get the L{POR} of the current word in the item indicated by the given 1437 L{POR}. When L{por} is None, the L{task_por} is used. 1438 1439 @param por: A point of regard; use the current task's POR if none supplied 1440 @type por: L{POR} 1441 @return: Point of regard to the start of the current word or None if not 1442 found 1443 @rtype: L{POR} 1444 ''' 1445 por = por or self.task_por 1446 # get the current item text 1447 try: 1448 text = IAccessibleInfo(por).getAccItemText() 1449 except (LookupError, NotImplementedError): 1450 return None 1451 # parse the text for the current word 1452 prev, curr, next = Word.getContextFromString(text, por) 1453 return curr.getPOR()

1454

1455 - def getPrevWord(self, por=None):

1456 ''' 1457 Get the L{POR} of the previous word in the item indicated by the given 1458 L{POR}. When L{por} is None, the L{task_por} is used. 1459 1460 @param por: A point of regard; uses the current task's POR if none supplied 1461 @type por: L{POR} 1462 @return: Point of regard to the previous word or None if not found 1463 @rtype: L{POR} 1464 ''' 1465 por = por or self.task_por 1466 # get the current item text; cannot use self.getItemText because it traps 1467 # errors that we need to know here in order to return on an invalid POR 1468 try: 1469 text = IAccessibleInfo(por).getAccItemText() 1470 except (LookupError, NotImplementedError): 1471 return None 1472 # parse the text for the previous word 1473 prev, curr, next = Word.getContextFromString(text, por) 1474 if prev is not None: 1475 # if we found a prev word, return its POR 1476 return prev.getPOR() 1477 else: 1478 return None

1479

1480 - def getLastWord(self, por=None):

1481 ''' 1482 Get the L{POR} of the current word in the item indicated by the given 1483 L{POR}. When L{por} is None, the L{task_por} is used. 1484 1485 @param por: A point of regard; use the current task's POR if none supplied 1486 @type por: L{POR} 1487 @return: Point of regard to the start of the last word or None if not found 1488 @rtype: L{POR} 1489 ''' 1490 por = por or self.task_por 1491 # get the current item text 1492 try: 1493 text = IAccessibleInfo(por).getAccItemText() 1494 except (LookupError, NotImplementedError): 1495 return None 1496 # parse the text 1497 words = Word.buildWordsFromString(text, por) 1498 try: 1499 # get the POR of the last word 1500 return words[-1].getPOR() 1501 except IndexError: 1502 # no words, so just return the given POR 1503 return por

1504

1505 - def getNextChar(self, por=None):

1506 ''' 1507 Get the L{POR} of the next character in the item indicated by the given 1508 L{POR}. When L{por} is None, the L{task_por} is used. 1509 1510 @param por: A point of regard; uses the current task's POR if none supplied 1511 @type por: L{POR} 1512 @return: Point of regard to the next character or None if not found 1513 @rtype: L{POR} 1514 ''' 1515 por = por or self.task_por 1516 try: 1517 # get the text of the current item 1518 text = IAccessibleInfo(por).getAccItemText() 1519 except (LookupError, NotImplementedError): 1520 return None 1521 if por.char_offset < len(text)-1: 1522 return POR(por.accessible, por.item_offset, por.char_offset+1) 1523 else: 1524 return None

1525

1526 - def getPrevChar(self, por=None):

1527 ''' 1528 Get the L{POR} of the previous character in the item indicated by the given 1529 L{POR}. When L{por} is None, the L{task_por} is used. 1530 1531 @param por: A point of regard; uses the current task's POR if none supplied 1532 @type por: L{POR} 1533 @return: Point of regard to the previous character or None if not found 1534 @rtype: L{POR} 1535 ''' 1536 por = por or self.task_por 1537 if por.char_offset > 0: 1538 return POR(por.accessible, por.item_offset, por.char_offset-1) 1539 else: 1540 return None

1541

1542 - def getLastChar(self, por=None):

1543 ''' 1544 Get the L{POR} of the last character in the item indicated by the given 1545 L{POR}. When L{por} is None, the L{task_por} is used. 1546 1547 @param por: A point of regard; uses the current task's POR if none supplied 1548 @type por: L{POR} 1549 @return: Point of regard to the last character or None if not found 1550 @rtype: L{POR} 1551 ''' 1552 por = por or self.task_por 1553 try: 1554 # get the text of the current item 1555 text = IAccessibleInfo(por).getAccItemText() 1556 except (LookupError, NotImplementedError): 1557 return None 1558 if len(text) == 0: 1559 return POR(por.accessible, por.item_offset, 0) 1560 else: 1561 return POR(por.accessible, por.item_offset, len(text)-1)

1562

1563 - def getNextRow(self, por=None):

1564 ''' 1565 Get the L{POR} of the first column of the next row relative to the row 1566 containing the item indicated by the given L{POR}. When L{por} is None, the 1567 L{task_por} is used. 1568 1569 @param por: A point of regard; uses the current task's POR if none supplied 1570 @type por: L{POR} 1571 @return: Point of regard to the start of the next row or None if not found 1572 @rtype: L{POR} 1573 ''' 1574 por = por or self.task_por 1575 try: 1576 ai = IAccessibleInfo(por) 1577 # get the current row and add one, first column 1578 index = ai.getAccRowColIndex(ai.getAccRow()+1, 0) 1579 return POR(por.accessible, index) 1580 except (LookupError, NotImplementedError): 1581 return None

1582

1583 - def getCurrRow(self, por=None):

1584 ''' 1585 Gets the L{POR} to the cell in the first column of the row containing the 1586 item indicated by the given L{POR}. When L{por} is None, the L{task_por} is 1587 used. 1588 1589 @param por: A point of regard; uses the current task's POR if none supplied 1590 @type por: L{POR} 1591 @return: Point of regard to the first column of the given row 1592 @rtype: L{POR} 1593 ''' 1594 por = por or self.task_por 1595 try: 1596 ai = IAccessibleInfo(por) 1597 # this row, first column 1598 index = ai.getAccRowColIndex(ai.getAccRow(), 0) 1599 return POR(por.accessible, index) 1600 except (LookupError, NotImplementedError): 1601 return None

1602

1603 - def getPrevRow(self, por=None):

1604 ''' 1605 Get the L{POR} of the first column of the previous row relative to the row 1606 containing the item indicated by the given L{POR}. When L{por} is None, the 1607 L{task_por} is used. 1608 1609 @param por: A point of regard; uses the current task's POR if none supplied 1610 @type por: L{POR} 1611 @return: Point of regard to the start of the previous row or None if not 1612 found 1613 @rtype: L{POR} 1614 ''' 1615 por = por or self.task_por 1616 try: 1617 ai = IAccessibleInfo(por) 1618 # get the current row and add one, first column 1619 index = ai.getAccRowColIndex(ai.getAccRow()+1, 0) 1620 return POR(por.accessible, index) 1621 except (LookupError, NotImplementedError): 1622 return None

1623

1624 - def iterNextAccs(self, por=None):

1625 ''' 1626 Builds an iterator over the accessibles next to the current L{POR}. When 1627 L{por} is None, the L{task_por} is used. 1628 1629 @param por: A point of regard; uses the current task's POR if none supplied 1630 @type por: L{POR} 1631 @return: Point of regard to the previous accessible 1632 @rtype: L{POR} 1633 ''' 1634 por = por or self.getNextAcc(por) 1635 while por is not None: 1636 yield por 1637 por = self.getNextAcc(por)

1638

1639 - def iterPrevAccs(self, por=None):

1640 ''' 1641 Builds an iterator over the accessibles previous to the current L{POR}. 1642 When L{por} is None, the L{task_por} is used. 1643 1644 @param por: A point of regard; uses the current task's POR if none supplied 1645 @type por: L{POR} 1646 @return: Point of regard to the previous accessible 1647 @rtype: L{POR} 1648 ''' 1649 por = por or self.getPrevAcc(por) 1650 while por is not None: 1651 yield por 1652 por = self.getPrevAcc(por)

1653

1654 - def iterNextItems(self, por=None, wrap=False, only_visible=False):

1655 ''' 1656 Builds an iterator over the items next to the current L{POR}. When L{por} 1657 is None, the L{task_por} is used. 1658 1659 @param por: A point of regard; use the current task's POR if none supplied 1660 @type por: L{POR} 1661 @param wrap: Consider a next item outside this accessible if there is 1662 no next item in this accessible? Defaults to False. 1663 @type wrap: boolean 1664 @param only_visible: Only consider visible items? Defaults to False. 1665 @type only_visible: boolean 1666 @return: Point of regard to the next item 1667 @rtype: L{POR} 1668 ''' 1669 por = por or self.getNextItem(por, wrap, only_visible) 1670 while por is not None: 1671 yield por 1672 por = self.getNextItem(por, wrap, only_visible)

1673

1674 - def iterPrevItems(self, por=None, wrap=False, only_visible=False):

1675 ''' 1676 Builds an iterator over the items previous to the current L{POR}. When 1677 L{por} is None, the L{task_por} is used. 1678 1679 @param por: A point of regard; use the current task's POR if none supplied 1680 @type por: L{POR} 1681 @param wrap: Consider a previous item outside this accessible if there is 1682 no previous item in this accessible? Defaults to False. 1683 @type wrap: boolean 1684 @param only_visible: Only consider visible items? Defaults to False. 1685 @type only_visible: boolean 1686 @return: Point of regard to the previous item 1687 @rtype: L{POR} 1688 ''' 1689 por = por or self.getPrevItem(por, wrap, only_visible) 1690 while por is not None: 1691 yield por 1692 por = self.getPrevItem(por, wrap, only_visible)

1693

1694 - def getChildAcc(self, index, por=None):

1695 ''' 1696 Gets the child accessible at the given index from the L{POR}. When no POR 1697 is provided, the L{task_por} is used. 1698 1699 @param index: Child index to retrieve 1700 @type index: integer 1701 @param por: A point of regard; uses the current task's POR if none supplied 1702 @type por: L{POR} 1703 @return: Point of regard to the child at the index or None if it does not 1704 exist 1705 @rtype: L{POR} 1706 ''' 1707 por = por or self.task_por 1708 try: 1709 return IAccessibleNav(por).getChildAcc(index) 1710 except (IndexError, LookupError): 1711 return None

1712

1713 - def getParentAcc(self, por=None):

1714 ''' 1715 Gets the L{POR} of the first character and first item of the parent of the 1716 provided L{POR}. When no POR is provided, the L{task_por} is used. 1717 1718 @param por: A point of regard; uses the current task's POR if none supplied 1719 @type por: L{POR} 1720 @return: Point of regard for the parent 1721 @rtype: L{POR} 1722 ''' 1723 por = por or self.task_por 1724 try: 1725 return IAccessibleNav(por).getParentAcc() 1726 except (NotImplementedError, LookupError): 1727 return None

1728

1729 - def iterAncestorAccs(self, por=None, only_visible=False,allow_trivial=False):

1730 ''' 1731 Builds an iterator over the ancestors of the current L{POR}. When L{por} is 1732 None, the L{task_por} is used. 1733 1734 @param por: A point of regard; use the current task's POR if none supplied 1735 @type por: L{POR} 1736 @param only_visible: Yield on visible L{POR}s only? 1737 @type only_visible: boolean 1738 @param allow_trivial: Yield on trivial L{POR}s too? 1739 @type allow_trivial: boolean 1740 @return: Point of regard to an ancestor 1741 @rtype: L{POR} 1742 ''' 1743 por = por or self.task_por 1744 w = AccessibleItemWalker(por, only_visible, allow_trivial) 1745 try: 1746 por = w.getParentPOR() 1747 except NotImplementedError: 1748 return 1749 while por is not None: 1750 yield por 1751 try: 1752 por = w.getParentPOR() 1753 except NotImplementedError: 1754 return

1755

1756 - def getViewRootAcc(self):

1757 ''' 1758 Gets a L{POR} indicating the root of the active view. This is more 1759 efficient than L{getRootAcc} when the root of the I{active} view is needed. 1760 1761 @return: A point of regard to the root accessible 1762 @rtype: L{POR} 1763 ''' 1764 return self.view_man.getAEView()

1765

1766 - def getRootAcc(self, por=None):

1767 ''' 1768 Gets a L{POR} to the top level container of the given L{POR}. When L{por} 1769 is None, the L{task_por} is used. 1770 1771 @param por: A point of regard; uses the current task's POR if none supplied 1772 @type por: L{POR} 1773 @return: A point of regard to the root accessible 1774 @rtype: L{POR} 1775 @raise PORError: When the provided L{POR} is invalid 1776 ''' 1777 por = por or self.task_por 1778 w = AccessibleWalker(por) 1779 try: 1780 return w.getFirstPOR() 1781 except NotImplementedError: 1782 return None

1783

1784 - def getEndAcc(self, por=None):

1785 ''' 1786 Gets a L{POR} to the last item of the last accessible under the root of the 1787 view. When L{por} is None, the L{task_por} is used. 1788 1789 @param por: A point of regard; uses the current task's POR if none supplied 1790 @type por: L{POR} 1791 @return: A point of regard to the last accessible under the root POR 1792 @rtype: L{POR} 1793 @raise PORError: When the L{POR} is invalid 1794 ''' 1795 por = por or self.task_por 1796 w = AccessibleItemWalker(por) 1797 try: 1798 por = w.getLastPOR() 1799 except NotImplementedError: 1800 # the por we tried to walk was bad 1801 raise PORError 1802 if por is None: 1803 # no last item 1804 raise PORError 1805 else: 1806 return por

1807

1808 - def getLastAccUnder(self, por=None):

1809 ''' 1810 Gets a L{POR} to the last item of the last accessible under the given root. 1811 When L{por} is None, the L{task_por} is used. 1812 1813 @param por: A point of regard; uses the current task's POR if none supplied 1814 @type por: L{POR} 1815 @return: A point of regard to the last accessible under the given POR 1816 @rtype: L{POR} 1817 @raise PORError: When the L{POR} is invalid 1818 ''' 1819 por = por or self.task_por 1820 while 1: 1821 try: 1822 por = IAccessibleNav(por).getLastAccChild() 1823 except NotImplementedError: 1824 # we can't walk this POR 1825 raise PORError 1826 except LookupError: 1827 old = por 1828 try: 1829 # get the last visible or invisible item 1830 por = IItemNav(por).getLastItem(False) 1831 except LookupError: 1832 pass 1833 if por == old: 1834 # stop when we haven't moved, else continue 1835 return por

1836

1837 - def getAccFromPath(self, por=None, *path):

1838 ''' 1839 Gets a L{POR} representing the accessible found by treating the path 1840 integers as descendant indices stating at the given L{POR}. When no POR is 1841 provided, the L{task_por} is used as the starting point. 1842 1843 @param por: A point of regard; uses the current task's POR if none supplied 1844 @type por: L{POR} 1845 @param path: Integers indicate the path to the desired object 1846 @type path: integer 1847 @return: Point of regard for the descendant at the specified path 1848 @rtype: L{POR} 1849 ''' 1850 por = por or self.task_por 1851 try: 1852 # try to get the child indicated by the path 1853 child_por = IAccessibleNav(por).getChildAcc(path[0]) 1854 except (IndexError, LookupError): 1855 return None 1856 # check if we need to recurse anymore 1857 path = path[1:] 1858 if not len(path): 1859 return child_por 1860 # recurse with the remainder of the path 1861 por_from_path = self.getAccFromPath(child_por, *path) 1862 return por_from_path

1863

1864 - def compareAncestorRoles(self, por=None, *roles):

1865 ''' 1866 Iterates through the given roles comparing them with the roles of the first 1867 len(roles) ancestors of the given L{POR} starting with the immediate 1868 parent. When no POR is provided, the L{task_por} is used as the starting 1869 point. 1870 1871 @param por: A point of regard; uses the current task's POR if none supplied 1872 @type por: L{POR} 1873 @param roles: Role names to use as a comparison 1874 @type roles: string 1875 @return: Did the given roles match the roles of the corresponding 1876 ancestors? 1877 @rtype: boolean 1878 ''' 1879 por = por or self.task_por 1880 # iterate all ancestors 1881 iter = self.iterAncestorAccs(allow_trivial=True) 1882 for name in roles: 1883 try: 1884 anc_name = self.getAccRoleName(iter.next()) 1885 except StopIteration: 1886 # not a match if we run out of ancestors 1887 return False 1888 if anc_name != name: 1889 return False 1890 return True

1891

1892 - def findAccByName(self, name, por=None, ancestor=False, depth_first=True):

1893 ''' 1894 Gets a L{POR} to the first accessible descendant or ancestor of the given 1895 L{POR} with the given name. 1896 1897 @param name: Name of the accessible to locate 1898 @type name: string 1899 @param por: A point of regard; uses the current task's POR if none supplied 1900 @type por: L{POR} 1901 @param ancestor: Search through ancestors (True) or descendants (False)? 1902 @type ancestor: boolean 1903 @param depth_first: Is the search depth-first (True) or breadth-first 1904 (False)? Only meaningful when ancestor is False. 1905 @type depth_first: boolean 1906 @return: Point of regard to the target if found or None if not 1907 @rtype: L{POR} 1908 ''' 1909 pred = lambda por: IAccessibleInfo(por).getAccName() == name 1910 return self.findAccByPredicate(pred, por, ancestor)

1911

1912 - def findAccByRole(self, role, por=None, ancestor=False, depth_first=True):

1913 ''' 1914 Gets a L{POR} to the first accessible descendant or ancestor of the given 1915 L{POR} with the given role. 1916 1917 @param role: Role of the accessible to locate 1918 @type role: string 1919 @param por: A point of regard; uses the current task's POR if none supplied 1920 @type por: L{POR} 1921 @param ancestor: Search through ancestors (True) or descendants (False)? 1922 @type ancestor: boolean 1923 @param depth_first: Is the search depth-first (True) or breadth-first 1924 (False)? Only meaningful when ancestor is False. 1925 @type depth_first: boolean 1926 @return: Point of regard to the target if found or None if not 1927 @rtype: L{POR} 1928 ''' 1929 pred = lambda por: IAccessibleInfo(por).hasAccRole(role) 1930 return self.findAccByPredicate(pred, por, ancestor)

1931

1932 - def findAccByObjId(self, objname, por=None, ancestor=False, depth_first=True):

1933 ''' 1934 Gets a L{POR} to the first accessible descendant or ancestor of the given 1935 L{POR} with the given 'id' attribute named objname. 1936 1937 @param objname: Object id name to search 1938 @type objname: string 1939 @param por: A point of regard; uses the current task's POR if none supplied 1940 @type por: L{POR} 1941 @param ancestor: Search through ancestors (True) or descendants (False)? 1942 @type ancestor: boolean 1943 @param depth_first: Is the search depth-first (True) or breadth-first 1944 (False)? Only meaningful when ancestor is False. 1945 @type depth_first: boolean 1946 @return: Point of regard to the target if found or None if not 1947 @rtype: L{POR} 1948 ''' 1949 pred = lambda por: self.getAccAttrs(por)['id'] == objname 1950 return self.findAccByPredicate(pred, por, ancestor)

1951

1952 - def findAccByPredicate(self, predicate, por=None, ancestor=False, 1953 depth_first=True):

1954 ''' 1955 Gets a L{POR} to the first accessible descendant or ancestor of the given 1956 L{POR} matching the given callable predicate. 1957 1958 @warning: This method should be considered unstable and likely to change in 1959 future versions of LSR 1960 1961 @param predicate: Search predicate that evaluates to True or False 1962 @type predicate: callable 1963 @param por: A point of regard; use the current task's POR if none supplied 1964 @type por: L{POR} 1965 @param ancestor: Search through ancestors (True) or descendants (False)? 1966 @type ancestor: boolean 1967 @param depth_first: Is the search depth-first (True) or breadth-first 1968 (False)? Only meaningful when ancestor is False. 1969 @type depth_first: boolean 1970 @return: Point of regard to the target if found or None if not 1971 @rtype: L{POR} 1972 ''' 1973 por = por or self.task_por 1974 try: 1975 ai = IAccessibleNav(por) 1976 if ancestor: 1977 return ai.findAncestorAcc(predicate) 1978 else: 1979 return ai.findDescendantAcc(predicate, depth_first) 1980 except NotImplementedError: 1981 return None 1982 except LookupError: 1983 raise PORError

1984

1985 - def moveToPointer(self):

1986 ''' 1987 Moves the L{task_por} to the pointer L{POR}. 1988 ''' 1989 self.task_por = self.tier.getPointer()

1990

1991 - def moveToItemStart(self):

1992 ''' 1993 Moves the L{task_por} to the first character in the current item of the 1994 L{POR}. 1995 ''' 1996 self.task_por.char_offset = 0

1997

1998 - def moveToPOR(self, por):

1999 ''' 2000 Moves the L{task_por} to the given L{POR}. Just a convenience method. A 2001 L{Perk} writer can set self.task_por = x if that is preferred. One 2002 advantage of using this method is that it will check if por is None and 2003 raise an error if so. 2004 2005 @raise PORError: When the L{POR} is invalid 2006 ''' 2007 if por is None: 2008 raise PORError 2009 self.task_por = por

2010

2011 - def moveToRoot(self):

2012 ''' 2013 Modifies the L{task_por} to the root of the view. 2014 ''' 2015 self.task_por = self.getRootAcc()

2016

2017 - def moveToEnd(self):

2018 ''' 2019 Modifies the L{task_por} to the beginning of the last item in the current 2020 view. 2021 2022 @raise PORError: When the L{POR} is invalid 2023 ''' 2024 self.task_por = self.getEndAcc()

2025

2026 - def getAccTextAttr(self, name, por=None):

2027 ''' 2028 Gets the value of the given attribute of an accessible of a given 2029 L{POR}. When L{por} is None, the L{task_por} is used. 2030 2031 Valid attribute names/value pairs include: (subject to change, GNOME ATK 2032 specification): 2033 2034 left-margin: The pixel width of the left margin 2035 right-margin: The pixel width of the right margin 2036 indent: The number of pixels that the text is indented 2037 invisible: Either "true" or "false" indicates whether text is visible or not 2038 editable: Either "true" or "false" indicates whether text is editable or not 2039 pixels-above-lines: Pixels of blank space to leave above each 2040 newline-terminated line. 2041 pixels-below-lines: Pixels of blank space to leave below each 2042 newline-terminated line. 2043 pixels-inside-wrap: Pixels of blank space to leave between wrapped lines 2044 inside the same newline-terminated line (paragraph). 2045 bg-full-height: "true" or "false" whether to make the background color for 2046 each character the height of the highest font used on the current line, or 2047 the height of the font used for the current character. 2048 rise: Number of pixels that the characters are risen above the baseline 2049 underline: "none", "single", "double" or "low" 2050 strikethrough: "true" or "false" whether the text is strikethrough 2051 size: The size of the characters. 2052 scale: The scale of the characters: a string representation of a double. 2053 weight: The weight of the characters. 2054 language: The language used 2055 family-name: The font family name 2056 bg-color: The background color: RGB value of the format "u,u,u" 2057 fg-color: The foreground color: RGB value of the format "u,u,u" 2058 bg-stipple: "true" if a GdkBitmap is set for stippling the background color. 2059 fg-stipple: "true" if a GdkBitmap is set for stippling the foreground color. 2060 wrap-mode: The wrap mode of the text, if any: "none", "char" or "word" 2061 direction: The direction of the text, if set: "none", "ltr" or "rtl" 2062 justification: The justification of the text, if set: "left", "right", 2063 "center" or "fill" 2064 stretch: The stretch of the text, if set: "ultra_condensed", 2065 "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", 2066 "expanded", "extra_expanded" or "ultra_expanded" 2067 variant: The capitalization of the text, if set: "normal" or "small_caps" 2068 style: The slant style of the text, if set: "normal", "oblique" or "italic" 2069 last-defined: not a valid text attribute, for finding end of enumeration 2070 2071 @param name: text attribute name, eg. "fg-color", "justification" 2072 @type name: string 2073 @param por: A point of regard; uses the current task's POR if none supplied 2074 @type por: L{POR} 2075 @return: value of attribute 2076 @rtype: string 2077 @raise PORError: When the L{POR} is invalid 2078 ''' 2079 por = por or self.task_por 2080 try: 2081 # get the info interface 2082 ai = IAccessibleInfo(por) 2083 value = ai.getAccTextAttr(name) 2084 return value 2085 except LookupError: 2086 # raise POR error if some accessible was dead, bad or missing 2087 raise PORError 2088 except NotImplementedError: 2089 return None

2090

2091 - def getAccAllTextAttrs(self, por=None):

2092 ''' 2093 Like L{getAccTextAttr}, but gets the values of all of the current 2094 attributes of an accessible of a given L{POR}. When L{por} is None, the 2095 L{task_por} is used. 2096 2097 @param por: A point of regard; use the current task's POR if none supplied 2098 @type por: L{POR} 2099 @return: Name/value pairs for all available attributes 2100 @rtype: dictionary 2101 @raise PORError: When the L{POR} is invalid 2102 @see: L{getAccTextAttr} 2103 ''' 2104 por = por or self.task_por

Source Code for Module Task.Tools.View