Source Code for Module AccessEngine.AEDevice.AEInput.Base

  1  ''' 
  2  Defines the abstract base class for all L{AEInput} subclasses. 
  3   
  4  @author: Peter Parente 
  5  @author: Scott Haeger 
  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 logging 
 16  from AccessEngine import AEUserInterface 
 17  from AccessEngine import AEConstants 
 18   
 19  log = logging.getLogger('Input') 
 20   
 21 -def getDefaults(): 
 22    ''' 
 23    Suggests the default L{AEOutput}s events to be monitored. 
 24     
 25    @return: Empty list, don't monitor by default 
 26    @rtype: list of string 
 27    ''' 
 28    return [] 
 29     
 30 -def getNames(): 
 31    ''' 
 32    Gets the names of all the L{AEInput} command types. 
 33     
 34    @return: List of all known L{AEInput} command names 
 35    @rtype: list of string 
 36    ''' 
 37    names = AEConstants.INPUT_COMMAND_NAMES.values() 
 38    names.sort() 
 39    return names 
 40   
 41 -class AEInput(AEUserInterface.AEUserInterface): 
 42    '''   
 43    Most abstract base class for all L{AEInput} devices. Maintains a collection of 
 44    L{Gesture} listeners that can be notified using L{_notifyInputListeners}. 
 45    Defines simple L{init} and L{close} methods that change the state of the 
 46    L{ready} flag. 
 47     
 48    This class is abstract as most of its methods raise NotImplementedError and  
 49    need to be overriden with input device specific code in subclasses. 
 50   
 51    @ivar listeners: Collection of listeners that are notified about L{Gesture}s 
 52      on an input device 
 53    @type listeners: list of callable 
 54    @ivar ready: Is the input device initialized? 
 55    @type ready: boolean 
 56    ''' 
 57 -  def __init__(self): 
 58      ''' 
 59      Initializes the listeners list to empty and sets the ready flag to False. 
 60      ''' 
 61      self.listeners = [] 
 62   
 63 -  def init(self): 
 64      ''' 
 65      Called after the instance is created to initialize the device. 
 66   
 67      If called when already initialized, this will restore the device to it's 
 68      initialized state. May also be called to re-initialize the device after 
 69      a call to L{close}. 
 70   
 71      @raise NotImplementedError: When not overridden in a subclass 
 72      @raise Error.InitError: When a communication or state problem exists for  
 73        the specific device 
 74      ''' 
 75      raise NotImplementedError 
 76       
 77 -  def getCapabilities(self): 
 78      ''' 
 79      Gets a list of strings representing the capabilities of this device.  
 80      Typical output capabilities include "system input," "braille," "switch," 
 81      etc. though others are certainly possible. 
 82       
 83      The L{AEDeviceManager} will only load a device if another device doesn't 
 84      already provide all of its capabilities. 
 85       
 86      @return: Lowercase names of output capabilities 
 87      @rtype: list of string 
 88      ''' 
 89      raise NotImplementedError 
 90       
 91 -  def close(self):  
 92      ''' 
 93      Closes an initialized input device. 
 94   
 95      @raise NotImplementedError: When not overridden in a subclass 
 96      ''' 
 97      raise NotImplementedError 
 98       
 99 -  def addInputListener(self, listener): 
100      ''' 
101      Adds a listener to be notified whenever a L{Gesture} occurs on an input 
102      device. Listeners are called in the order they are added and are given the 
103      L{Gesture} detected. 
104       
105      @param listener: Object to call when a L{Gesture} occurs 
106      @type listener: callable 
107      ''' 
108      self.listeners.append(listener) 
109       
110 -  def removeInputListener(self, listener): 
111      ''' 
112      Removes an existing listener for L{Gesture}s. 
113       
114      @param listener: Object to remove from the listener list 
115      @type listener: callable 
116      @raise ValueError: When removing a listener that is not registered 
117      ''' 
118      self.listeners.remove(listener) 
119       
120 -  def inputListenersExist(self): 
121      ''' 
122      Gets if there are any registered L{Gesture} listeners for this device. 
123       
124      @return: Is there at least one listener registered? 
125      @rtype: boolean 
126      ''' 
127      return len(self.listeners) > 0 
128       
129 -  def _notifyInputListeners(self, gesture, timestamp, **kwargs): 
130      ''' 
131      Notifies registered listeners about a L{Gesture} seen on the input device.  
132      Catches all exceptions from the callback and logs them. 
133       
134      @param gesture: L{Gesture} to send to listeners 
135      @type gesture: L{Gesture} 
136      @param timestamp: Time at which at the gesture happened 
137      @type timestamp: float 
138      @param kwargs: Additional data to include in the notification 
139      @type kwargs: dictionary 
140      ''' 
141      for listener in self.listeners: 
142        try: 
143          listener(gesture, timestamp, **kwargs) 
144        except Exception: 
145          log.exception('AEInput exception') 
146   
147 -  def sortGesture(self, gesture): 
148      ''' 
149      Sorts the actions in the given L{AEInput.Gesture} and returns them as a list 
150      of integers. The sort is done on a copy so the action codes held by the 
151      provided L{AEInput.Gesture} are not touched. 
152   
153      @param gesture: L{AEInput.Gesture} to sort 
154      @type gesture: L{AEInput.Gesture} 
155      @return: Sorted list of action codes that may be wrapped in a new 
156        L{AEInput.Gesture} 
157      @rtype: list of integer 
158      ''' 
159      codes = gesture.getActionCodes() 
160      codes.sort() 
161      return codes 
162     
163 -  def getMaxActions(self): 
164      ''' 
165      Abstract method. Gets the maximum number of actions that can be in a  
166      L{Gesture} on this input device. 
167       
168      @return: Maximum number of actions per L{Gesture} supported by this device 
169      @rtype: integer 
170      @raise NotImplementedError: When this method is not overridden by a subclass 
171      ''' 
172      raise NotImplementedError 
173       
174 -  def asString(self, gesture):  
175      '''  
176      Abstract method. Gets a human readable representation of the given 
177      L{Gesture}. 
178       
179      @param gesture: L{Gesture} object to render as text 
180      @type gesture: L{Gesture} 
181      @return: Text representation of the L{Gesture}  
182      @rtype: string 
183      @raise NotImplementedError: When this method is not overridden by a subclass 
184      ''' 
185      raise NotImplementedError 
186     
187 -  def addKeyCmd(self, codes): 
188      '''  
189      Abstract method. Registers KEY_CMD with device . 
190       
191      @param codes: list of lists of KEY_CMD* codes 
192      @type codes: list 
193      @raise NotImplementedError: When this method is not overridden by a subclass 
194      ''' 
195      pass 
196       
197 -  def removeKeyCmd(self, codes): 
198      '''  
199      Abstract method. Unregisters KEY_CMD with device . 
200       
201      @param codes: list of lists of KEY_CMD* codes 
202      @type codes: list 
203      @raise NotImplementedError: When this method is not overridden by a subclass 
204      ''' 
205      raise NotImplementedError 
206