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