Source Code for Module AEChooser.Base

  1  ''' 
  2  Defines the base class for all choosers in LSR. 
  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  import weakref, os.path 
 15  import AEEvent, UIElement 
 16   
 17  GLOBAL_SINGLETONS = weakref.WeakValueDictionary() 
 18  APP_SINGLETONS = {} 
 19   
 20 -class AEChooser(UIElement.UIE): 
 21    '''   
 22    Most abstract base class for all L{AEChooser} dialogs. 
 23     
 24    This class is abstract as most of its methods raise NotImplementedError and  
 25    need to be overriden in subclasses. 
 26     
 27    @cvar GLOBAL_SINGLETON: Allow only one instance of a chooser to exist at a 
 28      time globally? This flag should be overriden by a subclass to indicate 
 29      whether the chooser is a global singleton or not. 
 30    @type GLOBAL_SINGLETON: boolean 
 31    @cvar APP_SINGLETON: Allow only one instance of a chooser to exist at a  
 32      time for a given application? This flag should be overriden by a subclass  
 33      to indicate whether the chooser is an application singleton or not. 
 34      Meaningless if L{GLOBAL_SINGLETON} is set. 
 35    @type APP_SINGLETON: boolean 
 36    @cvar OK: Indicates the chooser is completing and its options should be 
 37      applied 
 38    @type OK: integer 
 39    @cvar CANCEL: Indicates the chooser is canceling and its options should be 
 40      ignored 
 41    @type CANCEL: integer 
 42    @cvar APPLY: Indicates the chooser options should be applied immediately  
 43      with no changes to its state 
 44    @type APPLY: integer 
 45    @ivar event_man: Reference to the event manager to which an event will be 
 46      posted when the user indicates the dialog is completed, cancelled, or 
 47      the current optionss applied 
 48    @type event_man: L{EventManager} 
 49    @ivar aid: Unique identifier for the application L{Tier} with which the  
 50      L{AEChooser} that fired this event is associated 
 51    @type aid: opaque 
 52    @ivar block_signals: Blocks future signals from being sent by the L{_signal} 
 53      method after a L{OK} or L{CANCEL} signal is sent 
 54    @type block_signals: boolean 
 55    ''' 
 56    GLOBAL_SINGLETON = False 
 57    APP_SINGLETON = False 
 58    # these must be mutually exclusive from the signal constants used by subclass 
 59    CANCEL = -1000 
 60    APPLY = -1001 
 61    OK = -1002 
 62     
 63 -  def __init__(self): 
 64      ''' 
 65      Initializes the L{event_man} and L{aid} variables to None and sets the  
 66      L{block_signals} flag to False. 
 67      ''' 
 68      self.aid = None 
 69      self.event_man = None 
 70      self.block_signals = False 
 71       
 72 -  def __call__(self, event_man, aid): 
 73      '''     
 74      Stores a reference the L{EventManager} that will be notified by L{_signal} 
 75      and a reference to the L{Tier} in which the L{Perk} associated with this 
 76      L{AEChooser} is loaded. 
 77       
 78      @param event_man: Reference to the event manager to which an event will be 
 79        posted when the user indicates the dialog is completed, cancelled, or 
 80        the current options applied 
 81      @type event_man: L{EventManager} 
 82      @param aid: Unique identifier for the application L{Tier} with which the  
 83        L{AEChooser} that fired this event is associated 
 84      @type aid: L{Tier} 
 85      @raise ValueError: When the L{GLOBAL_SINGLETON} flag is set to True and a  
 86        singleton already exists or L{APP_SINGLETON} flag is set to True and a 
 87        chooser for the application already exists. 
 88      ''' 
 89      cls = self.getClassName() 
 90       
 91      if self.GLOBAL_SINGLETON and cls in GLOBAL_SINGLETONS: 
 92        raise ValueError(GLOBAL_SINGLETONS[cls]) 
 93      elif (self.APP_SINGLETON and  
 94            APP_SINGLETONS.has_key(cls) and  
 95            aid in APP_SINGLETONS[cls]): 
 96        raise ValueError(APP_SINGLETONS[cls][aid]) 
 97       
 98      self.aid = aid 
 99      self.event_man = event_man 
100      # store a weakref for singletons 
101      if self.GLOBAL_SINGLETON: 
102        GLOBAL_SINGLETONS[cls] = self 
103      # store a WeakValueDictionary 
104      elif self.APP_SINGLETON: 
105        try: 
106          APP_SINGLETONS[cls][aid] = self 
107        except KeyError: 
108          APP_SINGLETONS[cls] = weakref.WeakValueDictionary({aid:self}) 
109             
110 -  def init(self, **kwargs): 
111      ''' 
112      Initializes the chooser. Should enable the chooser for interaction with the 
113      user. 
114       
115      @raise NotImplementedError: When not overridden by a subclass 
116      ''' 
117      raise NotImplementedError 
118     
119 -  def activate(self, **kwargs): 
120      ''' 
121      Activates the chooser. Called when a singleton instance of the chooser 
122      already exists, but an attempt was just made to create another. Does  
123      nothing by default. Could be used to, for instance, raise a window to the 
124      foreground. 
125      ''' 
126      pass 
127       
128 -  def close(self): 
129      ''' 
130      Closes the chooser. Should prevent further chooser interaction with the  
131      user. 
132       
133      @raise NotImplementedError: When not overridden by a subclass 
134      ''' 
135      raise NotImplementedError 
136     
137 -  def update(self, **kwargs): 
138      ''' 
139      Does an update of some aspect of the L{AEChooser}. A subclass can override 
140      this method to support updates from observers of L{AEEvent.ChooserChange} 
141      events. 
142       
143      @param kwargs: Arbitrary data given by the observer. The L{AEChooser} 
144        implementor should strong-name keyword params of interest. 
145      @type kwargs: dictionary 
146      ''' 
147      pass 
148     
149 -  def _getResource(self, name): 
150      ''' 
151      Gets the absolute path to a file located in the same directory as this 
152      L{AEChooser}. Useful for locating resources like glade files. 
153       
154      @return: Path to a resource file in the same directory as the chooser 
155      @rtype: string 
156      ''' 
157      return os.path.join(self.getPath(), name) 
158   
159 -  def _signal(self, kind, **kwargs): 
160      '''         
161      Posts an L{AEEvent.ChooserChange} event to the L{EventManager}. Chooser 
162      change events should have an arbitrary kind or one of the special L{OK}, 
163      L{APPLY}, L{CANCEL} valus. Any keyword arguments will be delivered to the 
164      observer. The event will also include a reference to this L{AEChooser} such 
165      that an observer can call the L{update} method on it. The event is  
166      delivered only to the L{Perk} responsible for managing this chooser. 
167       
168      After one cancel or one OK signal is fired, no more signals are sent. 
169       
170      @param kind: Kind of signal, one of L{OK}, L{APPLY}, L{CANCEL} or a chooser 
171        defined integer constant 
172      @type kind: integer 
173      @param kwargs: Arbitrary data to be delivered with the event 
174      @type kwargs: dictionary 
175      ''' 
176      if self.block_signals: 
177        return 
178      self.event_man.postEvents(AEEvent.ChooserChange(self.aid, self, kind,  
179                                                      **kwargs)) 
180      if kind == self.CANCEL or kind == self.OK: 
181        self.block_signals = True 
182