1 '''
2 Defines an L{AEEvent} indicating an event of interest occurred in an
3 L{AEChooser}.
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
16 import Base
17
19 '''
20 Event that fires when a L{AEChooser} indicates important input from a user.
21
22 This class registers its name and whether it should be monitored by default
23 in an L{AEMonitor} using the L{Base.registerEventType} function when
24 this module is first imported. The L{AEMonitor} can use this information to
25 build its menus.
26
27 @ivar aid: Unique identifier for the application L{Tier} with which the
28 L{AEChooser} that fired this event is associated
29 @type aid: opaque
30 @ivar chooser: L{AEChooser} that fired this event
31 @type chooser: L{AEChooser}
32 @ivar kind: Kind of event, one of OK, CANCEL, or APPLY from L{AEChooser}
33 @type kind: integer
34 @ivar kwargs: Aribitrary data to be passed to the handler of this event
35 @type kwargs: dictionary
36 '''
37 Base.registerEventType('ChooserChange', False)
38 - def __init__(self, aid, chooser, kind, **kwargs):
39 '''
40 Stores important references.
41
42 @param aid: Unique identifier for the application L{Tier} with which the
43 L{AEChooser} that fired this event is associated
44 @type aid: opaque
45 @param chooser: L{AEChooser} that fired this event
46 @type chooser: L{AEChooser}
47 @param kind: Kind of event, one of OK, CANCEL, or APPLY from L{AEChooser}
48 @type kind: integer
49 '''
50 Base.AccessEngineEvent.__init__(self, focused=True, **kwargs)
51 self.aid = aid
52 self.kwargs = kwargs
53 self.kind = kind
54 self.chooser = chooser
55
57 '''
58 Returns a human readable representation of this event including its name,
59 action, and chooser.
60
61 @return: Information about this event
62 @rtype: string
63 '''
64 name = Base.AccessEngineEvent.__str__(self)
65 if self.kind == AEConstants.CHOOSER_OK:
66 action = 'ok'
67 elif self.kind == AEConstants.CHOOSER_CANCEL:
68 action = 'cancel'
69 elif self.kind == AEConstants.CHOOSER_APPLY:
70 action = 'apply'
71 else:
72 action = self.kind
73 return '%s:\n\tchooser: %s\n\taction: %s' % \
74 (name, self.chooser.getName(), action)
75
76 - def execute(self, tier_manager, **kwargs):
77 '''
78 Contacts the L{TierManager} and asks it to manage this chooser event.
79
80 @param tier_manager: TierManager that will handle the event
81 @type tier_manager: L{TierManager}
82 @param kwargs: Packed references to other managers not of interest here
83 @type kwargs: dictionary
84 @return: True to indicate the event executed properly
85 @rtype: boolean
86 '''
87 tier_manager.manageChooser(self)
88 return True
89
91 '''
92 Gets the L{AEChooser} ID that triggered this event. This information is
93 used to locate the L{Task} that should handle this event.
94
95 @return: ID of the chooser that fired the event
96 @rtype: integer
97 '''
98 return id(self.chooser)
99
101 '''
102 @return: Unique application ID identifying the top most container for the
103 source of this event (i.e. the application)
104 @rtype: opaque object
105 '''
106 return self.aid
107
109 '''
110 Fetches data out of this L{ChooserChange} for use by a L{Task.ChooserTask}.
111
112 @return: Dictionary of parameters to be passed to a L{Task.ChooserTask} as
113 follows:
114 - chooser: The chooser that fired the event
115 - kind: The kind of event
116 - any addition data in the L{kwargs} instance variable
117 @rtype: dictionary
118 '''
119 self.kwargs['chooser'] = self.chooser
120 self.kwargs['kind'] = self.kind
121 return self.kwargs
122