Source Code for Module AEEvent.InputGesture

  1  ''' 
  2  Defines an L{AEEvent} indicating a gesture has been performed on an L{AEInput}  
  3  device. 
  4   
  5  @author: Peter Parente 
  6  @author: Scott Haeger 
  7  @organization: IBM Corporation 
  8  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
  9  @license: The BSD License 
 10   
 11  All rights reserved. This program and the accompanying materials are made 
 12  available under the terms of the BSD license which accompanies 
 13  this distribution, and is available at 
 14  U{http://www.opensource.org/licenses/bsd-license.php} 
 15  ''' 
 16  import AEInput 
 17  import Base 
 18   
 19 -class InputGesture(Base.AccessEngineEvent): 
 20    '''   
 21    Event that fires when some L{AEInput.Gesture} is detected on an L{AEInput} 
 22    device. Always defaults to the focused layer. 
 23     
 24    This class registers its name and whether it should be monitored by default in 
 25    an L{AEMonitor} using the L{Base.registerEventType} function 
 26    when this module is first imported. The L{AEMonitor} can use this 
 27    information to build its menus. 
 28     
 29    @ivar gesture: Gesture detected 
 30    @type gesture: L{AEInput.Gesture} 
 31    @ivar timestamp: Time at which the gesture was received on the device 
 32    @type timestamp: float 
 33    @ivar kwargs: Additional arguments to be passed to a L{Task.InputTask} 
 34    @type kwargs: dictionary 
 35    ''' 
 36    Base.registerEventType('InputGesture', True) 
 37 -  def __init__(self, gesture, timestamp, **kwargs): 
 38      ''' 
 39      Calls the base class (which sets the event priority) and then stores the  
 40      L{AEInput.GestureList} that will be used to trigger a L{Task}. 
 41       
 42      @param gesture: Gestures detected on an L{AEInput} device 
 43      @type gesture: L{AEInput.Gesture} 
 44      @param timestamp: Time at which the gesture was received on the device 
 45      @type timestamp: float 
 46      @param kwargs: Additional arguments to be passed to a L{Task.InputTask} 
 47      @type kwargs: dictionary 
 48      ''' 
 49      Base.AccessEngineEvent.__init__(self, focused=True, **kwargs) 
 50      self.gesture = gesture 
 51      self.timestamp = timestamp 
 52      self.kwargs = kwargs 
 53       
 54 -  def __str__(self): 
 55      ''' 
 56      Returns a human readable representation of this event including its name, 
 57      its gesture codes, and its device. 
 58       
 59      @return: Information about this event 
 60      @rtype: string 
 61      ''' 
 62      name = Base.AccessEngineEvent.__str__(self) 
 63      return '%s:\n\tgesture: %s\n\tdevice: %s' % \ 
 64             (name, self.gesture, self.gesture.getDevice().getName()) 
 65   
 66 -  def execute(self, tier_manager, **kwargs): 
 67      ''' 
 68      Contacts the L{TierManager} and asks it to manage this event as a gesture. 
 69       
 70      @param tier_manager: TierManager that will handle the event 
 71      @type tier_manager: L{TierManager} 
 72      @param kwargs: Packed references to other managers not of interest here 
 73      @type kwargs: dictionary 
 74      @return: True to indicate the event executed properly 
 75      @rtype: boolean 
 76      ''' 
 77      tier_manager.manageGesture(self) 
 78      return True 
 79     
 80 -  def getTaskKey(self): 
 81      ''' 
 82      Gets the L{AEInput.GestureList} that triggered this event. This  
 83      information is used to locate the L{Task} that should handle this event. 
 84       
 85      @return: Gesture seen on an L{AEInput} device 
 86      @rtype: L{AEInput.GestureList} 
 87      ''' 
 88      g = self.gesture 
 89      return AEInput.GestureList(g.getDevice(), gestures=[g]) 
 90     
 91 -  def getTimestamp(self): 
 92      ''' 
 93      Gets the timestamp for when the event occurred. This timestamp is useful 
 94      for connecting input events to changes on the desktop. For instance, the 
 95      timestamp for keyboard input is needed when key presses open a new dialog 
 96      on some platforms such that the window manager can activate the dialog  
 97      once it appears. 
 98       
 99      @return: Gesture timestamp 
100      @rtype: float 
101      ''' 
102      return self.timestamp 
103     
104 -  def getDataForTask(self): 
105      ''' 
106      Fetches data out of this L{InputGesture} for use by a 
107      L{Task.InputTask}. 
108       
109      @return: Dictionary of parameters to be passed to a L{Task.InputTask} 
110        as follows: 
111          - timestamp: The time when the input gesture occurred. The scale and 
112            absolute zero is device dependent. 
113          - any additional data in the L{kwargs} instance variable         
114      @rtype: dictionary 
115      ''' 
116      d = {} 
117      d.update(self.kwargs) 
118      d['timestamp'] = self.timestamp 
119      d['gesture'] = self.gesture 
120      return d 
121