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