Source Code for Module Task.Tools.Input

  1  ''' 
  2  Defines L{Tools} for getting input. 
  3   
  4  @author: Peter Parente 
  5  @organization: IBM Corporation 
  6  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  7  @license: The BSD License 
  8   
  9  All rights reserved. This program and the accompanying materials are made  
 10  available under the terms of the BSD license which accompanies 
 11  this distribution, and is available at 
 12  U{http://www.opensource.org/licenses/bsd-license.php} 
 13  ''' 
 14   
 15  import Base 
 16  from Error import * 
 17   
 18 -class Input(Base.TaskTools): 
 19    ''' 
 20    Provides methods for getting input on any L{AEInput} device. 
 21    ''' 
 22 -  def getInputDevice(self, name=None, *capabilities): 
 23      ''' 
 24      Gets an L{AEOutput} device from the L{DeviceManager} given its name or 
 25      its capabilities. The capabilities list may include strings naming  
 26      L{AEInput} interfaces ("braille" and/or "system input" at present). 
 27       
 28      If neither is specified, the first available output device in the 
 29      L{DeviceManager} is returned. 
 30       
 31      @param name: Class (UIE) name of the L{AEInput} device to get 
 32      @type name: string 
 33      @param capabilities: Names of capabilities required on the device 
 34      @type capabilities: list of string 
 35      @return: The named output device 
 36      @rtype: L{AEInput} 
 37      @raise InvalidDeviceError: When the specified L{AEInput} device is not  
 38        found 
 39      ''' 
 40      if name is not None: 
 41        device = self.device_man.getInputByName(name) 
 42      elif len(capabilities): 
 43        device = self.device_man.getInputByCaps(capabilities) 
 44      else:  
 45        device = self.device_man.getFirstInput() 
 46      if device is None: 
 47        # let the system report the device isn't available 
 48        raise InvalidDeviceError 
 49      return device 
 50     
 51 -  def addInputModifiers(self, dev, *codes): 
 52      ''' 
 53      Adds the given device code as a modifier on the named L{AEInput} device. 
 54      If the device doesn't support modifiers, ignores the error since it's a  
 55      non-critical operation. 
 56       
 57      @param dev: Reference to an input device 
 58      @type dev: L{AEInput} 
 59      @param codes: Action codes to add as modifiers 
 60      @type codes: integer 
 61      ''' 
 62      # notify device 
 63      try: 
 64        func = dev.addModifier  
 65      except AttributeError: 
 66        return 
 67      map(func, codes) 
 68      # register modifier with perk 
 69      self.perk.registerModifiers(dev, codes) 
 70        
 71 -  def removeInputModifiers(self, dev, *codes): 
 72      ''' 
 73      Removes the given device code as a modifier on the named L{AEInput} device. 
 74      If the device doesn't support modifiers, ignores the error since it's a  
 75      non-critical operation. 
 76       
 77      @param dev: Reference to an input device 
 78      @type dev: L{AEInput} 
 79      @param codes: Action codes to add as modifiers 
 80      @type codes: integer 
 81      ''' 
 82      # notify device 
 83      try: 
 84        func = dev.removeModifier  
 85      except AttributeError: 
 86        return 
 87      map(func, codes) 
 88       
 89      try: 
 90        # unregister modifier from perk 
 91        self.perk.unregisterModifiers(dev, codes)   
 92      except AttributeError: 
 93        pass 
 94     
 95 -  def registerCommand(self, dev, task_ident, propagate, *codes): 
 96      ''' 
 97      Registers a L{Task} in this L{Perk} to be executed in response to an  
 98      L{AEEvent} indicating that the given action codes were input on the given  
 99      L{AEInput} device.  
100       
101      @param dev: Device to monitor for input 
102      @type dev: L{AEInput} 
103      @param task_ident: Name of the L{Task} registered via  
104        L{Task.Tools.System.System.registerTask} to execute when the input  
105        gesture is detected on the device 
106      @type task_ident: string 
107      @param propagate: Should the input gesture be allowed to propagate to the  
108        OS after we receive it? 
109      @type propagate: boolean 
110      @param codes: List of lists of action codes forming the L{AEInput.Gesture}  
111        that will trigger the execution of the named L{Task}. For example,  
112        codes=[[Keyboard.AEK_CTRL, Keyboard.AEK_TILDE]] indicates the single 
113        gesture of simultaneously pressing Ctrl and ~ on the keyboard device. 
114      @type codes: list of list of integer 
115      @raise ValueError: When a L{Task} with the given name is not registered 
116      @raise InvalidDeviceError: When a L{AEInput} device with the given name is 
117        not registered 
118      ''' 
119      self.perk.registerCommandTask(dev, codes, task_ident, propagate) 
120       
121 -  def unregisterCommand(self, dev, *codes): 
122      ''' 
123      Unregisters a L{Task} set to execute in response to the given action codes  
124      on the given device B{from this L{Perk} only}. 
125       
126      @param dev: Device to monitor for input 
127      @type dev: L{AEInput} 
128      @param codes: List of lists of action codes forming the L{AEInput.Gesture}  
129        that will trigger the execution of the named L{Task}. For example,  
130        codes=[[Keyboard.AEK_CTRL, Keyboard.AEK_TILDE]] indicates the single 
131        gesture of simultaneously pressing Ctrl and ~ on the keyboard device. 
132      @type codes: list of list of integer 
133      @raise KeyError: When a L{AEInput.GestureList} is not registered 
134      @raise InvalidDeviceError: When a L{AEInput} device with the given name is 
135        not registered 
136      ''' 
137      self.perk.unregisterCommandTask(dev, codes) 
138