1 '''
2 Defines L{AccessEngineAPI} for navigating within an application and inspecting
3 and manipulating its accessible objects.
4
5 Provides methods for reading information from accessible objects and for
6 navigating relative to a L{AEPor}.
7
8 Methods prefixed with I{get} return the L{AEPor} of interest.
9 Methods prefixed with I{move} do modify these variables.
10 Methods prefixed with I{set} actually change properties of the accessible it
11
12 @note: Selected and editable states not being announced because they happen at
13 unexpected times or on undesireable accessibles. Selection can probably be
14 done properly with events. Editable we will just avoid for the time being.
15
16 @author: Peter Parente
17 @author: Pete Brunet
18 @author: Larry Weiss
19 @author: Brett Clippingdale
20 @author: Eirikur Hallgrimsson
21 @organization: IBM Corporation
22 @copyright: Copyright (c) 2005, 2007 IBM Corporation
23
24 @author: Frank Zenker
25 @author: Nicole Anacker
26 @author: Ramona Bunk
27 @organization: IT Science Center Ruegen gGmbH, Germany
28 @copyright: Copyright (c) 2007, 2008 ITSC Ruegen
29
30 @license: I{The BSD License}
31 All rights reserved. This program and the accompanying materials are made
32 available under the terms of the BSD license which accompanies
33 this distribution, and is available at
34 U{http://www.opensource.org/licenses/bsd-license.php}
35 '''
36
37 import AccessEngine
38 from AccessEngine.AEAccInterfaces import *
39 from AccessEngine.AEWalkers import *
40 from AccessEngine.AEPor import AEPor
41 from AEApiError import *
42 from Tools.i18n import _
43 from AccessEngine import AEConstants
44 from AccessEngine.AEDevice.AEOutput import Word
45
46
47
48 _state_descriptions = {('checked', False) : _('unchecked'),
49 ('checked', True) : _('checked'),
50 ('unchecked', True) : _('unchecked'),
51 ('enabled', False) : _('disabled'),
52 ('disabled', True) : _('disabled'),
53
54
55 ('collapsed', False) : _('expanded'),
56 ('collapsed', True) : _('collapsed'),
57 ('expanded', False) : _('collapsed'),
58 ('expanded', True) : _('expanded'),
59 ('animated', False) : _('not animated'),
60 ('animated', True) : _('animated'),
61
62
63 }
64
65
66
67
69 '''
70 Gets the accessible name of the component at the provided L{AEPor}.
71
72 @param por: A point of regard
73 @type por: L{AEPor}
74 @return: The accessible name of the control of the at the point of regard
75 @rtype: string
76 @raise PORError: When the L{AEPor} is invalid
77 '''
78 try:
79 return IAccessibleInfo(por).getAccName()
80 except LookupError:
81 raise PORError
82 except NotImplementedError:
83 return None
84
86 '''
87 Gets the accessible description of the component at the provided L{AEPor}.
88
89 @param por: A point of regard
90 @type por: L{AEPor}
91 @return: The accessible description of the control of the at the point of
92 regard
93 @rtype: string
94 @raise PORError: When the L{AEPor} is invalidd
95 '''
96 try:
97 return IAccessibleInfo(por).getAccDescription()
98 except LookupError:
99 raise PORError
100 except NotImplementedError:
101 return None
102
104 '''
105 Gets the number of child accessibles of the accessible indicated by
106
107 @param por: A point of regard
108 @type por: L{AEPor}
109 @return: Number of accessible children
110 @rtype: integer
111 @raise PORError: When the L{AEPor} is invalid
112 '''
113 try:
114 return IAccessibleInfo(por).getAccChildCount()
115 except LookupError:
116 raise PORError
117 except NotImplementedError:
118 return None
119
121 '''
122 Gets the unlocalized role for the accessible at the provided L{AEPor}.
123
124 The return value of this method is not suitable for output. It is suitable
125 for comparison to known role values.
126
127 @param por: A point of regard
128 @type por: L{AEPor}
129 @return: The role name of the control of the at the point of regard
130 @rtype: string
131 @raise PORError: When the L{AEPor} is invalid
132 '''
133 try:
134 return IAccessibleInfo(por).getAccRole()
135 except LookupError:
136 raise PORError
137 except NotImplementedError:
138 return None
139
141 '''
142 Gets the localized role name for the accessible at the provided L{AEPor}.
143
144 The return value of this method is suitable for output. It is not suitable
145 for comparison to known role values.
146
147 @param por: A point of regard
148 @type por: L{AEPor}
149 @return: The role name of the control of the at the point of regard
150 @rtype: string
151 @raise PORError: When the L{AEPor} is invalid
152 '''
153 try:
154 return IAccessibleInfo(por).getAccRoleName()
155 except LookupError:
156 raise PORError
157 except NotImplementedError:
158 return None
159
161 '''
162 Gets if the accessible at the given L{AEPor} has the given role. The role is
163 assumed to be a string that can be mapped to an appropriate role constant on
164 the platform or indicates an extension role that is represented by a string.
165
166 @param role: Name of a role (e.g. 'terminal', 'glass pane', 'button')
167 @type role: string
168 @param por: A point of regard
169 @type por: L{AEPor}
170 @return: Does the L{AEPor} have the given role?
171 @rtype: boolean
172 @raise PORError: When the L{AEPor} is invalid
173 '''
174 try:
175 return IAccessibleInfo(por).hasAccRole(role)
176 except LookupError:
177 raise PORError
178 except NotImplementedError:
179 return False
180
182 '''
183 Gets if the accessible at the given L{AEPor} has any one of the given roles.
184 The role is assumed to be a string that can be mapped to an appropriate role
185 constant on the platform or indicates an extension role that is represented
186 by a string.
187
188 This method is more efficient than calling L{hasAccRole} multiple times.
189
190 @param roles: Name of a role (e.g. 'terminal', 'glass pane', 'button')
191 @type roles: string
192 @param por: A point of regard
193 @type por: L{AEPor}
194 @return: Does the L{AEPor} have the given role?
195 @rtype: boolean
196 @raise PORError: When the L{AEPor} is invalid
197 '''
198 try:
199 return IAccessibleInfo(por).hasAccOneRole(*roles)
200 except LookupError:
201 raise PORError
202 except NotImplementedError:
203 return False
204
206 '''
207 Iterates through the given roles comparing them with the roles of the first
208 len(roles) ancestors of the given L{AEPor} starting with the immediate
209 parent.
210
211 @param por: A point of regard
212 @type por: L{AEPor}
213 @param roles: Role names to use as a comparison
214 @type roles: string
215 @return: Did the given roles match the roles of the corresponding
216 ancestors?
217 @rtype: boolean
218 '''
219
220 iter = iterAncestorAccs(por, allow_trivial=True)
221 for name in roles:
222 try:
223 anc_name = getAccRoleName(iter.next())
224 except StopIteration:
225
226 return False
227 if anc_name != name:
228 return False
229 return True
230
231 -def getStateText(por, name=None, value=None):
232 '''
233 Gets text describing the states of the given L{AEPor} that might be of
234 interest to the user. If name is specified, only gets the text describing
235 the state with that non-translated name. If name is not specified, gets text
236 describing all states of interest.
237
238 @param por: A point of regard
239 @type por: L{AEPor}
240 @param name: Name of the state to describe
241 @type name: string
242 @param value: Value of the state to describe
243 @type value: string
244 @return: String describing the state(s), None if named state not found
245 @rtype: string
246 @raise PORError: When the L{AEPor} is invalid
247 '''
248
249 if name is not None and value is not None:
250 return _state_descriptions.get((name, value))
251
252 try:
253
254 states = IAccessibleInfo(por).getAccStates()
255 except LookupError:
256 raise PORError
257 except NotImplementedError:
258 return None
259
260 text = []
261 for name in states:
262 try:
263
264 desc = _state_descriptions[(name, True)]
265 except KeyError:
266 continue
267 text.append(desc)
268 if not text:
269 return None
270 return ' '.join(text)
271
273 '''
274 Gets if the accessible at the given L{AEPor} has the given state. The state
275 is assumed to be a string that can be mapped to an appropriate state
276 constant on the platform or indicates an extension state that is
277 represented by a string.
278
279 @param state: Name of a state (e.g. 'focused', 'selected', 'selectable')
280 @type state: string
281 @param por: A point of regard
282 @type por: L{AEPor}
283 @return: Does the L{AEPor} have the given state?
284 @rtype: boolean
285 @raise PORError: When the L{AEPor} is invalid
286 '''
287 try:
288 return IAccessibleInfo(por).hasAccState(state)
289 except LookupError:
290 raise PORError
291 except NotImplementedError:
292 return False
293
295 '''
296 Gets if the accessible at the given L{AEPor} has one of the given states.
297 The state is assumed to be a string that can be mapped to an appropriate
298 state constant on the platform or indicates an extension state that is
299 represented by a string.
300
301 This method is more efficient than calling L{hasAccState} multiple times.
302
303 @param states: Names of states (e.g. 'focused', 'selected', 'selectable')
304 @type states: string
305 @param por: A point of regard
306 @type por: L{AEPor}
307 @return: Does the L{AEPor} have the given state?
308 @rtype: boolean
309 @raise PORError: When the L{AEPor} is invalid
310 '''
311 try:
312 return IAccessibleInfo(por).hasAccOneState(*states)
313 except LookupError:
314 raise PORError
315 except NotImplementedError:
316 return False
317
319 '''
320 Gets a dictionary of name:value attribute pairs at the provided L{AEPor}.
321
322 @param por: A point of regard
323 @type por: L{AEPor}
324 @return: Name/value pairs for all available attributes
325 @rtype: dictionary of string
326 @raise PORError: When the L{AEPor} is invalid
327 '''
328 try:
329 return IAccessibleInfo(por).getAccAttrs()
330 except LookupError:
331
332 raise PORError
333 except NotImplementedError:
334 return None
335
337 '''
338 Sets the system input focus, selection, and caret offset to the provided
339 L{AEPor}. Ignores errors trying each as focus, selection, and caret offset
340 are not all supported by every control.
341
342 @param por: A point of regard
343 @type por: L{AEPor}
344 @return: False if none of focus, selection, or caret can be set; True if
345 at least one was set
346 @rtype: boolean
347 @raise PORError: When the L{AEPor} is invalid
348 '''
349 count = 0
350 try:
351 setAccFocus(por)
352 except (NotImplementedError, ActionError):
353 count += 1
354 try:
355 setAccSelected(por)
356 except (NotImplementedError, ActionError):
357 count += 1
358 try:
359 setAccCaret(por)
360 except (NotImplementedError, ActionError):
361 count += 1
362 return count != 3
363
364
365
366
368 '''
369 Gets the names of the actions that can be performed at the provided L{AEPor}.
370
371 @note: The names appear to be unlocalized.
372
373 @param por: A point of regard
374 @type por: L{AEPor}
375 @return: Names of the actions at the point of regard
376 @rtype: list of string
377 @raise PORError: When the L{AEPor} is invalid
378 '''
379 try:
380 return IAccessibleInfo(por).getAccActionNames()
381 except LookupError:
382 raise PORError
383 except NotImplementedError:
384 return None
385
387 '''
388 Looks for the given action name in all action names of the por accessible.
389
390 @param actionName:
391 @type actionName: string
392 @param por: A point of regard
393 @type por: L{AEPor}
394 @return: Was the given action name found?
395 @rtype: boolean
396 @raise PORError: When the L{AEPor} is invalid
397 '''
398 actions = getAccActionNames(por)
399 for action in actions:
400 if action == actionName: return True
401 return False
402
404 '''
405 Gets the descriptions of the actions that can be performed at the
406
407 @note: Unsure if the descriptions are localized or not.
408
409 @param por: A point of regard
410 @type por: L{AEPor}
411 @return: Descriptions of the actions at the point of regard
412 @rtype: list of string
413 @raise PORError: When the L{AEPor} is invalid
414 '''
415 try:
416 return IAccessibleInfo(por).getAccActionDescs()
417 except LookupError:
418 raise PORError
419 except NotImplementedError:
420 return None
421
423 '''
424 Gets the key bindings associated with the actions at the given L{AEPor}.
425
426 @param por: A point of regard
427 @type por: L{AEPor}
428 @return: Names of key sequences that all trigger the same action
429 @rtype: list of tuple of string
430 @raise PORError: When the L{AEPor} is invalid
431 '''
432 try:
433 return IAccessibleInfo(por).getAccActionKeys()
434 except LookupError:
435 raise PORError
436 except NotImplementedError:
437 return None
438
440 '''
441 Gets the key binding associated with the common "click" action which
442 appears to be the action most commonly accessed by a hotkey. Only returns
443 the last of all defined hotkey sequences as it is usually the globally
444 available hotkey rather than the local menu mnemonic or a sequence for
445 activating the menu followed by the mnemonic.
446
447 @param por: A point of regard
448 @type por: L{AEPor}
449 @return: Hotkey sequence
450 @rtype: string
451 @raise PORError: When the L{AEPor} is invalid
452 '''
453 names = getAccActionNames(por)
454 try:
455 i = names.index('click')
456 except (ValueError, NotImplementedError, AttributeError):
457 return None
458 keys = getAccActionKeys(por)
459 try:
460
461 return keys[i][-1] or None
462 except IndexError:
463 return None
464
466 '''
467 Executes the action at the given index in the list of all actions named
468 in the return value from L{getAccActionNames}.
469
470 @param index: Index of the action to execute.
471 @type index: integer
472 @param por: A point of regard
473 @type por: L{AEPor}
474 @raise PORError: When the L{AEPor} is invalid
475 @raise ActionError: When executing the action fails for some reason
476 '''
477 try:
478
479 rv = IAccessibleAction(por).doAccAction(index)
480 except LookupError:
481
482 raise PORError
483 except NotImplementedError:
484
485 return
486 else:
487 if not rv:
488
489 raise ActionError
490
491
492
493
495 '''
496 Gets the accessible name of the application containing the L{AEPor}.
497
498 @param por: A point of regard
499 @type por: L{AEPor}
500 @return: Name of the application
501 @rtype: string
502 @raise PORError: When the L{AEPor} is invalid
503 '''
504 try:
505 return IAccessibleNav(por).getApplicationAcc()
506 except LookupError:
507 raise PORError
508 except NotImplementedError:
509 return None
510
512 '''
513 Gets the accessible name of the application containing the L{AEPor}.
514
515 @param por: A point of regard
516 @type por: L{AEPor}
517 @return: Name of the application
518 @rtype: string
519 @raise PORError: When the L{AEPor} is invalid
520 '''
521 try:
522 return IAccessibleInfo(por).getAccAppName()
523 except LookupError:
524 raise PORError
525 except NotImplementedError:
526 return None
527
529 '''
530 Gets the accessible name of the window containing the L{AEPor}.
531
532 @param por: A point of regard
533 @type por: L{AEPor}
534 @return: Name of the window
535 @rtype: string
536 @raise PORError: When the L{AEPor} is invalid
537 '''
538 frame_por = getRootAcc(por)
539 try:
540 return IAccessibleInfo(frame_por).getAccName()
541 except LookupError:
542 raise PORError
543 except NotImplementedError:
544 return None
545
547 '''
548 Gets the POSIX locale of the application containing the L{AEPor} as a string.
549
550 @param por: A point of regard
551 @type por: L{AEPor}
552 @return: POSIX locale of the application
553 @rtype: string
554 @raise PORError: When the L{AEPor} is invalid
555 '''
556 try:
557 return IAccessibleInfo(por).getAccAppLocale()
558 except LookupError:
559 raise PORError
560 except NotImplementedError:
561 return None
562
564 '''
565 Gets the L{AEPor} representing the focus of the foreground application. If
566 no focus event has been received yet by this L{AETier} and search is True,
567 performs a search for an accessible with state focus.
568
569 @note: Setting search to True can result in a very long search operation.
570 Be careful.
571 @return: Point of regard to the focused accessible
572 @rtype: L{AEPor}
573 '''
574 por = tier.getFocus()
575 if por is None and search:
576
577 pred = lambda por: IAccessibleInfo(por).hasAccState('focused')
578 return findAccByPredicate(pred, getViewRootAcc(), False)
579 return por
580
582 '''
583 Sets the system input focus to the accessible in the provided L{AEPor}.
584
585 @param por: A point of regard
586 @type por: L{AEPor}
587 @return: Is setting the focus supported?
588 @rtype: boolean
589 @raise PORError: When the L{AEPor} is invalid
590 @raise FocusError: When focusing on the L{AEPor} is supported but rejected by
591 the system for some reason
592 '''
593 try:
594
595 rv = IAccessibleAction(por).setAccFocus()
596 except LookupError:
597
598 raise PORError
599 except NotImplementedError:
600
601 return False
602 else:
603 if not rv:
604
605 raise FocusError
606 return True
607
608
609
610
612 '''
613 Gets the position of the accessible object, usually upper-left corner
614
615 @param por: A point of regard
616 @type por: L{AEPor}
617 @return: x,y coordinates of the accessible's position
618 @rtype: 2-tuple of integer
619 @raise PORError: When the L{AEPor} is invalid
620 '''
621 try:
622 return IAccessibleInfo(por).getAccPosition()
623 except LookupError:
624 raise PORError
625 except NotImplementedError:
626 return None
627
629 '''
630 Returns the focal point of a visual component at the L{AEPor}.
631
632 @param por: A point of regard
633 @type por: L{AEPor}
634 @return: x,y coordinates of the focal point of the point of regard
635 @rtype: 2-tuple of integer
636 @raise PORError: When the L{AEPor} is invalid
637 '''
638
639 try:
640 return IAccessibleInfo(por).getAccVisualPoint()
641 except LookupError:
642 raise PORError
643 except NotImplementedError:
644 return None
645
647 '''
648 Returns the extents of a visual component at the L{AEPor}.
649
650 @param por: A point of regard
651 @type por: L{AEPor}
652 @return: Width and height of the point of regard
653 @rtype: 2-tuple of integer
654 @raise PORError: When the L{AEPor} is invalid
655 '''
656 try:
657 return IAccessibleInfo(por).getAccVisualExtents()
658 except LookupError:
659 raise PORError
660 except NotImplementedError:
661 return None
662
664 '''
665 Gets the label for the accessible at the provided L{AEPor}.
666
667 @param por: A point of regard
668 @type por: L{AEPor}
669 @return: The AccessibleName of the component that labels the component at
670 the given location.
671 @rtype: string
672 @raise PORError: When the L{AEPor} is invalid
673 '''
674 try:
675
676 pors = IAccessibleInfo(por).getAccRelations('labelled by')
677 except LookupError:
678 raise PORError
679 except NotImplementedError:
680 return None
681
682 label = []
683 for por in pors:
684 try:
685 label.append(getItemText(por))
686 except PORError:
687
688 pass
689
690 if not label:
691 return None
692 return ' '.join(label)
693
695 '''
696 Gets the L{AEPor}s to accessibles related to the given L{AEPor} in the manner
697 stated by the given relation.
698
699 @param por: A point of regard
700 @type por: L{AEPor}
701 @param relation: Type of relation
702 @type relation: string
703 @return: Point of regard to related accessibles
704 @rtype: list of L{AEPor}s
705 @raise PORError: When the L{AEPor} is invalid
706 '''
707 try:
708
709 return IAccessibleInfo(por).getAccRelations(relation)
710 except LookupError:
711 raise PORError
712 except NotImplementedError:
713 return None
714
716 '''
717 Get the number of members within an accessible group. Often used to
718 determine the size of a radio or menu group.
719
720 @param por: Point of regard
721 @type por: L{AEPor}
722 @return: Set/group size.
723 @rtype: integer
724 '''
725 attrs = getAccAttrs(por)
726 try:
727 return int(attrs['setsize'])
728 except (KeyError, TypeError):
729 relations = getAccRelations('member of', por)
730 if relations is not None and len(relations) > 0:
731 return len(relations)
732 else:
733 return None
734
736 '''
737 Get the position of an accessible within a group.
738
739 @param por: Point of regard
740 @type por: L{AEPor}
741 @return: Position within a group.
742 @rtype: integer
743 '''
744 attrs = getAccAttrs(por)
745 try:
746 return int(attrs['posinset'])
747 except (KeyError, TypeError):
748 return None
749
751 '''
752 Obtain a resource locator ('URI') string which can be used to access the
753 content to which this link "points" or is connected.
754
755 @param index: anchor index
756 @type index: integer
757 @param por: Point of regard
758 @type por: L{AEPor}
759 @return: URI string
760 @rtype: string
761 @raise PORError: When the L{AEPor} is invalid
762 '''
763 try:
764 rv = IAccessibleInfo(por).getAccURI(index)
765 return rv
766 except LookupError:
767 raise PORError
768 except NotImplementedError:
769 return None
770 else:
771 return None
772
774 '''
775 Obtain the number of separate anchors associated with this accessible.
776
777 @param por: Point of regard
778 @type por: L{AEPor}
779 @return: Number of anchors
780 @rtype: integer
781 @raise PORError: When the L{AEPor} is invalid
782 '''
783 try:
784 rv = IAccessibleInfo(por).getAccAnchorCount()
785 return rv
786 except LookupError:
787 raise PORError
788 except NotImplementedError:
789 return None
790 else:
791 return None
792
793
794
795
796 -def getItemText(por):
797 '''
798 Gets the text of the complete item that includes the specified L{AEPor}.
799
800 @param por: A point of regard
801 @type por: L{AEPor}
802 @return: Item text at the given point of regard
803 @rtype: string
804 @raise PORError: When the L{AEPor} is invalid
805 '''
806 try:
807 text = IAccessibleInfo(por).getAccItemText()
808 return text
809 except LookupError:
810 raise PORError
811 except NotImplementedError:
812 return None
813
814 -def getWordText(por):
815 '''
816 Gets the text of the current word at the specified L{AEPor}.
817
818 @param por: A point of regard
819 @type por: L{AEPor}
820 @return: Word text at the given point of regard
821 @rtype: string
822 @raise PORError: When the L{AEPor} is invalid
823 '''
824 try:
825 text = IAccessibleInfo(por).getAccItemText()
826 except LookupError:
827 raise PORError
828 except NotImplementedError:
829 return None
830 prev, curr, next = Word.getContextFromString(text, por)
831 return str(curr)
832
833 -def getCharText(por):
834 '''
835 Gets the text of the current character at the specified L{AEPor}.
836
837 @param por: A point of regard
838 @type por: L{AEPor}
839 @return: Character at the given point of regard
840 @rtype: string
841 @raise PORError: When the L{AEPor} is invalid
842 '''
843 try:
844 text = IAccessibleInfo(por).getAccItemText()
845 if len(text) <= por.char_offset:
846 return u''
847 else:
848 return text[por.char_offset]
849 except LookupError:
850 raise PORError
851 except NotImplementedError:
852 return None
853
854 -def getAccText(start, end=None):
855 '''
856 Gets all of the text from the starting offset to the ending offset at the
857 given L{AEPor}s. If end is None, the L{start} is used possibly for both cases.
858
859 @param start: Point of regard to the start of the text run
860 @type start: L{AEPor}
861 @param end: Point of regard to the end of the text run
862 @type end: L{AEPor}
863 @return: Text between start and end offsets
864 @rtype: string
865 @raise PORError: When the L{AEPor} is invalid
866 '''
867 if end is None:
868 end = start
869 try:
870 return IAccessibleInfo(start).getAccText(end)
871 except LookupError:
872 raise PORError
873 except NotImplementedError:
874 return None
875
877 '''
878 Gets the length of the text in the L{AEPor}.
879
880 @param por: Point of regard to an object containing text
881 @type por: L{AEPor}
882 @return: Number of characters in the text or None when character count not
883 supported
884 @rtype: integer
885 @raise PORError: When the L{AEPor} is invalid
886 '''
887 try:
888 return IAccessibleInfo(por).getAccTextCharCount()
889 except LookupError:
890 raise PORError
891 except NotImplementedError:
892 return None
893
894 -def getAccTextBetween(start_por, end_por=None, only_visible=False):
895 '''
896 Gets all text between two point of regards. If L{end_por} is not given,
897 defaults to getting all text to the end of the current accessible.
898
899
900 @param start_por: A point of regard indicating the start of the text range
901 @type start_por: L{AEPor}
902 @param end_por: A point of regard indicating the end of the text range;
903 use the POR to the end of the accessible if none supplied
904 @type end_por: L{AEPor}
905 @param only_visible: Only consider visible items? Defaults to False.
906 @type only_visible: boolean
907 @return: Text between the two L{AEPor}s
908 @rtype: string
909 @raise PORError: When the provided L{AEPor} is invalid
910 '''
911 w = AccessibleItemWalker(start_por, only_visible=only_visible)
912
913 text = []
914 curr = start_por
915 prev = start_por
916
917 while 1:
918 if curr is None or (end_por is None and not curr.isSameAcc(start_por)):
919
920
921 break
922 elif end_por.isSameItem(curr):
923
924 text.append(getItemText(curr)[:end_por.char_offset])
925 break
926 elif curr.isItemAfter(end_por):
927
928 text.append(getItemText(prev)[:end_por.char_offset])
929 break
930 else:
931
932 text.append(getItemText(curr))
933 prev = curr
934 try:
935 curr = w.getNextPOR()
936 except NotImplementedError:
937
938 break
939 return ''.join(text)
940
941 -def setAccText(text, por):
942 '''
943 Sets the given string as the text at the given L{AEPor}. All existing text
944 is replaced.
945
946 @param text: Text to set
947 @type text: string
948 @param por: Point of regard
949 @type por: L{AEPor}
950 @return: Is setting the text supported?
951 @rtype: boolean
952 @raise PORError: When the L{AEPor} is invalid
953 @raise TextError: When the text operation fails
954 '''
955 try:
956 rv = IAccessibleAction(por).setAccText(text)
957 except LookupError:
958 raise PORError
959 except NotImplementedError:
960
961 return False
962 else:
963 if not rv:
964
965 raise TextError
966 return True
967
968 -def insertAccText(text, por, attrs=None):
969 '''
970 Inserts the given text at the given L{AEPor}. If attributes are specified,
971 they will be applied to the inserted text.
972
973 @param text: Text to set
974 @type text: string
975 @param por: Point of regard
976 @type por: L{AEPor}
977 @param attrs: Attributes to set over the text range
978 @type attrs: dictionary
979 @return: Is inserting text supported?
980 @rtype: boolean
981 @raise PORError: When the L{AEPor} is invalid
982 @raise TextError: When the text operation fails
983 '''
984 try:
985 rv = IAccessibleAction(por).setAccText(text, attrs)
986 except LookupError:
987 raise PORError
988 except NotImplementedError:
989
990 return False
991 else:
992 if not rv:
993
994 raise TextError
995 return True
996
997 -def copyAccText(start, end=None):
998 '''
999 Copies the text from the given starting L{AEPor} to the ending L{AEPor}. When
1000 L{end} is None, the L{start} is used.
1001
1002 @param start: Point of regard to the start of the text run
1003 @type start: L{AEPor}
1004 @param end: Point of regard to the end of the text run
1005 @type end: L{AEPor}
1006 @return: Is copy supported?
1007 @rtype: boolean
1008 @raise PORError: When the L{AEPor} is invalid
1009 @raise TextError: When the text operation fails
1010 '''
1011 if end is None:
1012 end = start
1013 try:
1014 rv = IAccessibleAction(start).copyAccText(end)
1015 except LookupError:
1016 raise PORError
1017 except NotImplementedError:
1018
1019 return False
1020 else:
1021 if not rv:
1022
1023 raise TextError
1024 return True
1025
1026 -def cutAccText(start, end=None):
1027 '''
1028 Cuts the text from the given starting L{AEPor} to the ending L{AEPor}. When
1029 L{end} is None, the L{start} is used.
1030
1031 @param start: Point of regard to the start of the text run
1032 @type start: L{AEPor}
1033 @param end: Point of regard to the end of the text run
1034 @type end: L{AEPor}
1035 @return: Is cut supported?
1036 @rtype: boolean
1037 @raise PORError: When the L{AEPor} is invalid
1038 @raise TextError: When the text operation fails
1039 '''
1040 if end is None:
1041 end = start
1042 try:
1043 rv = IAccessibleAction(start).cutAccText(end)
1044 except LookupError:
1045 raise PORError
1046 except NotImplementedError:
1047
1048 return False
1049 else:
1050 if not rv:
1051
1052 raise TextError
1053 return True
1054
1055 -def pasteAccText(por):
1056 '''
1057 Pastes the clipboard text at the given L{AEPor}.
1058
1059 @param por: Point of regard to the insertion point
1060 @type por: L{AEPor}
1061 @return: Is paste supported?
1062 @rtype: boolean
1063 @raise PORError: When the L{AEPor} is invalid
1064 @raise TextError: When the text operation fails
1065 '''
1066 try:
1067 rv = IAccessibleAction(por).pasteAccText()
1068 except LookupError:
1069 raise PORError
1070 except NotImplementedError:
1071
1072 return False
1073 else:
1074 if not rv:
1075
1076 raise TextError
1077 return True
1078
1079 -def deleteAccText(start, end=None):
1080 '''
1081 Deletes the text from the given starting L{AEPor} to the ending L{AEPor}. When
1082 L{end} is None, the L{start} is used.
1083
1084 @param start: Point of regard to the start of the text run
1085 @type start: L{AEPor}
1086 @param end: Point of regard to the end of the text run
1087 @type end: L{AEPor}
1088 @return: Is delete supported?
1089 @rtype: boolean
1090 @raise PORError: When the L{AEPor} is invalid
1091 @raise TextError: When the text operation fails
1092 '''
1093 if end is None:
1094 end = start
1095 try:
1096 rv = IAccessibleAction(start).cutAccText(end)
1097 except LookupError:
1098 raise PORError
1099 except NotImplementedError:
1100
1101 return False
1102 else:
1103 if not rv:
1104
1105 raise TextError
1106 return True
1107
1108 -def selectAccText(start, end=None, n=None):
1109 '''
1110 Selects the text from the given starting L{AEPor} to the ending L{AEPor}. If n
1111 is None, a new selection range is added, else the nth selection is modified
1112 to the given range. When L{end} is None, the L{start} is used.
1113
1114 @param start: Point of regard to the start of the text run
1115 @type start: L{AEPor}
1116 @param end: Point of regard to the end of the text run
1117 @type end: L{AEPor}
1118 @return: Is text selection supported?
1119 @rtype: boolean
1120 @raise PORError: When the L{AEPor} is invalid
1121 @raise SelectError: When the selection operation fails
1122 '''
1123 if end is None:
1124 end = start
1125 try:
1126 rv = IAccessibleAction(start).selectAccText(end, n)
1127 except LookupError:
1128 raise PORError
1129 except NotImplementedError:
1130
1131 return False
1132 else:
1133 if not rv:
1134
1135 raise SelectError
1136 return True
1137
1138 -def deselectAccText(por, n=None):
1139 '''
1140 Deselects the text from the given L{AEPor}. If n is None, all selected ranges
1141 are removed, else the nth selection is removed.
1142
1143 @param por: Point of regard to the text area
1144 @type por: L{AEPor}
1145 @return: Is text deselection supported?
1146 @rtype: boolean
1147 @raise PORError: When the L{AEPor} is invalid
1148 @raise SelectError: When the deselection operation fails
1149 '''
1150 try:
1151 rv = IAccessibleAction(por).deselectAccText(n)
1152 except LookupError:
1153 raise PORError
1154 except NotImplementedError:
1155
1156 return False
1157 else:
1158 if not rv:
1159
1160 raise SelectError
1161 return True
1162
1163 -def getAccTextSelection(por, n=None):
1164 '''
1165 Gets a list of all selected text if n is None, or the nth selection if it
1166 is specified, at the L{AEPor}.
1167
1168 @param n: Index of text selection to get or None
1169 @type n: integer
1170 @param por: A point of regard
1171 @type por: L{AEPor}
1172 @return: List of selected text strings
1173 @rtype: list of string
1174 @raise PORError: When the L{AEPor} is invalid
1175 '''
1176 try:
1177 return IAccessibleInfo(por).getAccTextSelection(n)
1178 except LookupError:
1179 raise PORError
1180 except NotImplementedError:
1181 return None
1182
1184 '''
1185 Gets the number of discontiguous text selections in the L{AEPor}.
1186
1187 @param por: Point of regard to an object containing text
1188 @type por: L{AEPor}
1189 @return: Number of selections or None when selections are not supported
1190 @rtype: integer
1191 @raise PORError: When the L{AEPor} is invalid
1192 '''
1193 try:
1194 return IAccessibleInfo(por).getAccTextSelectionCount()
1195 except LookupError:
1196 raise PORError
1197 except NotImplementedError:
1198 return None
1199
1201 '''
1202 Gets a dictionary of name:value default text attribute pairs at the provided
1203
1204 @param por: A point of regard
1205 @type por: L{AEPor}
1206 @return: Name/value pairs for all available attributes
1207 @rtype: dictionary
1208 @raise PORError: When the L{AEPor} is invalid
1209 '''
1210 try:
1211 return IAccessibleInfo(por).getAccDefTextAttrs()
1212 except LookupError:
1213
1214 raise PORError
1215 except NotImplementedError:
1216 return None
1217
1219 '''
1220 Like L{getAccTextAttr}, but gets the values of all of the current
1221 attributes of an accessible of a given L{AEPor}.
1222
1223 @param por: A point of regard
1224 @type por: L{AEPor}
1225 @return: Name/value pairs for all available attributes
1226 @rtype: dictionary
1227 @raise PORError: When the L{AEPor} is invalid
1228 @see: L{getAccTextAttr}
1229 '''
1230 try:
1231
1232 return IAccessibleInfo(por).getAccAllTextAttrs()
1233 except LookupError:
1234
1235 raise PORError
1236 except NotImplementedError:
1237 return None
1238
1239 -def getAccTextAttr(name, por):
1240 '''
1241 Gets the value of the given attribute of an accessible of a given L{AEPor}.
1242
1243 Valid attribute names/value pairs include: (subject to change, GNOME ATK
1244 specification):
1245
1246 left-margin: The pixel width of the left margin
1247 right-margin: The pixel width of the right margin
1248 indent: The number of pixels that the text is indented
1249 invisible: Either "true" or "false" indicates whether text is visible or not
1250 editable: Either "true" or "false" indicates whether text is editable or not
1251 pixels-above-lines: Pixels of blank space to leave above each
1252 newline-terminated line.
1253 pixels-below-lines: Pixels of blank space to leave below each
1254 newline-terminated line.
1255 pixels-inside-wrap: Pixels of blank space to leave between wrapped lines
1256 inside the same newline-terminated line (paragraph).
1257 bg-full-height: "true" or "false" whether to make the background color for
1258 each character the height of the highest font used on the current line, or
1259 the height of the font used for the current character.
1260 rise: Number of pixels that the characters are risen above the baseline
1261 underline: "none", "single", "double" or "low"
1262 strikethrough: "true" or "false" whether the text is strikethrough
1263 size: The size of the characters.
1264 scale: The scale of the characters: a string representation of a double.
1265 weight: The weight of the characters.
1266 language: The language used
1267 family-name: The font family name
1268 bg-color: The background color: RGB value of the format "u,u,u"
1269 fg-color: The foreground color: RGB value of the format "u,u,u"
1270 bg-stipple: "true" if a GdkBitmap is set for stippling the background color.
1271 fg-stipple: "true" if a GdkBitmap is set for stippling the foreground color.
1272 wrap-mode: The wrap mode of the text, if any: "none", "char" or "word"
1273 direction: The direction of the text, if set: "none", "ltr" or "rtl"
1274 justification: The justification of the text, if set: "left", "right",
1275 "center" or "fill"
1276 stretch: The stretch of the text, if set: "ultra_condensed",
1277 "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded",
1278 "expanded", "extra_expanded" or "ultra_expanded"
1279 variant: The capitalization of the text, if set: "normal" or "small_caps"
1280 style: The slant style of the text, if set: "normal", "oblique" or "italic"
1281 last-defined: not a valid text attribute, for finding end of enumeration
1282
1283 @param name: text attribute name, eg. "fg-color", "justification"
1284 @type name: string
1285 @param por: A point of regard
1286 @type por: L{AEPor}
1287 @return: value of attribute
1288 @rtype: string
1289 @raise PORError: When the L{AEPor} is invalid
1290 '''
1291 try:
1292
1293 value = IAccessibleInfo(por).getAccTextAttr(name)
1294 return value
1295 except LookupError:
1296
1297 raise PORError
1298 except NotImplementedError:
1299 return None
1300
1301 -def setAccTextAttrs(start, end=None, **attrs):
1302 '''
1303 Sets the attributes of the text from the given starting L{AEPor} to the
1304 ending L{AEPor}. When L{end} is None, the L{start} is used.
1305
1306 @param attrs: Attributes to set over the text range
1307 @type attrs: dictionary
1308 @param start: Point of regard to the start of the text run
1309 @type start: L{AEPor}
1310 @param end: Point of regard to the end of the text run
1311 @type end: L{AEPor}
1312 @return: Is setting attributes supported?
1313 @rtype: boolean
1314 @raise PORError: When the L{AEPor} is invalid
1315 @raise TextError: When the text operation fails
1316 @see: L{getAccTextAttr}
1317 '''
1318 if end is None:
1319 end = start
1320 try:
1321 rv = IAccessibleAction(start).setAccTextAttrs(end, attrs)
1322 except LookupError:
1323 raise PORError
1324 except NotImplementedError:
1325
1326 return False
1327 else:
1328 if not rv:
1329
1330 raise TextError
1331 return True
1332
1334 '''
1335 Gets the text input caret L{AEPor} within the given accessible L{AEPor}.
1336
1337 @param por: A point of regard
1338 @type por: L{AEPor}
1339 @return: Point of regard to the text insertion caret
1340 @rtype: L{AEPor}
1341 @raise PORError: When the L{AEPor} is invalid
1342 '''
1343 try:
1344 return IAccessibleInfo(por).getAccCaret()
1345 except LookupError:
1346 raise PORError
1347 except NotImplementedError:
1348
1349 return None
1350
1352 '''
1353 Moves the text input caret to offset indicated by the given L{AEPor}.
1354
1355 @param por: A point of regard
1356 @type por: L{AEPor}
1357 @return: Is setting the caret supported?
1358 @rtype: boolean
1359 @raise PORError: When the L{AEPor} is invalid
1360 @raise CaretError: When moving the caret is supported but rejected by the
1361 system for some reason
1362 '''
1363 try:
1364 rv = IAccessibleAction(por).setAccCaret()
1365 except LookupError:
1366 raise PORError
1367 except NotImplementedError:
1368
1369 return False
1370 else:
1371 if not rv:
1372
1373 raise CaretError
1374 return True
1375
1376
1377
1378
1380 '''
1381 Gets the floating point value at the given L{AEPor}.
1382
1383 @param por: A point of regard
1384 @type por: L{AEPor}
1385 @return: Floating point value
1386 @rtype: float
1387 @raise PORError: When the L{AEPor} is invalid
1388 '''
1389 try:
1390 return IAccessibleInfo(por).getAccFloatValue()
1391 except LookupError:
1392 raise PORError
1393 except NotImplementedError:
1394 return None
1395
1397 '''
1398 Get the extents and step size of the floating point value at the L{AEPor}.
1399
1400 @param por: A point of regard
1401 @type por: L{AEPor}
1402 @return: The minimum possible value, the maximum possible value, and the
1403 step size for the floating point value
1404 @rtype: 3-tuple of float
1405 @raise PORError: When the L{AEPor} is invalid
1406 '''
1407 try:
1408 return IAccessibleInfo(por).getAccFloatValueExtents()
1409 except LookupError:
1410 raise PORError
1411 except NotImplementedError:
1412 return None
1413
1414
1415
1416
1418 '''
1419 Gets the index the L{AEPor} within some 1D ordered collection.
1420
1421 @param por: A point of regard
1422 @type por: L{AEPor}
1423 @return: Zero index of the item
1424 @rtype: integer
1425 @raise PORError: When the L{AEPor} is invalid
1426 '''
1427 try:
1428 return IAccessibleInfo(por).getAccIndex()
1429 except LookupError:
1430 raise PORError
1431 except NotImplementedError:
1432 return None
1433
1435 '''
1436 Gets the row index of the L{AEPor} within some 2D ordered collection.
1437
1438 @param por: A point of regard
1439 @type por: L{AEPor}
1440 @return: Zero indexed row of the item
1441 @rtype: integer
1442 @raise PORError: When the L{AEPor} is invalid
1443 '''
1444 try:
1445 return IAccessibleInfo(por).getAccRow()
1446 except LookupError:
1447 raise PORError
1448 except NotImplementedError:
1449 return None
1450
1452 '''
1453 Gets the column index of the L{AEPor} within some 2D ordered collection.
1454
1455 @param por: A point of regard
1456 @type por: L{AEPor}
1457 @return: Zero indexed column of the item
1458 @rtype: integer
1459 @raise PORError: When the L{AEPor} is invalid
1460 '''
1461 try:
1462 return IAccessibleInfo(por).getAccColumn()
1463 except LookupError:
1464 raise PORError
1465 except NotImplementedError:
1466 return None
1467
1469 '''
1470 Gets the L{AEPor} to the cell in the given L{AEPor} at the given row and
1471 column.
1472
1473 @param por: A point of regard
1474 @type por: L{AEPor}
1475 @param row: Row offset
1476 @type row: integer
1477 @param col: Column offset
1478 @type col: integer
1479 @return: Point of regard to the given row and column
1480 @rtype: L{AEPor}
1481 @raise PORError: When the L{AEPor} is invalid
1482 '''
1483 try:
1484 index = IAccessibleInfo(por).getAccRowColIndex(row, col)
1485 return POR(por.accessible, index)
1486 except LookupError:
1487 raise PORError
1488 except NotImplementedError:
1489 return None
1490
1492 '''
1493 Gets the text description of a row in a table.
1494
1495 @param por: A point of regard
1496 @type por: L{AEPor}
1497 @return: text description of the row, if there is one.
1498 @rtype: string
1499 @raise PORError: When the L{AEPor} is invalid
1500 '''
1501 try:
1502 return IAccessibleInfo(por).getAccRowHeader()
1503 except LookupError:
1504 raise PORError
1505 except NotImplementedError:
1506 return None
1507
1509 '''
1510 Gets the text description of a column in a table.
1511
1512 @param por: A point of regard
1513 @type por: L{AEPor}
1514 @return: text description of the column, if there is one.
1515 @rtype: string
1516 @raise PORError: When the L{AEPor} is invalid
1517 '''
1518 try:
1519 return IAccessibleInfo(por).getAccColumnHeader()
1520 except LookupError:
1521 raise PORError
1522 except NotImplementedError:
1523 return None
1524
1526 '''
1527 Gets the tree level of the item indicated by the given L{AEPor}.
1528
1529 @param por: A point of regard
1530 @type por: L{AEPor}
1531 @return: Zero indexed level of the item
1532 @rtype: integer
1533 @raise PORError: When the L{AEPor} is invalid
1534 '''
1535 try:
1536 return IAccessibleInfo(por).getAccLevel()
1537 except LookupError:
1538 raise PORError
1539 except NotImplementedError:
1540 return None
1541
1543 '''
1544 Returns the number of rows and columns in a table indicated by the given
1545 L{AEPor}.
1546
1547 @param por: A point of regard
1548 @type por: L{AEPor}
1549 @return: Count of rows and columns
1550 @rtype: 2-tuple of integer
1551 @raise PORError: When the L{AEPor} is invalid
1552 '''
1553 try:
1554 return IAccessibleInfo(por).getAccTableExtents()
1555 except LookupError:
1556 raise PORError
1557 except NotImplementedError:
1558 return None
1559
1560
1561
1562
1564 '''
1565 Gets the first selected items or accessible children in the accessible
1566 indicated by the given L{AEPor}.
1567
1568 @param por: A point of regard
1569 @type por: L{AEPor}
1570 @return: Point of regard to the first selected item or accessible
1571 @rtype: L{AEPor}
1572 @raise PORError: When the L{AEPor} is invalid
1573 '''
1574 all = getAllSelected(por)
1575 try:
1576 return all[0]
1577 except TypeError:
1578 return None
1579
1581 '''
1582 Gets all of the selected items or accessible children in the accessible
1583 indicated by the given L{AEPor}.
1584
1585 @param por: A point of regard
1586 @type por: L{AEPor}
1587 @return: Points of regard to selected items or accessibles
1588 @rtype: list of L{AEPor}
1589 @raise PORError: When the L{AEPor} is invalid
1590 '''
1591 try:
1592 return IAccessibleInfo(por).getAccSelection()
1593 except LookupError:
1594 raise PORError
1595 except NotImplementedError:
1596 return None
1597
1599 '''
1600 Selects all of the items or accessible children in the accessible indicated
1601 by the given L{AEPor}.
1602
1603 @param por: A point of regard
1604 @type por: L{AEPor}
1605 @return: Is setting the focus supported?
1606 @rtype: boolean
1607 @raise PORError: When the L{AEPor} is invalid
1608 @raise SelectError: When selecting is supported but rejected by the system
1609 for some reason
1610 '''
1611 try:
1612 rv = IAccessibleAction(por).selectAcc(all=True)
1613 except LookupError:
1614 raise PORError
1615 except NotImplementedError:
1616
1617 return False
1618 else:
1619 if not rv:
1620
1621 raise SelectError
1622 return True
1623
1625 '''
1626 Deselects all of the items or accessible children in the accessible
1627 indicated by the given L{AEPor}.
1628
1629 @param por: A point of regard
1630 @type por: L{AEPor}
1631 @return: Is setting the focus supported?
1632 @rtype: boolean
1633 @raise PORError: When the L{AEPor} is invalid
1634 @raise SelectError: When deselecting is supported but rejected by the
1635 system for some reason
1636 '''
1637 try:
1638 rv = IAccessibleAction(por).deselectAcc(True)
1639 except LookupError:
1640 raise PORError
1641 except NotImplementedError:
1642
1643 return False
1644 else:
1645 if not rv:
1646
1647 raise SelectError
1648 return True
1649
1651 '''
1652 Selects the item or accessible indicated by the given L{AEPor}.
1653
1654 @param por: A point of regard
1655 @type por: L{AEPor}
1656 @return: Is setting the selection supported?
1657 @rtype: boolean
1658 @raise PORError: When the L{AEPor} is invalid
1659 @raise SelectError: When selecting the L{AEPor} is supported but rejected by
1660 the system for some reason
1661 '''
1662 try:
1663 rv = IAccessibleAction(por).selectAcc(False)
1664 except LookupError:
1665 raise PORError
1666 except NotImplementedError:
1667
1668 return False
1669 else:
1670 if not rv:
1671
1672 raise SelectError
1673 return True
1674
1676 '''
1677 Deselects the item or accessible indicated by the given L{AEPor}.
1678
1679 @param por: A point of regard
1680 @type por: L{AEPor}
1681 @return: Is setting the selection supported?
1682 @rtype: boolean
1683 @raise PORError: When the L{AEPor} is invalid
1684 @raise SelectError: When deselecting the L{AEPor} is supported but rejected
1685 by the system for some reason
1686 '''
1687 try:
1688 rv = IAccessibleAction(por).deselectAcc(False)
1689 except LookupError:
1690 raise PORError
1691 except NotImplementedError:
1692
1693 return False
1694 else:
1695 if not rv:
1696
1697 raise SelectError
1698 return True
1699
1700
1701
1702
1704 '''
1705 Gets a L{AEPor} to the top level container of the given L{AEPor}.
1706
1707 @param por: A point of regard
1708 @type por: L{AEPor}
1709 @return: A point of regard to the root accessible
1710 @rtype: L{AEPor}
1711 @raise PORError: When the provided L{AEPor} is invalid
1712 '''
1713 try:
1714 return AccessibleWalker(por).getFirstPOR()
1715 except NotImplementedError:
1716 return None
1717
1719 '''
1720 Gets a L{AEPor} to the last item of the last accessible under the root of the
1721 view.
1722
1723 @param por: A point of regard
1724 @type por: L{AEPor}
1725 @return: A point of regard to the last accessible under the root POR
1726 @rtype: L{AEPor}
1727 @raise PORError: When the L{AEPor} is invalid
1728 '''
1729 try:
1730 por = AccessibleItemWalker(por).getLastPOR()
1731 except NotImplementedError:
1732
1733 raise PORError
1734 if por is None:
1735
1736 raise PORError
1737 else:
1738 return por
1739
1741 '''
1742 Gets a L{AEPor} indicating the root of the active view. This is more
1743 efficient than L{getRootAcc} when the root of the I{active} view is needed.
1744
1745 @return: A point of regard to the root accessible
1746 @rtype: L{AEPor}
1747 '''
1748 return AccessEngine.AEViewManager.getAEView()
1749
1751 '''
1752 Gets a L{AEPor} to the last item of the last accessible under the given root.
1753
1754 @param por: A point of regard
1755 @type por: L{AEPor}
1756 @return: A point of regard to the last accessible under the given POR
1757 @rtype: L{AEPor}
1758 @raise PORError: When the L{AEPor} is invalid
1759 '''
1760 while 1:
1761 try:
1762 por = IAccessibleNav(por).getLastAccChild()
1763 except NotImplementedError:
1764
1765 raise PORError
1766 except LookupError:
1767 old = por
1768 try:
1769
1770 por = IItemNav(por).getLastItem(False)
1771 except LookupError:
1772 pass
1773 if por == old:
1774
1775 return por
1776
1778 '''
1779 Gets a L{AEPor} representing the accessible found by treating the path
1780 integers as descendant indices stating at the given L{AEPor}.
1781
1782 @param por: A point of regard
1783 @type por: L{AEPor}
1784 @param path: Integers indicate the path to the desired object
1785 @type path: integer
1786 @return: Point of regard for the descendant at the specified path
1787 @rtype: L{AEPor}
1788 '''
1789 try:
1790
1791 child_por = IAccessibleNav(por).getChildAcc(path[0])
1792 except (IndexError, LookupError):
1793 return None
1794
1795 path = path[1:]
1796 if not len(path):
1797 return child_por
1798
1799 por_from_path = getAccFromPath(child_por, *path)
1800 return por_from_path
1801
1802
1804 '''
1805 Gets the L{AEPor} of the first character and first item of the parent of the
1806 provided L{AEPor}.
1807
1808 @param por: A point of regard
1809 @type por: L{AEPor}
1810 @return: Point of regard for the parent
1811 @rtype: L{AEPor}
1812 '''
1813 try:
1814 return IAccessibleNav(por).getParentAcc()
1815 except (NotImplementedError, LookupError):
1816 return None
1817
1819 '''
1820 Gets the child accessible at the given index from the L{AEPor}.
1821
1822 @param index: Child index to retrieve
1823 @type index: integer
1824 @param por: A point of regard
1825 @type por: L{AEPor}
1826 @return: Point of regard to the child at the index or None if it does not
1827 exist
1828 @rtype: L{AEPor}
1829 '''
1830 try:
1831 return IAccessibleNav(por).getChildAcc(index)
1832 except (IndexError, LookupError):
1833 return None
1834
1836 '''
1837 Gets the L{AEPor} of the previous accessible of a given L{AEPor}.
1838
1839 @param por: A point of regard
1840 @type por: L{AEPor}
1841 @return: Point of regard to the previous accessible or None if not found
1842 @rtype: L{AEPor}
1843 '''
1844 try:
1845 return AccessibleWalker(por).getPrevPOR()
1846 except NotImplementedError:
1847 return None
1848
1850 '''
1851 Gets the L{AEPor} of the next accessible of a given L{AEPor} in the
1852 L{AccessibleWalker} order.
1853
1854 @param por: A point of regard
1855 @type por: L{AEPor}
1856 @return: Point of regard to the next accessible
1857 @rtype: L{AEPor}
1858 '''
1859 try:
1860 return AccessibleWalker(por).getNextPOR()
1861 except NotImplementedError:
1862 return None
1863
1864
1865
1867 '''
1868 Gets the L{AEPor} of the first accessible peer of a given L{AEPor}.
1869
1870 @param por: A point of regard
1871 @type por: L{AEPor}
1872 @return: Point of regard to the first peer accessible
1873 @rtype: L{AEPor}
1874 '''
1875 try:
1876 p = IAccessibleNav(por).getParentAcc()
1877 return IAccessibleNav(p).getFirstAccChild()
1878 except (NotImplementedError, IndexError, LookupError):
1879 return None
1880
1882 '''
1883 Gets the L{AEPor} of the last accessible peer of a given L{AEPor}.
1884
1885 @param por: A point of regard
1886 @type por: L{AEPor}
1887 @return: Point of regard to the first peer accessible
1888 @rtype: L{AEPor}
1889 '''
1890 try:
1891 p = IAccessibleNav(por).getParentAcc()
1892 return IAccessibleNav(p).getLastAccChild()
1893 except (NotImplementedError, IndexError, LookupError):
1894 return None
1895
1897 '''
1898 Gets the L{AEPor} of the next accessible peer of a given L{AEPor}.
1899
1900 @param por: A point of regard
1901 @type por: L{AEPor}
1902 @return: Point of regard to the next peer accessible
1903 @rtype: L{AEPor}
1904 '''
1905 try:
1906 return IAccessibleNav(por).getNextAcc()
1907 except (IndexError, NotImplementedError, LookupError):
1908 return None
1909
1911 '''
1912 Gets the L{AEPor} of the previous accessible peer of a given L{AEPor}.
1913
1914 @param por: A point of regard
1915 @type por: L{AEPor}
1916 @return: Point of regard to the next peer accessible
1917 @rtype: L{AEPor}
1918 '''
1919 try:
1920 return IAccessibleNav(por).getPrevAcc()
1921 except (IndexError, NotImplementedError, LookupError):
1922 return None
1923
1924
1926 '''
1927 Gets the L{AEPor} of the start of the item.
1928
1929 @param por: A point of regard
1930 @type por: L{AEPor}
1931 @return: Point of regard to the first character in the item or None if not
1932 found
1933 @rtype: L{AEPor}
1934 '''
1935 return AEPor(por.accessible, por.item_offset, 0)
1936
1938 '''
1939 Gets the L{AEPor} of the next item in the given L{AEPor}.
1940
1941 @param por: A point of regard
1942 @type por: L{AEPor}
1943 @param wrap: Consider a next item outside this accessible if there is no
1944 next item in this accessible? Defaults to False.
1945 @type wrap: boolean
1946 @param only_visible: Only consider visible items? Defaults to False.
1947 @type only_visible: boolean
1948 @return: Point of regard to the previous item or None if not found
1949 @rtype: L{AEPor}
1950 '''
1951 try:
1952 next_por = AccessibleItemWalker(por, only_visible=only_visible).getNextPOR()
1953 except NotImplementedError:
1954 return None
1955 if wrap:
1956
1957 return next_por
1958 elif next_por is not None and not next_por.isSameAcc(por):
1959
1960 return None
1961 return next_por
1962
1964 '''
1965 Gets the L{AEPor} of the previous item in the given L{AEPor}.
1966
1967 @param por: A point of regard
1968 @type por: L{AEPor}
1969 @param wrap: Consider a previous item outside this accessible if there is
1970 no previous item in this accessible? Defaults to False.
1971 @type wrap: boolean
1972 @param only_visible: Only consider visible items? Defaults to False.
1973 @type only_visible: boolean
1974 @return: Point of regard to the previous item or None if not found
1975 @rtype: L{AEPor}
1976 '''
1977 try:
1978 prev_por = AccessibleItemWalker(por, only_visible=only_visible).getPrevPOR()
1979 except NotImplementedError:
1980 return None
1981 if wrap:
1982
1983 return prev_por
1984 elif not prev_por.isSameAcc(por):
1985
1986 return None
1987 return prev_por
1988
1989
1991 '''
1992 Get the L{AEPor} of the current word in the item indicated by the given L{AEPor}
1993
1994 @param por: A point of regard
1995 @type por: L{AEPor}
1996 @return: Point of regard to the start of the current word or None if not
1997 found
1998 @rtype: L{AEPor}
1999 '''
2000
2001 try:
2002 text = IAccessibleInfo(por).getAccItemText()
2003 except (LookupError, NotImplementedError):
2004 return None
2005
2006 prev, curr, next = Word.getContextFromString(text, por)
2007 return curr.getPOR()
2008
2010 '''
2011 Get the L{AEPor} of the next word in the item indicated by the given L{AEPor}.
2012
2013 @param por: A point of regard
2014 @type por: L{AEPor}
2015 @return: Point of regard to the next word or None if not found
2016 @rtype: L{AEPor}
2017 '''
2018
2019 try:
2020 text = IAccessibleInfo(por).getAccItemText()
2021 except (LookupError, NotImplementedError):
2022 return None
2023
2024 prev, curr, next = Word.getContextFromString(text, por)
2025 if next is not None:
2026
2027 return next.getPOR()
2028 else:
2029 return None
2030
2032 '''
2033 Get the L{AEPor} of the previous word in the item indicated by the given
2034 L{AEPor}.
2035
2036 @param por: A point of regard
2037 @type por: L{AEPor}
2038 @return: Point of regard to the previous word or None if not found
2039 @rtype: L{AEPor}
2040 '''
2041
2042
2043 try:
2044 text = IAccessibleInfo(por).getAccItemText()
2045 except (LookupError, NotImplementedError):
2046 return None
2047
2048 prev, curr, next = Word.getContextFromString(text, por)
2049 if prev is not None:
2050
2051 return prev.getPOR()
2052 else:
2053 return None
2054
2056 '''
2057 Get the L{AEPor} of the current word in the item indicated by the given
2058 L{AEPor}.
2059
2060 @param por: A point of regard
2061 @type por: L{AEPor}
2062 @return: Point of regard to the start of the last word or None if not found
2063 @rtype: L{AEPor}
2064 '''
2065
2066 try:
2067 text = IAccessibleInfo(por).getAccItemText()
2068 except (LookupError, NotImplementedError):
2069 return None
2070
2071 words = Word.buildWordsFromString(text, por)
2072 try:
2073
2074 return words[-1].getPOR()
2075 except IndexError:
2076
2077 return por
2078
2079
2081 '''
2082 Get the L{AEPor} of the next character in the item indicated by the given
2083
2084 @param por: A point of regard
2085 @type por: L{AEPor}
2086 @return: Point of regard to the next character or None if not found
2087 @rtype: L{AEPor}
2088 '''
2089 try:
2090
2091 text = IAccessibleInfo(por).getAccItemText()
2092 except (LookupError, NotImplementedError):
2093 return None
2094 if por.char_offset < len(text)-1:
2095 return AEPor(por.accessible, por.item_offset, por.char_offset+1)
2096 else:
2097 return None
2098
2100 '''
2101 Get the L{AEPor} of the previous character in the item indicated by the given
2102 L{AEPor}.
2103
2104 @param por: A point of regard
2105 @type por: L{AEPor}
2106 @return: Point of regard to the previous character or None if not found
2107 @rtype: L{AEPor}
2108 '''
2109 if por.char_offset > 0:
2110 return AEPor(por.accessible, por.item_offset, por.char_offset-1)
2111 else:
2112 return None
2113
2115 '''
2116 Get the L{AEPor} of the last character in the item indicated by the given
2117 L{AEPor}.
2118
2119 @param por: A point of regard
2120 @type por: L{AEPor}
2121 @return: Point of regard to the last character or None if not found
2122 @rtype: L{AEPor}
2123 '''
2124 try:
2125
2126 text = IAccessibleInfo(por).getAccItemText()
2127 except (LookupError, NotImplementedError):
2128 return None
2129 if len(text) == 0:
2130 return AEPor(por.accessible, por.item_offset, 0)
2131 else:
2132 return AEPor(por.accessible, por.item_offset, len(text)-1)
2133
2134
2136 '''
2137 Gets the L{AEPor} to the cell in the first column of the row containing the
2138 item indicated by the given L{AEPor}.
2139
2140 @param por: A point of regard
2141 @type por: L{AEPor}
2142 @return: Point of regard to the first column of the given row
2143 @rtype: L{AEPor}
2144 '''
2145 try:
2146 ai = IAccessibleInfo(por)
2147
2148 index = ai.getAccRowColIndex(ai.getAccRow(), 0)
2149 return AEPor(por.accessible, index)
2150 except (LookupError, NotImplementedError):
2151 return None
2152
2154 '''
2155 Get the L{AEPor} of the first column of the next row relative to the row
2156 containing the item indicated by the given L{AEPor}.
2157
2158 @param por: A point of regard
2159 @type por: L{AEPor}
2160 @return: Point of regard to the start of the next row or None if not found
2161 @rtype: L{AEPor}
2162 '''
2163 try:
2164 ai = IAccessibleInfo(por)
2165
2166 index = ai.getAccRowColIndex(ai.getAccRow()+1, 0)
2167 return AEPor(por.accessible, index)
2168 except (LookupError, NotImplementedError):
2169 return None
2170
2171
2173 '''
2174 Get the L{AEPor} of the first column of the previous row relative to the row
2175 containing the item indicated by the given L{AEPor}.
2176
2177 @param por: A point of regard
2178 @type por: L{AEPor}
2179 @return: Point of regard to the start of the previous row or None if not
2180 found
2181 @rtype: L{AEPor}
2182 '''
2183 try:
2184 ai = IAccessibleInfo(por)
2185
2186 index = ai.getAccRowColIndex(ai.getAccRow()+1, 0)
2187 return AEPor(por.accessible, index)
2188 except (LookupError, NotImplementedError):
2189 return None
2190
2191
2193 '''
2194 From a given L{AEPor}, get the L{AEPor} of the start of the first line that
2195 follows the previous hard line break, or the start of the first line if it
2196 is the first line in the accessible.
2197
2198 @param por: Point of regard
2199 @type por: L{AEPor}
2200 @return: Point of regard to the previous character or None if not found
2201 @rtype: L{AEPor}
2202 @raise PORError: When some L{AEPor} is invalid
2203 '''
2204 try:
2205 prev = getPrevItem(por)
2206 while prev is not None and prev.item_offset is not None:
2207 prevText = getItemText(prev)
2208 if prevText.endswith('\n'):
2209 break
2210 por = prev
2211 prev = getPrevItem(por)
2212 return AEPor(por.accessible, por.item_offset, 0)
2213 except (LookupError, PORError):
2214
2215 raise PORError
2216
2218 '''
2219 From a given L{AEPor}, get the L{AEPor} of the end of the first following line
2220 that ends with a hard line break, or the end of the last line if it is the
2221 last line in the accessible.
2222
2223 @param por: Point of regard
2224 @type por: L{AEPor}
2225 @return: Point of regard to the previous character or None if not found
2226 @rtype: L{AEPor}
2227 @raise PORError: When some L{AEPor} is invalid
2228 '''
2229 try:
2230 next = getNextItem(por)
2231 text = getItemText(por)
2232 while next is not None:
2233 if text.endswith('\n'):
2234 break
2235 text = getItemText(next)
2236 por = next
2237 next = getNextItem(por)
2238 if next is None:
2239
2240 return AEPor(por.accessible, por.item_offset, len(text))
2241 else:
2242 return AEPor(por.accessible, por.item_offset, len(text)-1)
2243 except (LookupError, PORError):
2244
2245 raise PORError
2246
2247
2248
2249
2251 '''
2252 Builds an iterator over the ancestors of the current L{AEPor}.
2253
2254 @param por: A point of regard
2255 @type por: L{AEPor}
2256 @param only_visible: Yield on visible L{AEPor}s only?
2257 @type only_visible: boolean
2258 @param allow_trivial: Yield on trivial L{AEPor}s too?
2259 @type allow_trivial: boolean
2260 @return: Point of regard to an ancestor
2261 @rtype: L{AEPor}
2262 '''
2263 w = AccessibleItemWalker(por, only_visible, allow_trivial)
2264 try:
2265 por = w.getParentPOR()
2266 except NotImplementedError:
2267 return
2268 while por is not None:
2269 yield por
2270 try:
2271 por = w.getParentPOR()
2272 except NotImplementedError:
2273 return
2274
2276 '''
2277 Builds an iterator over the accessibles next to the current L{AEPor}.
2278
2279 @param por: A point of regard
2280 @type por: L{AEPor}
2281 @return: Point of regard to the previous accessible
2282 @rtype: L{AEPor}
2283 '''
2284 while por is not None:
2285 yield por
2286 por = getNextAcc(por)
2287
2289 '''
2290 Builds an iterator over the accessibles previous to the current L{AEPor}.
2291
2292 @param por: A point of regard
2293 @type por: L{AEPor}
2294 @return: Point of regard to the previous accessible
2295 @rtype: L{AEPor}
2296 '''
2297 while por is not None:
2298 yield por
2299 por = getPrevAcc(por)
2300
2302 '''
2303 Builds an iterator over the items next to the current L{AEPor}.
2304
2305 @param por: A point of regard
2306 @type por: L{AEPor}
2307 @param wrap: Consider a next item outside this accessible if there is
2308 no next item in this accessible? Defaults to False.
2309 @type wrap: boolean
2310 @param only_visible: Only consider visible items? Defaults to False.
2311 @type only_visible: boolean
2312 @return: Point of regard to the next item
2313 @rtype: L{AEPor}
2314 '''
2315 por = getNextItem(por, wrap, only_visible)
2316 while por is not None:
2317 yield por
2318 por = getNextItem(por, wrap, only_visible)
2319
2321 '''
2322 Builds an iterator over the items previous to the current L{AEPor}.
2323
2324 @param por: A point of regard
2325 @type por: L{AEPor}
2326 @param wrap: Consider a previous item outside this accessible if there is
2327 no previous item in this accessible? Defaults to False.
2328 @type wrap: boolean
2329 @param only_visible: Only consider visible items? Defaults to False.
2330 @type only_visible: boolean
2331 @return: Point of regard to the previous item
2332 @rtype: L{AEPor}
2333 '''
2334 por = getPrevItem(por, wrap, only_visible)
2335 while por is not None:
2336 yield por
2337 por = getPrevItem(por, wrap, only_visible)
2338
2339
2340
2341
2343 '''
2344 Gets a L{AEPor} to the first accessible descendant or ancestor of the given
2345 L{AEPor} with the given name.
2346
2347 @param name: Name of the accessible to locate
2348 @type name: string
2349 @param por: A point of regard
2350 @type por: L{AEPor}
2351 @param ancestor: Search through ancestors (True) or descendants (False)?
2352 @type ancestor: boolean
2353 @param depth_first: Is the search depth-first (True) or breadth-first
2354 (False)? Only meaningful when ancestor is False.
2355 @type depth_first: boolean
2356 @return: Point of regard to the target if found or None if not
2357 @rtype: L{AEPor}
2358 '''
2359 pred = lambda por: IAccessibleInfo(por).getAccName() == name
2360 return findAccByPredicate(pred, por, ancestor)
2361
2363 '''
2364 Gets a L{AEPor} to the first accessible descendant or ancestor of the given
2365 L{AEPor} with the given role.
2366
2367 @param role: Role of the accessible to locate
2368 @type role: string
2369 @param por: A point of regard
2370 @type por: L{AEPor}
2371 @param ancestor: Search through ancestors (True) or descendants (False)?
2372 @type ancestor: boolean
2373 @param depth_first: Is the search depth-first (True) or breadth-first
2374 (False)? Only meaningful when ancestor is False.
2375 @type depth_first: boolean
2376 @return: Point of regard to the target if found or None if not
2377 @rtype: L{AEPor}
2378 '''
2379 pred = lambda por: IAccessibleInfo(por).hasAccRole(role)
2380 return findAccByPredicate(pred, por, ancestor)
2381
2383 '''
2384 Gets a L{AEPor} to the first accessible descendant or ancestor of the given
2385 L{AEPor} with the given 'id' attribute named objname.
2386
2387 @param objname: Object id name to search
2388 @type objname: string
2389 @param por: A point of regard
2390 @type por: L{AEPor}
2391 @param ancestor: Search through ancestors (True) or descendants (False)?
2392 @type ancestor: boolean
2393 @param depth_first: Is the search depth-first (True) or breadth-first
2394 (False)? Only meaningful when ancestor is False.
2395 @type depth_first: boolean
2396 @return: Point of regard to the target if found or None if not
2397 @rtype: L{AEPor}
2398 '''
2399 pred = lambda por: getAccAttrs(por)['id'] == objname
2400 return findAccByPredicate(pred, por, ancestor)
2401
2403 '''
2404 Gets a L{AEPor} to the first accessible descendant or ancestor of the given
2405 L{AEPor} matching the given callable predicate.
2406
2407 @warning: This method should be considered unstable and likely to change in
2408 future versions of SUE
2409
2410 @param predicate: Search predicate that evaluates to True or False
2411 @type predicate: callable
2412 @param por: A point of regard
2413 @type por: L{AEPor}
2414 @param ancestor: Search through ancestors (True) or descendants (False)?
2415 @type ancestor: boolean
2416 @param depth_first: Is the search depth-first (True) or breadth-first
2417 (False)? Only meaningful when ancestor is False.
2418 @type depth_first: boolean
2419 @return: Point of regard to the target if found or None if not
2420 @rtype: L{AEPor}
2421 '''
2422 try:
2423 ai = IAccessibleNav(por)
2424 if ancestor:
2425 return ai.findAncestorAcc(predicate)
2426 else:
2427 return ai.findDescendantAcc(predicate, depth_first)
2428 except NotImplementedError:
2429 return None
2430 except LookupError:
2431 raise PORError
2432
2433
2434
2435
2437 '''
2438 Triggers a mouse event at the center of the given point of regard or - in
2439 case of a text accessible - set the caret to the given position (e.g. in
2440 response to HandleTouchCursor in BasicBraillePerk)
2441
2442 @param event: Mouse event, one of EVENT_SYNTHMOUSE_* in L{AEConstants}
2443 @type event: string
2444 @param por: Point of regard
2445 @type por: L{AEPor}
2446 @return: Is the action supported?
2447 @rtype: boolean
2448 @raise PORError: When the L{AEPor} is invalid
2449 @raise MouseError: When the mouse operation fails
2450 '''
2451 try:
2452 rv = IAccessibleAction(por).doMouseAction(event)
2453 except LookupError:
2454 raise PORError
2455 except NotImplementedError:
2456
2457 return False
2458 else:
2459 if not rv:
2460
2461 raise MouseError
2462 return True
2463
2465 '''
2466 Performs a mouse left click on the center of a given point of regard.
2467
2468 @param por: Point of regard
2469 @type por: L{AEPor}
2470 @return: Did the click succeed?
2471 @rtype: boolean
2472 @raise PORError: When the L{AEPor} is invalid
2473 @raise MouseError: When the mouse click fails
2474 '''
2475
2476 return mouseEventPOR(AEConstants.EVENT_SYNTHMOUSE_B1C, por)
2477