Source Code for Module AccessEngine.AEPor

  1  ''' 
  2  Defines a class for storing point-of-regard information. 
  3   
  4  @author: Peter Parente 
  5  @organization: IBM Corporation 
  6  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  7  @license: The BSD License 
  8   
  9  @author: Frank Zenker 
 10  @organization: IT Science Center Ruegen gGmbH, Germany 
 11  @copyright: Copyright (c) 2007, 2008 ITSC Ruegen 
 12  @license: The BSD License 
 13   
 14  All rights reserved. This program and the accompanying materials are made  
 15  available under the terms of the BSD license which accompanies 
 16  this distribution, and is available at 
 17  U{http://www.opensource.org/licenses/bsd-license.php} 
 18  ''' 
 19 -class AEPor(object): 
 20    ''' 
 21    Stores point-of-regard data for accessibles, the user, a L{AETier}'s focus, etc. 
 22     
 23    @ivar accessible: The accessible of the control which has the point of regard. 
 24    @type accessible: C{pyatspi.Accessibility.Accessible} 
 25    @ivar item_offset: Offset of the Item within the accessible which has the 
 26      point of regard. Set to None to indicate the accessible has only 1 item. 
 27      When restricting to visible, this offset will still be relative to total.  
 28      For example, when the first item in a table is not visible, but the first  
 29      item is requested, this index will not be 0 (the first in the table), but  
 30      instead will be the index of the first visible cell. For text, this will  
 31      be the character index of the first character in the line requested (i.e.  
 32      the first visible line in the example above). 
 33    @type item_offset: integer or None 
 34    @ivar char_offset: Offset of the character at the caret or virtual cursor 
 35      within the accessible and the item which has the point of regard. 
 36    @type char_offset: integer   
 37    @ivar incomplete: Indicates that a L{AEPor} might need additional processing 
 38      before it is used when True. Some L{AEAccInterfaces.IEventHandler} may create 
 39      L{AEPor}s that have an item in the L{accessible} slot instead of its parent as 
 40      the L{accessible} and its index as the L{item_offset} in order to save time 
 41      for events that may never be handled. This flag indicates this situation and 
 42      suggests that the L{AEPor} be corrected properly before it reaches a L{AEScript <AEScript.AEScript>} 
 43      and its tasks for processing.  
 44    @type incomplete: boolean 
 45    @ivar adapters: Cached adapters for L{AEAccInterfaces} for this L{AEPor} 
 46    @type adapters: dictionary 
 47   
 48    @note: This class is a structure and based on the SUE coding conventions its 
 49      members (except for the adapters dictionary) can be accessed directly.  
 50    ''' 
 51 -  def __init__(self, accessible=None, item_offset=None, char_offset=0, 
 52                 incomplete=False): 
 53      ''' 
 54      Stores the provided accessible, offset to an item within the accessible, and 
 55      offset to a character within the accessible. 
 56       
 57      @param accessible: Accessible of the control which has the point of regard. 
 58      @type accessible: C{pyatspi.Accessibility.Accessible} 
 59      @param item_offset: Offset of the Item within the accessible which has the 
 60        point of regard. Set to None to indicate the accessible has only 1 item. 
 61        When restricting to visible, this offset will still be relative to total.  
 62        For example, when the first item in a table is not visble, but the first  
 63        item is requested, this index will not be 0 (the first in the table), but  
 64        instead will be the index of the first visible cell. For text, this will  
 65        be the character index of the first character in the line requested (i.e.  
 66        the first visible line in the example above). 
 67      @type item_offset: integer or None 
 68      @param char_offset: Offset of the character at the caret or virtual cursor 
 69        within the accessible which has the point of regard. 
 70      @type char_offset: integer 
 71      @param incomplete: Indicates that a L{AEPor} might need additional processing 
 72        before it is used when True. Some L{AEAccInterfaces.IEventHandler} may  
 73        create L{AEPor}s that have an item in the L{accessible} slot instead of 
 74        its parent as the L{accessible} and its index as the L{item_offset} in 
 75        order to save time for events that may never be handled. This flag  
 76        indicates this situation and suggests that the L{AEPor} be corrected 
 77        properly before it reaches a L{AEScript <AEScript.AEScript>} and its tasks for processing. 
 78      @type incomplete: boolean 
 79      ''' 
 80      self.accessible = accessible 
 81      self.item_offset = item_offset 
 82      self.char_offset = char_offset 
 83      self.incomplete = incomplete 
 84      self.adapters = {} 
 85       
 86 -  def getAdapter(self, interface): 
 87      ''' 
 88      Gets a cached instead of an adapter for this L{AEPor} to one of the  
 89      L{AEAccInterfaces}. 
 90       
 91      @param interface: Interface serving as the key for the cache 
 92      @type interface: L{AEAccAdapter.Interface} class 
 93      ''' 
 94      return self.adapters[interface] 
 95     
 96 -  def cacheAdapter(self, interface, adapter): 
 97      ''' 
 98      Caches an adapter instance that has been previously used for this L{AEPor} 
 99      to provide the given interface. 
100       
101      @param interface: Interface serving as the key for the cache 
102      @type interface: L{AEAccAdapter.Interface} class 
103      @param adapter: Adapter instance to cache 
104      @type adapter: L{AEAccAdapter.PORAdapter} 
105      ''' 
106      self.adapters[interface] = adapter 
107   
108 -  def __eq__(self, other): 
109      ''' 
110      Compares this L{AEPor} to the one provided based on all their properties. 
111       
112      @param other: Point of regard to compare 
113      @type other: L{AEPor} 
114      ''' 
115      try: 
116        return (self.item_offset == other.item_offset) and \ 
117               (self.char_offset == other.char_offset) and \ 
118               (self.accessible == other.accessible) 
119      except: 
120        return False 
121       
122 -  def __hash__(self): 
123      ''' 
124      Hashes based on the accessible, item offset, and character offset rather  
125      than the ID of the L{AEPor} itself. 
126       
127      @return: Immutable hash code based on the attributes of the L{AEPor} 
128      @rtype: integer 
129      ''' 
130      return hash(self.accessible)^(self.item_offset or 0)^(self.char_offset) 
131     
132 -  def __ne__(self, other): 
133      ''' 
134      Compares this L{AEPor} to the one provided based on all their properties. 
135       
136      @param other: Point of regard to compare 
137      @type other: L{AEPor} 
138      ''' 
139      return not self.__eq__(other) 
140     
141 -  def __str__(self): 
142      ''' 
143      Gets a string describing this AEPor (Por = Point of Regard) in terms of its  
144      L{accessible}, L{item_offset}, and L{char_offset} 
145       
146      @return: String representation 
147      @rtype: string 
148      ''' 
149      s = 'AEPor(%s, %s, %d)' % (self.accessible, self.item_offset,  
150                               self.char_offset) 
151      return s 
152     
153 -  def isSameChar(self, other): 
154      ''' 
155      Checks if the character offset in this L{AEPor} is the same as the one in the 
156      given L{AEPor}. 
157       
158      @param other: Point of regard with the character offset to compare 
159      @type other: L{AEPor} 
160      @return: Same character offset? 
161      @rtype: boolean 
162      ''' 
163      return self.char_offset == other.char_offset 
164     
165 -  def isSameItem(self, other): 
166      ''' 
167      Checks if the item offset in this L{AEPor} is the same as the one in the 
168      given L{AEPor}. 
169       
170      @param other: Point of regard with the item offset to compare 
171      @type other: L{AEPor} 
172      @return: Same item offset? 
173      @rtype: boolean 
174      ''' 
175      return self.item_offset == other.item_offset 
176     
177 -  def isSameAcc(self, other): 
178      ''' 
179      Checks if the accessible object in this L{AEPor} is the same as the one in the 
180      given L{AEPor}. 
181       
182      @param other: Point of regard with the accessible to compare 
183      @type other: L{AEPor} 
184      @return: Same accessible? 
185      @rtype: boolean 
186      ''' 
187      return self.accessible == other.accessible 
188     
189 -  def isCharAfter(self, other): 
190      ''' 
191      Checks if the character offset in this L{AEPor} is after the one in the given 
192      L{AEPor}. 
193       
194      @param other: Point of regard with the character offset to compare 
195      @type other: L{AEPor} 
196      @return: Character after the other? 
197      @rtype: boolean 
198      ''' 
199      return self.char_offset > other.char_offset 
200     
201 -  def isCharBefore(self, other): 
202      ''' 
203      Checks if the character offset in this L{AEPor} is before the one in the given 
204      L{AEPor}. 
205       
206      @param other: Point of regard with the character offset to compare 
207      @type other: L{AEPor} 
208      @return: Character before the other? 
209      @rtype: boolean 
210      ''' 
211      return self.char_offset < other.char_offset 
212    
213 -  def isItemBefore(self, other): 
214      ''' 
215      Checks if the item offset in this L{AEPor} is before the one in the given 
216      L{AEPor}. 
217       
218      @param other: Point of regard with the item offset to compare 
219      @type other: L{AEPor} 
220      @return: Item before the other? 
221      @rtype: boolean 
222      ''' 
223      return self.item_offset < other.item_offset 
224     
225 -  def isItemAfter(self, other): 
226      ''' 
227      Checks if the item offset in this L{AEPor} is after the one in the given 
228      L{AEPor}. 
229       
230      @param other: Point of regard with the item offset to compare 
231      @type other: L{AEPor} 
232      @return: Item after the other? 
233      @rtype: boolean 
234      ''' 
235      return self.item_offset > other.item_offset 
236