1 '''
2 Defines the base class for all choosers in SUE.
3
4 @author: Peter Parente
5 @organization: IBM Corporation
6 @copyright: Copyright (c) 2005, 2007 IBM Corporation
7 @license: The BSD License
8
9 @author: Frank Zenker
10 @organization: IT Science Center Ruegen gGmbH, Germany
11 @copyright: Copyright (c) 2007, 2008 ITSC Ruegen
12 @license: The BSD License
13
14 All rights reserved. This program and the accompanying materials are made
15 available under the terms of the BSD license which accompanies
16 this distribution, and is available at
17 U{http://www.opensource.org/licenses/bsd-license.php}
18 '''
19 import weakref, os.path
20 import AccessEngine
21 from AccessEngine import AEEvent
22 import AEUserInterface
23
24 GLOBAL_SINGLETONS = weakref.WeakValueDictionary()
25 APP_SINGLETONS = {}
26
27 -class AEChooser(AEUserInterface.AEUserInterface):
28 '''
29 Most abstract base class for all L{AEChooser} dialogs.
30
31 This class is abstract as most of its methods raise NotImplementedError and
32 need to be overriden in subclasses.
33
34 @cvar GLOBAL_SINGLETON: Allow only one instance of a chooser to exist at a
35 time globally? This flag should be overriden by a subclass to indicate
36 whether the chooser is a global singleton or not.
37 @type GLOBAL_SINGLETON: boolean
38 @cvar APP_SINGLETON: Allow only one instance of a chooser to exist at a
39 time for a given application? This flag should be overriden by a subclass
40 to indicate whether the chooser is an application singleton or not.
41 Meaningless if L{GLOBAL_SINGLETON} is set.
42 @type APP_SINGLETON: boolean
43 @cvar OK: Indicates the chooser is completing and its options should be
44 applied
45 @type OK: integer
46 @cvar CANCEL: Indicates the chooser is canceling and its options should be
47 ignored
48 @type CANCEL: integer
49 @cvar APPLY: Indicates the chooser options should be applied immediately
50 with no changes to its state
51 @type APPLY: integer
52 @ivar aid: Unique identifier for the application L{AETier} with which the
53 L{AEChooser} that fired this event is associated
54 @type aid: opaque
55 @ivar block_signals: Blocks future signals from being sent by the L{_signal}
56 method after a L{OK} or L{CANCEL} signal is sent
57 @type block_signals: boolean
58 '''
59 GLOBAL_SINGLETON = False
60 APP_SINGLETON = False
61
62 CANCEL = -1000
63 APPLY = -1001
64 OK = -1002
65
67 '''
68 Initializes the L{aid} variable to None and sets the L{block_signals} flag
69 to False.
70 '''
71 self.aid = None
72 self.block_signals = False
73
75 '''
76 Stores a reference the L{AEEventManager} that will be notified by L{_signal}
77 and a reference to the L{AETier} in which the L{AEScript <AEScript.AEScript>} associated with this
78 L{AEChooser} is loaded.
79
80 @param aid: Unique identifier for the application L{AETier} with which the
81 L{AEChooser} that fired this event is associated
82 @type aid: L{AETier}
83 @raise ValueError: When the L{GLOBAL_SINGLETON} flag is set to True and a
84 singleton already exists or L{APP_SINGLETON} flag is set to True and a
85 chooser for the application already exists.
86 '''
87 cls = self.getClassName()
88
89 if self.GLOBAL_SINGLETON and cls in GLOBAL_SINGLETONS:
90 raise ValueError(GLOBAL_SINGLETONS[cls])
91 elif (self.APP_SINGLETON and
92 APP_SINGLETONS.has_key(cls) and
93 aid in APP_SINGLETONS[cls]):
94 raise ValueError(APP_SINGLETONS[cls][aid])
95
96 self.aid = aid
97
98 if self.GLOBAL_SINGLETON:
99 GLOBAL_SINGLETONS[cls] = self
100
101 elif self.APP_SINGLETON:
102 try:
103 APP_SINGLETONS[cls][aid] = self
104 except KeyError:
105 APP_SINGLETONS[cls] = weakref.WeakValueDictionary({aid:self})
106
107 - def init(self, **kwargs):
108 '''
109 Initializes the chooser. Should enable the chooser for interaction with the
110 user.
111
112 @raise NotImplementedError: When not overridden by a subclass
113 '''
114 raise NotImplementedError
115
117 '''
118 Activates the chooser. Called when a singleton instance of the chooser
119 already exists, but an attempt was just made to create another. Does
120 nothing by default. Could be used to, for instance, raise a window to the
121 foreground.
122 '''
123 pass
124
126 '''
127 Closes the chooser. Should prevent further chooser interaction with the
128 user.
129
130 @raise NotImplementedError: When not overridden by a subclass
131 '''
132 raise NotImplementedError
133
135 '''
136 Does an update of some aspect of the L{AEChooser}. A subclass can override
137 this method to support updates from observers of L{AEEvent.ChooserChange}
138 events.
139
140 @param kwargs: Arbitrary data given by the observer. The L{AEChooser}
141 implementor should strong-name keyword params of interest.
142 @type kwargs: dictionary
143 '''
144 pass
145
147 '''
148 Gets the absolute path to a file located in the same directory as this
149 L{AEChooser}. Useful for locating resources like glade files.
150
151 @return: Path to a resource file in the same directory as the chooser
152 @rtype: string
153 '''
154 return os.path.join(self.getPath(), name)
155
156 - def _signal(self, kind, **kwargs):
157 '''
158 Posts an L{AEEvent.ChooserChange} event to the L{AEEventManager}. Chooser
159 change events should have an arbitrary kind or one of the special L{OK},
160 L{APPLY}, L{CANCEL} valus. Any keyword arguments will be delivered to the
161 observer. The event will also include a reference to this L{AEChooser} such
162 that an observer can call the L{update} method on it. The event is
163 delivered only to the L{AEScript <AEScript.AEScript>} responsible for managing this chooser.
164
165 After one cancel or one OK signal is fired, no more signals are sent.
166
167 @param kind: Kind of signal, one of L{OK}, L{APPLY}, L{CANCEL} or a chooser
168 defined integer constant
169 @type kind: integer
170 @param kwargs: Arbitrary data to be delivered with the event
171 @type kwargs: dictionary
172 '''
173 if self.block_signals:
174 return
175 AccessEngine.AEEventManager.postEvents(AEEvent.ChooserChange(self.aid, self, kind,
176 **kwargs))
177 if kind == self.CANCEL or kind == self.OK:
178 self.block_signals = True
179