Source Code for Module Task.Tools.Base

  1  ''' 
  2  Defines the most base L{Tools} class from which all other L{Task.Tools} should 
  3  derive. 
  4   
  5  @author: Peter Parente 
  6  @author: Pete Brunet 
  7  @author: Larry Weiss 
  8  @organization: IBM Corporation 
  9  @copyright: Copyright (c) 2005, 2007 IBM Corporation 
 10  @license: The BSD License 
 11   
 12  All rights reserved. This program and the accompanying materials are made  
 13  available under the terms of the BSD license which accompanies 
 14  this distribution, and is available at 
 15  U{http://www.opensource.org/licenses/bsd-license.php} 
 16  ''' 
 17  import weakref 
 18  import AEConstants, AEInterfaces 
 19  from i18n import _ 
 20   
 21 -class TaskTools(object): 
 22    ''' 
 23    Provides initialize and finalize methods for preparing and unpreparing the 
 24    data required by L{Tools} subclasses while a L{Task} or L{Perk} is executing. 
 25    Temporarily stores information such as the event layer, event L{POR}, and 
 26    timestamp. 
 27     
 28    @ivar acc_eng: Reference to L{AccessEngine} for task context 
 29    @type acc_eng: L{AccessEngine} 
 30    @ivar event_man: Reference to the L{EventManager} 
 31    @type event_man: L{EventManager} 
 32    @ivar view_man: Reference to the L{ViewManager} 
 33    @type view_man: L{ViewManager} 
 34    @ivar tier_man: Reference to the L{TierManager} 
 35    @type tier_man: L{TierManager} 
 36    @ivar device_man: Reference to the L{DeviceManager} 
 37    @type device_man: L{DeviceManager} 
 38    @ivar sett_man: Reference to the L{SettingsManager} 
 39    @type sett_man: L{SettingsManager} 
 40    @ivar tier: The L{Tier} owning the L{Task} or L{Perk} subclass 
 41    @type tier: L{Tier} 
 42    @ivar perk: The L{Perk} owning the L{Task} subclass 
 43    @type perk: L{Perk} 
 44    @ivar layer: Layer on which the event occurred 
 45    @type layer: integer 
 46    @ivar lsr_state: The state object shared across all L{Tier}s 
 47    @type lsr_state: L{AEState.AEState} 
 48    @ivar perk_state: The state object shared across all instances of this  
 49      L{Perk} 
 50    @type perk_state: L{AEState.AEState} 
 51    @ivar task_por:  The L{POR} for the Task or Perk subclass, set by  
 52      L{preExecute} 
 53    @type task_por: L{POR} 
 54    @ivar tools_initialized: Is the instance ready to be executed? 
 55    @type tools_initialized: boolean 
 56    @ivar tools_auto_pointer: Should the task_por become the pointer after  
 57      execution? 
 58    @type tools_auto_pointer: boolean 
 59    @ivar def_out: Default output device to use for all 
 60    L{Task.Tools.Output.Output.say} 
 61      calls in this L{Perk} module. 
 62    @type def_out: weakref.proxy to L{AEOutput} 
 63    ''' 
 64 -  def __init__(self): 
 65      ''' 
 66      Create the ivars and initialize them to None or reasonable defaults. 
 67      ''' 
 68      self.perk = None 
 69      self.event_man = None 
 70      self.device_man = None 
 71      self.tier_man = None 
 72      self.view_man = None 
 73      self.sett_man = None 
 74      self.lsr_state = None 
 75      self.perk_state = None 
 76      self.task_por = None 
 77      self.tier = None 
 78      self.layer = None 
 79      self.acc_eng = None 
 80      self.def_out = None 
 81      self.tools_initialized = False 
 82      self.tools_auto_pointer = True 
 83       
 84 -  def preInit(self, ae, tier, perk=None): 
 85      '''  
 86      Initializes the references to the L{Perk}, L{Tier}, L{AccessEngine} 
 87      owning this instance of the L{TaskTools}. Contacts the L{AccessEngine} to 
 88      get refs to all managers. These references are fixed throughout the life of 
 89      the tools object. 
 90       
 91      Called before state information is loaded from disk. 
 92       
 93      @param ae: Reference to AccessEngine for event context 
 94      @type ae: L{AccessEngine} 
 95      @param tier: The L{Tier} executing this L{TaskTools} object 
 96      @type tier: L{Tier} 
 97      @param perk: The L{Perk} containing this L{TaskTools} object 
 98      @type perk: L{Perk} 
 99      @return: Did the L{TaskTools} initialize (True) or not (False)? 
100      @rtype: boolean 
101      ''' 
102      if self.tools_initialized: 
103        # don't reinitialize if we already are initialized 
104        return False 
105       
106      # store a reference to the AccessEngine and owning Tier 
107      self.acc_eng = ae 
108      self.tier = tier 
109       
110      # store the perk, which may be this object itself 
111      if perk is None: 
112        self.perk = self 
113      else: 
114        self.perk = perk 
115         
116      # get all manager references from AccessEngine very quickly 
117      self.acc_eng.loanManagers(self) 
118       
119      # get all state objects 
120      self.lsr_state = self.tier_man.getState() 
121      self.perk_state = self.perk.getState() 
122       
123      # indicate we're initialized now 
124      self.tools_initialized = True 
125       
126      return True 
127   
128 -  def init(self): 
129      ''' 
130      Does nothing. Reserved for subclasses to initialize themselves. 
131      ''' 
132      pass 
133   
134 -  def postClose(self): 
135      ''' 
136      Frees the references to the L{Tier}, L{Perk}, and L{AccessEngine} as well  
137      as all borrowed references from the L{AccessEngine}. Releases references to 
138      state information. Intended to be called after L{close}. 
139      ''' 
140      if not self.tools_initialized: 
141        # don't re-uninitialize 
142        return 
143      # toss references to owning Perk and Tier 
144      self.tier = None 
145      self.perk = None 
146      # throw away manager and access engine refs 
147      self.acc_eng.unloanManagers(self) 
148      self.acc_eng = None 
149      # IMPORTANT: throw away weak ref to device else the callback keeps it alive 
150      self.def_out = None 
151      # throw away references to state 
152      self.lsr_state = None 
153      self.perk_state = None 
154      # inidicate we're not initialized anymore 
155      self.tools_initialized = False 
156   
157 -  def close(self): 
158      ''' 
159      Does nothing. Reserved for subclasses to finalize themselves. 
160      ''' 
161      pass 
162     
163 -  def preExecute(self, layer, event_por=None): 
164      ''' 
165      Configures this L{TaskTools} object before execution. 
166   
167      @param layer: Layer on which the event occurred 
168      @type layer: integer 
169      @param event_por: Point of regard received with the event that triggered 
170        this execution 
171      @type event_por: L{POR} 
172      @return: Is the instance ready for execution? 
173      @rtype: boolean 
174      ''' 
175      if not self.tools_initialized: 
176        # don't do anything if the tools aren't initialized 
177        return False 
178       
179      # reset the auto pointer flag to True 
180      self.tools_auto_pointer = True 
181   
182      # store the layer 
183      self.layer = layer 
184   
185      # use the POR from the event or the last saved Task POR if there is no POR  
186      # associated with the event 
187      self.task_por = event_por or self.tier.getPointer() 
188       
189      try: 
190        # call a method on the default output device to ensure the ref is alive 
191        self.def_out.getName() 
192      except (AttributeError, ReferenceError): 
193        # get an output device to serve as the default output 
194        self._changeDefaultOutput() 
195      return True 
196   
197 -  def postExecute(self): 
198      ''' 
199      Unconfigures this L{TaskTools} object after execution. Automatically 
200      updates the L{Tier} pointer L{POR} if , the L{tools_initialized} flag is 
201      True, the L{tools_auto_pointer} is True, and the event handled is in the 
202      focus layer. 
203      ''' 
204      if (self.tools_initialized and # only store if initialized 
205          self.tools_auto_pointer and # only store if auto pointer 
206          AEConstants.LAYER_FOCUS == self.layer): # only store if focus layer 
207        self.tier.setPointer(self.task_por) 
208   
209 -  def _changeDefaultOutput(self, ref=None): 
210      ''' 
211      Gets an output device based on the ideal capabilities requested by the 
212      current L{Perk}. Creates a weak proxy for the device object. When the 
213      weak ref is no longer valid, this method is called again to find another 
214      suitable device. 
215       
216      @param ref: Weak proxy that is no longer valid 
217      @type ref: weakref.proxy 
218      ''' 
219      if not self.tools_initialized: 
220        return 
221      # get an output device to serve as the default output 
222      caps = self.perk.getIdealOutput() 
223      dev = self.device_man.getOutputByCaps(caps) 
224      try: 
225        self.def_out = weakref.proxy(dev, self._changeDefaultOutput) 
226      except TypeError: 
227        self.def_out = None 
228