Source Code for Module AccessEngine.AEDevice.AEInput.GestureList

  1  ''' 
  2  Defines a class representing a collection of L{Gesture}s performed in sequence 
  3  on an L{AEInput} device. 
  4   
  5  @author: Peter Parente 
  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  from Gesture import Gesture 
 16   
 17 -class GestureList(object): 
 18    ''' 
 19    Manages a list of L{Gesture} objects in the order in which they occured. 
 20    Represents a sequence of L{Gesture}s for the purposes of detecting and  
 21    filtering that sequence when it occurs on an input device. 
 22     
 23    @ivar device: Input device on which the L{Gesture} sequence is performed 
 24    @type device: L{AEInput.AEInput} 
 25    @ivar gestures: L{Gesture}s in the sequence 
 26    @type gestures: list of L{Gesture} 
 27    @ivar hash: Cached copy of the hash value of the L{GestureList} 
 28    @type hash: integer 
 29    ''' 
 30 -  def __init__(self, device, action_codes=None, gestures=None, 
 31                 copy_gestures=None): 
 32      '''     
 33      Stores a reference to the input device. If action codes are specified, wraps 
 34      them in L{Gesture} objects and stores those objects. If L{Gesture}s are 
 35      specified, stores those objects. If L{Gesture}s to copy are given, makes a 
 36      copy of those objects and stores the copies, not the original references. If 
 37      none of these is given, creates an empty list to be filled with L{Gesture}s 
 38      later. 
 39       
 40      @param device: Input device on which this L{Gesture} is performed 
 41      @type device: L{AEInput.AEInput} 
 42      @param action_codes: List of lists of action codes that will be stored in 
 43          L{Gesture} objects in this L{GestureList} 
 44      @type action_codes: list of lists of integer 
 45      @param gestures: L{Gesture}s that this L{GestureList} should store 
 46      @type gestures: list of L{Gesture}   
 47      @param copy_gestures: L{Gesture}s that this L{GestureList} should duplicate 
 48        and store 
 49      @type copy_gestures: list of L{Gesture} 
 50      ''' 
 51      self.device = device 
 52      self.hash = None 
 53      if action_codes is not None: 
 54        # build Gestures from the lists of codes in the action codes list 
 55        self.gestures = [Gesture(self.device, codes) for codes in action_codes] 
 56      elif gestures is not None: 
 57        # store gesture references 
 58        self.gestures = gestures 
 59      elif copy_gestures is not None: 
 60        # store copies of gestures 
 61        self.gestures = [Gesture(self.device, gesture=g) for g in copy_gestures] 
 62      else: 
 63        # initialize to an empty list if no gestures provided 
 64        self.gestures = [] 
 65         
 66 -  def __eq__(self, other): 
 67      ''' 
 68      Compares this L{GestureList} to the one provided to see if they represent 
 69      the same sequence of L{Gesture}s on the same device. The comparison 
 70      performed is order dependent since a different sequence of L{Gesture}s could 
 71      represent a different input intention. 
 72       
 73      @param other: L{GestureList} to compare to this one 
 74      @type other: L{GestureList} 
 75      @return: Is this L{GestureList} equal to the one provided? 
 76      @rtype: boolean 
 77      ''' 
 78      # equality comparison on lists of Gesture objects invokes __eq__ on each 
 79      # object so this comparison is by value, not by instance 
 80      try: 
 81        return (self.device == other.device) and \ 
 82               (self.gestures == other.gestures) 
 83      except Exception: 
 84        return False 
 85   
 86 -  def __hash__(self): 
 87      ''' 
 88      Builds a hash code for this L{GestureList} based on its L{Gesture} contents 
 89      by XORing their hash values together. The hash code is used by an L{AEInput} 
 90      device to store and retrieve filters from a dictionary. 
 91       
 92      @return: Hash code for this L{GestureList} 
 93      @rtype: integer 
 94      ''' 
 95      if self.hash is None: 
 96        self.hash = 0 
 97        for gesture in self.gestures: 
 98          self.hash = self.hash^hash(gesture) 
 99      return self.hash 
100       
101 -  def getGestureAt(self, i): 
102      '''     
103      Gets the L{Gesture} stored at the given index. If the index is invalid, 
104      raises IndexError. 
105       
106      @param i: Index of the L{Gesture} to retrieve 
107      @type i: integer 
108      @return: L{Gesture} retrieved from this L{GestureList} 
109      @rtype: L{Gesture} 
110      @raise IndexError: When the index is invalid 
111      ''' 
112      return self.gestures[i] 
113       
114 -  def addGesture(self, gesture): 
115      ''' 
116      Adds a L{Gesture} to the end of this L{GestureList}. 
117       
118      @param gesture: L{Gesture} to add 
119      @type gesture: L{Gesture} 
120      ''' 
121      self.gestures.append(gesture) 
122      self.hash = None 
123     
124 -  def getNumGestures(self): 
125      ''' 
126      Gets the total number of L{Gesture}s currently in this L{GestureList}. 
127       
128      @return: L{Gesture} count 
129      @rtype: integer 
130      ''' 
131      return len(self.gestures) 
132   
133 -  def asString(self): 
134      '''     
135      Gets a human readable representation of all the L{Gesture}s in this 
136      L{GestureList} determined by the L{AEInput} device on which they are 
137      performed. 
138       
139      @return: Text representation of all the L{Gesture}s in this L{GestureList} 
140      @rtype: string 
141      ''' 
142      out = [] 
143      for gesture in self.gestures: 
144        out.append('(%s)' % gesture.asString()) 
145      return ' '.join(out) 
146     
147 -  def getDevice(self): 
148      ''' 
149      Gets the device on which the L{Gesture}s in this L{GestureList} are 
150      performed. 
151       
152      @return: Device on which the L{Gesture}s in this L{GestureList} are  
153        performed 
154      @rtype: L{AEInput.AEInput} 
155      ''' 
156      return self.device 
157