Source Code for Module treeInterceptorHandler

  1  #treeInterceptorHandler.py 
  2  #A part of NonVisual Desktop Access (NVDA) 
  3  #This file is covered by the GNU General Public License. 
  4  #See the file COPYING for more details. 
  5  #Copyright (C) 2006-2010 Michael Curran <mick@kulgan.net>, James Teh <jamie@jantrid.net> 
  6   
  7  from logHandler import log 
  8  import baseObject 
  9  import api 
 10  import config 
 11  import braille 
 12   
 13  runningTable=set() 
 14   
 15 -def getTreeInterceptor(obj): 
 16          for ti in runningTable: 
 17                  if obj in ti: 
 18                          return ti 
 19   
 20 -def update(obj): 
 21          #Don't create treeInterceptors in self voicing apps 
 22          if obj.appModule and obj.appModule.sleepMode: 
 23                  return None 
 24          #If this object already has a treeInterceptor, just return that and don't bother trying to create one 
 25          ti=obj.treeInterceptor 
 26          if not ti: 
 27                  try: 
 28                          newClass=obj.treeInterceptorClass 
 29                  except NotImplementedError: 
 30                          return None 
 31                  ti=newClass(obj) 
 32                  if not ti.isAlive: 
 33                          return None 
 34                  runningTable.add(ti) 
 35                  log.debug("Adding new treeInterceptor to runningTable: %s"%ti) 
 36          if ti.shouldPrepare: 
 37                  ti.prepare() 
 38          return ti 
 39   
 40 -def cleanup(): 
 41          """Kills off any treeInterceptors that are no longer alive.""" 
 42          for ti in list(runningTable): 
 43                  if not ti.isAlive: 
 44                          killTreeInterceptor(ti) 
 45   
 46 -def killTreeInterceptor(treeInterceptorObject): 
 47          try: 
 48                  runningTable.remove(treeInterceptorObject) 
 49          except KeyError: 
 50                  return 
 51          treeInterceptorObject.terminate() 
 52          log.debug("Killed treeInterceptor: %s" % treeInterceptorObject) 
 53   
 54 -def terminate(): 
 55          """Kills any currently running treeInterceptors""" 
 56          for ti in list(runningTable): 
 57                  killTreeInterceptor(ti) 
 58   
 59 -class TreeInterceptor(baseObject.ScriptableObject): 
 60          """Intercepts events and scripts for a tree of NVDAObjects. 
 61          When an NVDAObject is encompassed by this interceptor (i.e. it is beneath the root object or it is the root object itself), 
 62          events will first be executed on this interceptor if implemented. 
 63          Similarly, scripts on this interceptor take precedence over those of encompassed objects. 
 64          """ 
 65   
 66 -        def __init__(self, rootNVDAObject): 
 67                  super(TreeInterceptor, self).__init__() 
 68                  self._passThrough = False 
 69                  #: The root object of the tree wherein events and scripts are intercepted. 
 70                  #: @type: L{NVDAObjects.NVDAObject} 
 71                  self.rootNVDAObject = rootNVDAObject 
 72   
 73 -        def terminate(self): 
 74                  """Terminate this interceptor. 
 75                  This is called to perform any clean up when this interceptor is being destroyed. 
 76                  """ 
 77   
 78 -        def _get_isAlive(self): 
 79                  """Whether this interceptor is alive. 
 80                  If it is not alive, it will be removed. 
 81                  """ 
 82                  raise NotImplementedError 
 83   
 84          #: Whether this interceptor is ready to be used; i.e. whether it should receive scripts and events. 
 85          #: @type: bool 
 86          isReady = True 
 87   
 88 -        def __contains__(self, obj): 
 89                  """Determine whether an object is encompassed by this interceptor. 
 90                  @param obj: The object in question. 
 91                  @type obj: L{NVDAObjects.NVDAObject} 
 92                  @return: C{True} if the object is encompassed by this interceptor. 
 93                  @rtype: bool 
 94                  """ 
 95                  raise NotImplementedError 
 96   
 97 -        def _get_passThrough(self): 
 98                  """Whether most scripts should temporarily pass through this interceptor without being intercepted. 
 99                  """ 
100                  return self._passThrough 
101   
102 -        def _set_passThrough(self, state): 
103                  if self._passThrough == state: 
104                          return 
105                  self._passThrough = state 
106                  if state: 
107                          if config.conf['reviewCursor']['followFocus']: 
108                                  focusObj=api.getFocusObject() 
109                                  if self is focusObj.treeInterceptor: 
110                                          api.setNavigatorObject(focusObj) 
111                          braille.handler.handleGainFocus(api.getFocusObject()) 
112                  else: 
113                          obj=api.getNavigatorObject() 
114                          if config.conf['reviewCursor']['followCaret'] and self is obj.treeInterceptor:  
115                                  api.setNavigatorObject(self.rootNVDAObject) 
116                          braille.handler.handleGainFocus(self) 
117   
118          _cache_shouldPrepare=True 
119          shouldPrepare=False #:True if this treeInterceptor's prepare method should be called in order to make it ready (e.g. load a virtualBuffer, or process the document in some way). 
120   
121 -        def prepare(self): 
122                  """Prepares this treeInterceptor so that it becomes ready to accept event/script input.""" 
123                  raise NotImplementedError 
124