Source Code for Module AccessEngine.AEAccAdapters.ATSPI.DefaultNav

  1  ''' 
  2  Defines default L{AEAccAdapter.AEAccAdapter}s for the  
  3  L{AEAccInterfaces.IAccessibleNav} and L{AEAccInterfaces.IItemNav} interfaces on  
  4  L{AEPor.AEPor} objects. 
  5   
  6  @author: Peter Parente 
  7  @organization: IBM Corporation 
  8  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  9  @license: The BSD License 
 10   
 11  @author: Frank Zenker 
 12  @author: Ramona Bunk 
 13  @organization: IT Science Center Ruegen gGmbH, Germany 
 14  @copyright: Copyright (c) 2007, 2008 ITSC Ruegen 
 15  @license: The BSD License 
 16   
 17  All rights reserved. This program and the accompanying materials are made 
 18  available under the terms of the BSD license which accompanies 
 19  this distribution, and is available at 
 20  U{http://www.opensource.org/licenses/bsd-license.php} 
 21  ''' 
 22  from AccessEngine.AEPor import AEPor 
 23  from AccessEngine.AEAccAdapter import PORAdapter 
 24  from AccessEngine.AEAccInterfaces import * 
 25  import pyatspi 
 26   
 27 -class DefaultNavAdapter(PORAdapter): 
 28    '''   
 29    Adapts all AT-SPI accessibles to the L{IAccessibleNav} and L{IItemNav} 
 30    interfaces. No condition for adaptation is given implying that this adapter is 
 31    used as a default by L{AEAccAdapter} when no better adapter is available. Expects  
 32    the subject to be a L{AEPor}. 
 33    ''' 
 34    provides = [IAccessibleNav, IItemNav] 
 35     
 36 -  def getNextItem(self, only_visible=True):  
 37      ''' 
 38      Always raises IndexError as this default adapter assumes the subject has  
 39      only one item. 
 40       
 41      @param only_visible: True when Item in the returned L{AEPor} must be visible 
 42      @type only_visible: boolean 
 43      @return: Point of regard to the next item in the same accessible 
 44      @rtype: L{AEPor} 
 45      @raise IndexError: When there is no next item 
 46      ''' 
 47      raise IndexError 
 48       
 49 -  def getPrevItem(self, only_visible=True): 
 50      ''' 
 51      Always raises IndexError as this default adapter assumes the subject has  
 52      only one item. 
 53       
 54      @param only_visible: True when Item in the returned L{AEPor} must be visible 
 55      @type only_visible: boolean 
 56      @return: Point of regard to the previous item in the same accessible 
 57      @rtype: L{AEPor} 
 58      @raise IndexError: When there is no previous item 
 59      ''' 
 60      raise IndexError 
 61     
 62 -  def getFirstItem(self, only_visible=True): 
 63      '''     
 64      Gets a L{AEPor} pointing to the first item in the subject L{AEPor}. Ignores the 
 65      only visible flag. 
 66       
 67      @param only_visible: True when Item in the returned L{AEPor} must be visible 
 68      @type only_visible: boolean 
 69      @return: Point of regard to the first item in the same accessible 
 70      @rtype: L{AEPor} 
 71      @raise IndexError: When there is no first item 
 72      ''' 
 73      return AEPor(self.accessible, None, 0) 
 74     
 75 -  def getLastItem(self, only_visible=True): 
 76      ''' 
 77      Gets a L{AEPor} pointing to the first item in the subject L{AEPor} since it is 
 78      assumed to be the only item in this default adapter. Ignores the only 
 79      visible flag. 
 80       
 81      @param only_visible: True when Item in the returned L{AEPor} must be visible 
 82      @type only_visible: boolean 
 83      @return: Point of regard to the last item in the same accessible 
 84      @rtype: L{AEPor} 
 85      @raise IndexError: When there is no last item 
 86      ''' 
 87      return AEPor(self.accessible, None, 0) 
 88     
 89 -  def getAccAsItem(self, por): 
 90      ''' 
 91      Always raises IndexError as this default adapter assumes the subject has  
 92      only one item. 
 93       
 94      @param por: Point of regard to a child of the subject 
 95      @type por: L{AEPor} 
 96      @return: Point of regard to an item of the subject 
 97      @rtype: L{AEPor} 
 98      @raise IndexError: When there is no next item 
 99      ''' 
100      raise IndexError 
101     
102    
103 -  def getNextAcc(self): 
104      ''' 
105      Gets the next peer accessible object if possible and if it exists. 
106       
107      @return: Point of regard to the next accessible, or None if there is no next 
108        peer 
109      @rtype: L{AEPor} 
110      @raise IndexError: When there is no next accessible 
111      @raise LookupError: When lookup for the next accessible fails even though 
112        it may exist 
113      ''' 
114      acc = self.accessible 
115      # get the index of this accessible 
116      i = acc.getIndexInParent() 
117      has_parent = acc.parent is not None 
118      if i < 0 or not has_parent: 
119        # indicate lookup of the next peer failed 
120        raise LookupError 
121      # get the accessible at the next index (the peer) 
122      child = acc.parent.getChildAtIndex(i+1) 
123      if child is None: 
124        # indicate there is no next peer 
125        raise IndexError 
126      return AEPor(child, None, 0) 
127   
128    
129 -  def getPrevAcc(self): 
130      '''     
131      Gets the previous peer accessible object if possible and if it exists. 
132       
133      @return: Point of regard to the previous accessible 
134      @rtype: L{AEPor} 
135      @raise IndexError: When there is no previous accessible 
136      @raise LookupError: When lookup for the previous accessible fails even  
137        though it may exist 
138      ''' 
139      acc = self.accessible 
140      # get the index of this accessible 
141      i = acc.getIndexInParent() 
142      has_parent = acc.parent is not None 
143      if i <= 0 or not has_parent: 
144        # indicate lookup of the previous peer failed 
145        raise LookupError 
146      # get the accessible at the previous index (the peer) 
147      child = acc.parent.getChildAtIndex(i-1) 
148      if child is None: 
149        # indicate there is no previous peer 
150        raise IndexError 
151      return AEPor(child, None, 0) 
152   
153    
154 -  def getParentAcc(self): 
155      '''     
156      Gets the parent accessible object if possible and if it exists. 
157       
158      @return: Point of regard to the parent accessible 
159      @rtype: L{AEPor} 
160      @raise LookupError: When lookup for the parent accessible fails because it 
161        does not exist 
162      ''' 
163      # get the parent of this accessible 
164      parent = self.accessible.parent 
165      if parent is None: 
166        raise LookupError 
167      return AEPor(parent, None, 0) 
168     
169     
170 -  def getFirstAccChild(self): 
171      ''' 
172      Gets the first accessible child relative to the subject accessible. 
173       
174      @return: Point of regard to the first child accessible 
175      @rtype: L{AEPor} 
176      @raise LookupError: When lookup for child fails because it does not exist 
177      ''' 
178      child = self.accessible.getChildAtIndex(0) 
179      if child is None: 
180        raise LookupError 
181      return AEPor(child, None, 0) 
182   
183     
184 -  def getLastAccChild(self): 
185      ''' 
186      Gets the last accessible child relative to the subject accessible. 
187       
188      @return: Point of regard to the last child accessible 
189      @rtype: L{AEPor} 
190      @raise LookupError: When lookup for child fails because it does not exist 
191      ''' 
192      child = self.accessible.getChildAtIndex(self.accessible.childCount-1) 
193      if child is None: 
194        raise LookupError 
195      return AEPor(child, None, 0) 
196   
197      
198 -  def getChildAcc(self, index): 
199      ''' 
200      Gets the child accessible at the given index relative to the one providing 
201      this interface. 
202       
203      @param index: Index of the child to retrieve 
204      @type index: integer 
205      @return: Point of regard to the child accessible 
206      @rtype: L{AEPor} 
207      @raise IndexError: When there is no child at the given index 
208      @raise LookupError: When the lookup for the child fails even though it may 
209        exist 
210      ''' 
211      child = self.accessible.getChildAtIndex(index) 
212      if child is None: 
213        raise IndexError 
214      return AEPor(child, None, 0) 
215     
216    
217 -  def findDescendantAcc(self, predicate, depth_first): 
218      ''' 
219      Searches all descendants for one matching the given predicate. 
220       
221      @warning: The predicate is currently supplied with accessibles, not PORs. 
222      This behavior will likely change in the future. 
223       
224      @param predicate: Search predicate 
225      @type predicate: callable 
226      @param depth_first: Perform the search in depth-first (True) or breadth  
227        first (False) order? 
228      @type depth_first: boolean 
229      @return: Point of regard to the target or None if not found 
230      @rtype: L{AEPor} 
231      @raise LookupError: When the lookup fails during the search 
232      ''' 
233      # define our own predicate which will create PORs 
234      def por_predicate(acc): 
235        if acc is not None: 
236          por = IPORFactory(acc).create() 
237          return predicate(por) 
238        return False 
239      acc = pyatspi.utils.findDescendant(self.accessible, por_predicate, not depth_first) # NIC: test 
240      if acc is not None: 
241        acc = IPORFactory(acc).create() 
242      return acc 
243     
244    
245 -  def findAncestorAcc(self, predicate): 
246      ''' 
247      Searches all ancestors for one matching the given predicate. 
248       
249      @warning: The predicate is currently supplied with accessibles, not PORs. 
250      This behavior will likely change in the future. 
251       
252      @param predicate: Search predicate 
253      @type predicate: callable 
254      @return: Point of regard to the target or None if not found 
255      @rtype: L{AEPor} 
256      @raise LookupError: When the lookup fails during the search 
257      ''' 
258      # define our own predicate which will create PORs 
259      def por_predicate(acc): 
260        if acc is not None: 
261          por = IPORFactory(acc).create() 
262          return predicate(por) 
263        return False 
264      acc = pyatspi.utils.findAncestor(self.accessible, por_predicate) 
265      if acc is not None: 
266        acc = IPORFactory(acc).create() 
267      return acc 
268     
269 -  def getApplicationAcc(self): 
270      ''' 
271      Return the L{AEPor} to the root accessible of the current application. 
272       
273      @rtype: L{AEPor} 
274      ''' 
275      return AEPor(self.accessible.getApplication()) 
276