Source Code for Module AccessEngine.AEEvent.Base

  1  ''' 
  2  Defines the base class for all L{AccessEngine} events (L{AEEvent}s). 
  3   
  4  @author: Peter Parente 
  5  @author: Pete Brunet 
  6  @organization: IBM Corporation 
  7  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  8  @license: The BSD License 
  9   
 10  @author: Frank Zenker 
 11  @author: Ramona Bunk 
 12  @organization: IT Science Center Ruegen gGmbH, Germany 
 13  @copyright: Copyright (c) 2007, 2008 ITSC Ruegen 
 14  @license: The BSD License 
 15   
 16  All rights reserved. This program and the accompanying materials are made  
 17  available under the terms of the BSD license which accompanies 
 18  this distribution, and is available at 
 19  U{http://www.opensource.org/licenses/bsd-license.php} 
 20  ''' 
 21  from AccessEngine import AEConstants 
 22  from AccessEngine.AEAccInterfaces import * 
 23   
 24  default_types = [] 
 25  all_types = [] 
 26   
 27 -def registerEventType(name, default): 
 28    ''' 
 29    Called once by every L{AEEvent} class to register itself for buffering and  
 30    filtering by an L{AEMonitor}. 
 31     
 32    @param name: Name of the L{AEEvent} 
 33    @type name: string 
 34    @param default: Should this L{AEEvent} be buffered by default? 
 35    @type default: boolean 
 36    ''' 
 37    global default_types 
 38    global all_types 
 39    all_types.append(name) 
 40    if default: 
 41      default_types.append(name) 
 42       
 43 -def getDefaults(): 
 44    ''' 
 45    Suggests the default L{AEEvent}s to be monitored. 
 46     
 47    @return: Names of defaults to monitor 
 48    @rtype: list of string 
 49    ''' 
 50    return default_types   
 51     
 52 -def getNames(): 
 53    ''' 
 54    Gets the names of all the L{AEEvent} types. 
 55     
 56    @return: List of all L{AEEvent} names 
 57    @rtype: list of string 
 58    ''' 
 59    return all_types 
 60   
 61 -class AEEvent(object): 
 62    ''' 
 63    Most base class for all L{AccessEngine} events. Supports the concept of a  
 64    priority which may be used to prioritize event execution. 
 65   
 66    @ivar priority: Priority of this event 
 67    @type priority: integer 
 68    @ivar layer: Layer of this event (focus, tier, background) 
 69    @type layer: integer 
 70    @ivar por: Point of regard associated with this event 
 71    @type por: L{AEPor} 
 72    ''' 
 73 -  def __init__(self, priority=AEConstants.EXEC_NORMAL, focused=False, **kwargs): 
 74      ''' 
 75      Stores the event priority and whether the event source was focused or not. 
 76   
 77      @param priority: Priority of this event, defaults to normal 
 78      @type priority: integer     
 79      @param focused: Was the source of the event focused at the time of event  
 80        creation? 
 81      @type focused: boolean 
 82      ''' 
 83      self.priority = priority 
 84      self.por = None 
 85      if focused: 
 86        self.layer = AEConstants.LAYER_FOCUS 
 87      else: 
 88        self.layer = AEConstants.LAYER_BACKGROUND 
 89       
 90 -  def __str__(self): 
 91      ''' 
 92      Returns the name of this event. 
 93       
 94      @return: Class name of this AEEvent 
 95      @rtype: string 
 96      ''' 
 97      level = AEConstants.LAYER_NAMES[self.layer] 
 98      return '%s (%s)' % (self.__class__.__name__, level) 
 99       
100 -  def execute(self): 
101      ''' 
102      Executes the logic that will handle this event. The L{AEEventManager} can  
103      provide whatever arguments are necessary for an L{AEEvent} subclass to  
104      execute as keyword arguments. It is up to the subclass to unpack and use  
105      the arguments it needs by name. 
106       
107      See L{AccessEngine.AEEventManager._AEEventManager}._executeEvent for the 
108      arguments provided. 
109       
110      @return: Was this class able to execute successfully? Always True here. 
111      @rtype: boolean 
112      ''' 
113      return True 
114       
115 -  def getPriority(self): 
116      ''' 
117      @return: Current priority value 
118      @rtype: integer 
119      ''' 
120      return self.priority 
121       
122 -  def setPriority(self, priority): 
123      ''' 
124      @param priority: New priority value 
125      @type priority: integer 
126      ''' 
127      self.priority = priority 
128       
129 -  def setLayer(self, layer): 
130      ''' 
131      @param layer: Layer of this event (focus, tier, background) 
132      @type layer: integer 
133      ''' 
134      self.layer = layer 
135       
136 -  def getLayer(self): 
137      ''' 
138      Gets the layer for this event. If the L{AEPor} is marked as imcomplete, builds 
139      a complete L{AEPor} and then determines if the proper L{AEPor} is in a different 
140      layer than the one originally computed. 
141       
142      @return: Gets the layer for this event 
143      @rtype: integer 
144      ''' 
145      if self.por is not None and self.por.incomplete: 
146        if IAccessibleInfo(self.getPOR()).hasAccState('focused'): 
147          self.layer = AEConstants.LAYER_FOCUS 
148      return self.layer 
149   
150 -  def getDataForTask(self): 
151      ''' 
152      Fetches data out of an L{AEEvent} for use by a task. This  
153      method must be implemented by any L{AEEvent} that will be handled by  
154      L{AETierManager <AETierManager._AETierManager>}.manageEvent or 
155      L{AETierManager <AETierManager._AETierManager>}.manageGesture. 
156       
157      @return: Empty dictionary 
158      @rtype: dictionary 
159      ''' 
160      return {} 
161     
162 -  def getTimestamp(self): 
163      ''' 
164      Gets the timestamp for when the event occurred. 
165       
166      @return: Always zero when not overridden 
167      @rtype: float 
168      ''' 
169      return 0 
170     
171 -  def getPOR(self): 
172      ''' 
173      @return: Point of regard associated with this event 
174      @rtype: L{AEPor} 
175      ''' 
176      if self.por is not None and self.por.incomplete: 
177        self.por = IPORFactory(self.por).create() 
178      return self.por 
179     
180 -  def getAppID(self): 
181      ''' 
182      @return: Unique application ID identifying the top most container for the 
183        source of this event (i.e. the application) 
184      @rtype: opaque object 
185      ''' 
186      if self.por is None: 
187        return None 
188      else: 
189        try: 
190          return IAccessibleInfo(self.por).getAccAppID() 
191        except LookupError: 
192          # app is dead 
193          return None 
194