blob: 64729eab8ca4d8b3485ca22d934f7350a4151984 [file] [log] [blame]
Kurt B. Kaiserb1754452005-11-18 22:05:48 +00001"""
2MultiCall - a class which inherits its methods from a Tkinter widget (Text, for
3example), but enables multiple calls of functions per virtual event - all
4matching events will be called, not only the most specific one. This is done
5by wrapping the event functions - event_add, event_delete and event_info.
6MultiCall recognizes only a subset of legal event sequences. Sequences which
7are not recognized are treated by the original Tk handling mechanism. A
8more-specific event will be called before a less-specific event.
9
10The recognized sequences are complete one-event sequences (no emacs-style
11Ctrl-X Ctrl-C, no shortcuts like <3>), for all types of events.
12Key/Button Press/Release events can have modifiers.
13The recognized modifiers are Shift, Control, Option and Command for Mac, and
14Control, Alt, Shift, Meta/M for other platforms.
15
16For all events which were handled by MultiCall, a new member is added to the
17event instance passed to the binded functions - mc_type. This is one of the
18event type constants defined in this module (such as MC_KEYPRESS).
19For Key/Button events (which are handled by MultiCall and may receive
20modifiers), another member is added - mc_state. This member gives the state
21of the recognized modifiers, as a combination of the modifier constants
22also defined in this module (for example, MC_SHIFT).
23Using these members is absolutely portable.
24
25The order by which events are called is defined by these rules:
261. A more-specific event will be called before a less-specific event.
272. A recently-binded event will be called before a previously-binded event,
28 unless this conflicts with the first rule.
29Each function will be called at most once for each event.
30"""
31
32import sys
Kurt B. Kaiserb1754452005-11-18 22:05:48 +000033import re
Georg Brandl14fc4272008-05-17 18:39:55 +000034import tkinter
Ronald Oussoren827822e2009-02-12 15:01:44 +000035from idlelib import macosxSupport
Kurt B. Kaiserb1754452005-11-18 22:05:48 +000036
37# the event type constants, which define the meaning of mc_type
38MC_KEYPRESS=0; MC_KEYRELEASE=1; MC_BUTTONPRESS=2; MC_BUTTONRELEASE=3;
39MC_ACTIVATE=4; MC_CIRCULATE=5; MC_COLORMAP=6; MC_CONFIGURE=7;
40MC_DEACTIVATE=8; MC_DESTROY=9; MC_ENTER=10; MC_EXPOSE=11; MC_FOCUSIN=12;
41MC_FOCUSOUT=13; MC_GRAVITY=14; MC_LEAVE=15; MC_MAP=16; MC_MOTION=17;
42MC_MOUSEWHEEL=18; MC_PROPERTY=19; MC_REPARENT=20; MC_UNMAP=21; MC_VISIBILITY=22;
43# the modifier state constants, which define the meaning of mc_state
44MC_SHIFT = 1<<0; MC_CONTROL = 1<<2; MC_ALT = 1<<3; MC_META = 1<<5
45MC_OPTION = 1<<6; MC_COMMAND = 1<<7
46
47# define the list of modifiers, to be used in complex event types.
Ronald Oussoren827822e2009-02-12 15:01:44 +000048if macosxSupport.runningAsOSXApp():
Kurt B. Kaiserb1754452005-11-18 22:05:48 +000049 _modifiers = (("Shift",), ("Control",), ("Option",), ("Command",))
50 _modifier_masks = (MC_SHIFT, MC_CONTROL, MC_OPTION, MC_COMMAND)
51else:
52 _modifiers = (("Control",), ("Alt",), ("Shift",), ("Meta", "M"))
53 _modifier_masks = (MC_CONTROL, MC_ALT, MC_SHIFT, MC_META)
54
55# a dictionary to map a modifier name into its number
56_modifier_names = dict([(name, number)
57 for number in range(len(_modifiers))
58 for name in _modifiers[number]])
59
60# A binder is a class which binds functions to one type of event. It has two
61# methods: bind and unbind, which get a function and a parsed sequence, as
62# returned by _parse_sequence(). There are two types of binders:
63# _SimpleBinder handles event types with no modifiers and no detail.
64# No Python functions are called when no events are binded.
65# _ComplexBinder handles event types with modifiers and a detail.
66# A Python function is called each time an event is generated.
67
68class _SimpleBinder:
69 def __init__(self, type, widget, widgetinst):
70 self.type = type
71 self.sequence = '<'+_types[type][0]+'>'
72 self.widget = widget
73 self.widgetinst = widgetinst
74 self.bindedfuncs = []
75 self.handlerid = None
76
77 def bind(self, triplet, func):
78 if not self.handlerid:
79 def handler(event, l = self.bindedfuncs, mc_type = self.type):
80 event.mc_type = mc_type
81 wascalled = {}
82 for i in range(len(l)-1, -1, -1):
83 func = l[i]
84 if func not in wascalled:
85 wascalled[func] = True
86 r = func(event)
87 if r:
88 return r
89 self.handlerid = self.widget.bind(self.widgetinst,
90 self.sequence, handler)
91 self.bindedfuncs.append(func)
92
93 def unbind(self, triplet, func):
94 self.bindedfuncs.remove(func)
95 if not self.bindedfuncs:
96 self.widget.unbind(self.widgetinst, self.sequence, self.handlerid)
97 self.handlerid = None
98
99 def __del__(self):
100 if self.handlerid:
101 self.widget.unbind(self.widgetinst, self.sequence, self.handlerid)
102
103# An int in range(1 << len(_modifiers)) represents a combination of modifiers
104# (if the least significent bit is on, _modifiers[0] is on, and so on).
105# _state_subsets gives for each combination of modifiers, or *state*,
106# a list of the states which are a subset of it. This list is ordered by the
107# number of modifiers is the state - the most specific state comes first.
108_states = range(1 << len(_modifiers))
Guido van Rossum89da5d72006-08-22 00:21:25 +0000109_state_names = [''.join(m[0]+'-'
110 for i, m in enumerate(_modifiers)
111 if (1 << i) & s)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000112 for s in _states]
Guido van Rossumb5a755e2007-07-18 18:15:48 +0000113
114def expand_substates(states):
115 '''For each item of states return a list containing all combinations of
116 that item with individual bits reset, sorted by the number of set bits.
117 '''
118 def nbits(n):
119 "number of bits set in n base 2"
120 nb = 0
121 while n:
122 n, rem = divmod(n, 2)
123 nb += rem
124 return nb
125 statelist = []
126 for state in states:
127 substates = list(set(state & x for x in states))
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +0000128 substates.sort(key=nbits, reverse=True)
Guido van Rossumb5a755e2007-07-18 18:15:48 +0000129 statelist.append(substates)
130 return statelist
131
132_state_subsets = expand_substates(_states)
133
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000134# _state_codes gives for each state, the portable code to be passed as mc_state
Guido van Rossum89da5d72006-08-22 00:21:25 +0000135_state_codes = []
136for s in _states:
137 r = 0
138 for i in range(len(_modifiers)):
139 if (1 << i) & s:
140 r |= _modifier_masks[i]
141 _state_codes.append(r)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000142
143class _ComplexBinder:
144 # This class binds many functions, and only unbinds them when it is deleted.
145 # self.handlerids is the list of seqs and ids of binded handler functions.
146 # The binded functions sit in a dictionary of lists of lists, which maps
147 # a detail (or None) and a state into a list of functions.
148 # When a new detail is discovered, handlers for all the possible states
149 # are binded.
150
151 def __create_handler(self, lists, mc_type, mc_state):
152 def handler(event, lists = lists,
153 mc_type = mc_type, mc_state = mc_state,
154 ishandlerrunning = self.ishandlerrunning,
155 doafterhandler = self.doafterhandler):
156 ishandlerrunning[:] = [True]
157 event.mc_type = mc_type
158 event.mc_state = mc_state
159 wascalled = {}
160 r = None
161 for l in lists:
162 for i in range(len(l)-1, -1, -1):
163 func = l[i]
164 if func not in wascalled:
165 wascalled[func] = True
166 r = l[i](event)
167 if r:
168 break
169 if r:
170 break
171 ishandlerrunning[:] = []
172 # Call all functions in doafterhandler and remove them from list
Roger Serwy420e2d82013-03-31 15:53:08 -0500173 for f in doafterhandler:
174 f()
175 doafterhandler[:] = []
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000176 if r:
177 return r
178 return handler
179
180 def __init__(self, type, widget, widgetinst):
181 self.type = type
182 self.typename = _types[type][0]
183 self.widget = widget
184 self.widgetinst = widgetinst
185 self.bindedfuncs = {None: [[] for s in _states]}
186 self.handlerids = []
187 # we don't want to change the lists of functions while a handler is
188 # running - it will mess up the loop and anyway, we usually want the
189 # change to happen from the next event. So we have a list of functions
190 # for the handler to run after it finishes calling the binded functions.
191 # It calls them only once.
192 # ishandlerrunning is a list. An empty one means no, otherwise - yes.
193 # this is done so that it would be mutable.
194 self.ishandlerrunning = []
195 self.doafterhandler = []
196 for s in _states:
197 lists = [self.bindedfuncs[None][i] for i in _state_subsets[s]]
198 handler = self.__create_handler(lists, type, _state_codes[s])
199 seq = '<'+_state_names[s]+self.typename+'>'
200 self.handlerids.append((seq, self.widget.bind(self.widgetinst,
201 seq, handler)))
202
203 def bind(self, triplet, func):
Guido van Rossum811c4e02006-08-22 15:45:46 +0000204 if triplet[2] not in self.bindedfuncs:
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000205 self.bindedfuncs[triplet[2]] = [[] for s in _states]
206 for s in _states:
207 lists = [ self.bindedfuncs[detail][i]
208 for detail in (triplet[2], None)
209 for i in _state_subsets[s] ]
210 handler = self.__create_handler(lists, self.type,
211 _state_codes[s])
212 seq = "<%s%s-%s>"% (_state_names[s], self.typename, triplet[2])
213 self.handlerids.append((seq, self.widget.bind(self.widgetinst,
214 seq, handler)))
215 doit = lambda: self.bindedfuncs[triplet[2]][triplet[0]].append(func)
216 if not self.ishandlerrunning:
217 doit()
218 else:
219 self.doafterhandler.append(doit)
220
221 def unbind(self, triplet, func):
222 doit = lambda: self.bindedfuncs[triplet[2]][triplet[0]].remove(func)
223 if not self.ishandlerrunning:
224 doit()
225 else:
226 self.doafterhandler.append(doit)
227
228 def __del__(self):
229 for seq, id in self.handlerids:
230 self.widget.unbind(self.widgetinst, seq, id)
231
232# define the list of event types to be handled by MultiEvent. the order is
233# compatible with the definition of event type constants.
234_types = (
235 ("KeyPress", "Key"), ("KeyRelease",), ("ButtonPress", "Button"),
236 ("ButtonRelease",), ("Activate",), ("Circulate",), ("Colormap",),
237 ("Configure",), ("Deactivate",), ("Destroy",), ("Enter",), ("Expose",),
238 ("FocusIn",), ("FocusOut",), ("Gravity",), ("Leave",), ("Map",),
239 ("Motion",), ("MouseWheel",), ("Property",), ("Reparent",), ("Unmap",),
240 ("Visibility",),
241)
242
243# which binder should be used for every event type?
244_binder_classes = (_ComplexBinder,) * 4 + (_SimpleBinder,) * (len(_types)-4)
245
246# A dictionary to map a type name into its number
247_type_names = dict([(name, number)
248 for number in range(len(_types))
249 for name in _types[number]])
250
251_keysym_re = re.compile(r"^\w+$")
252_button_re = re.compile(r"^[1-5]$")
253def _parse_sequence(sequence):
254 """Get a string which should describe an event sequence. If it is
255 successfully parsed as one, return a tuple containing the state (as an int),
256 the event type (as an index of _types), and the detail - None if none, or a
257 string if there is one. If the parsing is unsuccessful, return None.
258 """
259 if not sequence or sequence[0] != '<' or sequence[-1] != '>':
260 return None
Kurt B. Kaiser4d9620a2007-08-22 19:41:43 +0000261 words = sequence[1:-1].split('-')
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000262 modifiers = 0
263 while words and words[0] in _modifier_names:
264 modifiers |= 1 << _modifier_names[words[0]]
265 del words[0]
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000266 if words and words[0] in _type_names:
267 type = _type_names[words[0]]
268 del words[0]
269 else:
270 return None
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000271 if _binder_classes[type] is _SimpleBinder:
272 if modifiers or words:
273 return None
274 else:
275 detail = None
276 else:
277 # _ComplexBinder
278 if type in [_type_names[s] for s in ("KeyPress", "KeyRelease")]:
279 type_re = _keysym_re
280 else:
281 type_re = _button_re
282
283 if not words:
284 detail = None
285 elif len(words) == 1 and type_re.match(words[0]):
286 detail = words[0]
287 else:
288 return None
289
290 return modifiers, type, detail
291
292def _triplet_to_sequence(triplet):
293 if triplet[2]:
294 return '<'+_state_names[triplet[0]]+_types[triplet[1]][0]+'-'+ \
295 triplet[2]+'>'
296 else:
297 return '<'+_state_names[triplet[0]]+_types[triplet[1]][0]+'>'
298
299_multicall_dict = {}
300def MultiCallCreator(widget):
301 """Return a MultiCall class which inherits its methods from the
302 given widget class (for example, Tkinter.Text). This is used
303 instead of a templating mechanism.
304 """
305 if widget in _multicall_dict:
306 return _multicall_dict[widget]
307
308 class MultiCall (widget):
Georg Brandl14fc4272008-05-17 18:39:55 +0000309 assert issubclass(widget, tkinter.Misc)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000310
311 def __init__(self, *args, **kwargs):
Neal Norwitzd9108552006-03-17 08:00:19 +0000312 widget.__init__(self, *args, **kwargs)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000313 # a dictionary which maps a virtual event to a tuple with:
314 # 0. the function binded
315 # 1. a list of triplets - the sequences it is binded to
316 self.__eventinfo = {}
317 self.__binders = [_binder_classes[i](i, widget, self)
318 for i in range(len(_types))]
319
320 def bind(self, sequence=None, func=None, add=None):
Kurt B. Kaiserea03c112007-08-22 18:57:50 +0000321 #print("bind(%s, %s, %s)" % (sequence, func, add),
322 # file=sys.__stderr__)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000323 if type(sequence) is str and len(sequence) > 2 and \
324 sequence[:2] == "<<" and sequence[-2:] == ">>":
325 if sequence in self.__eventinfo:
326 ei = self.__eventinfo[sequence]
327 if ei[0] is not None:
328 for triplet in ei[1]:
329 self.__binders[triplet[1]].unbind(triplet, ei[0])
330 ei[0] = func
331 if ei[0] is not None:
332 for triplet in ei[1]:
333 self.__binders[triplet[1]].bind(triplet, func)
334 else:
335 self.__eventinfo[sequence] = [func, []]
336 return widget.bind(self, sequence, func, add)
337
338 def unbind(self, sequence, funcid=None):
339 if type(sequence) is str and len(sequence) > 2 and \
340 sequence[:2] == "<<" and sequence[-2:] == ">>" and \
341 sequence in self.__eventinfo:
342 func, triplets = self.__eventinfo[sequence]
343 if func is not None:
344 for triplet in triplets:
345 self.__binders[triplet[1]].unbind(triplet, func)
346 self.__eventinfo[sequence][0] = None
347 return widget.unbind(self, sequence, funcid)
348
349 def event_add(self, virtual, *sequences):
Kurt B. Kaiserea03c112007-08-22 18:57:50 +0000350 #print("event_add(%s, %s)" % (repr(virtual), repr(sequences)),
351 # file=sys.__stderr__)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000352 if virtual not in self.__eventinfo:
353 self.__eventinfo[virtual] = [None, []]
354
355 func, triplets = self.__eventinfo[virtual]
356 for seq in sequences:
357 triplet = _parse_sequence(seq)
358 if triplet is None:
Kurt B. Kaiserea03c112007-08-22 18:57:50 +0000359 #print("Tkinter event_add(%s)" % seq, file=sys.__stderr__)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000360 widget.event_add(self, virtual, seq)
361 else:
362 if func is not None:
363 self.__binders[triplet[1]].bind(triplet, func)
364 triplets.append(triplet)
365
366 def event_delete(self, virtual, *sequences):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000367 if virtual not in self.__eventinfo:
368 return
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000369 func, triplets = self.__eventinfo[virtual]
370 for seq in sequences:
371 triplet = _parse_sequence(seq)
372 if triplet is None:
Kurt B. Kaiserea03c112007-08-22 18:57:50 +0000373 #print("Tkinter event_delete: %s" % seq, file=sys.__stderr__)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000374 widget.event_delete(self, virtual, seq)
375 else:
376 if func is not None:
377 self.__binders[triplet[1]].unbind(triplet, func)
378 triplets.remove(triplet)
379
380 def event_info(self, virtual=None):
381 if virtual is None or virtual not in self.__eventinfo:
382 return widget.event_info(self, virtual)
383 else:
384 return tuple(map(_triplet_to_sequence,
385 self.__eventinfo[virtual][1])) + \
386 widget.event_info(self, virtual)
387
388 def __del__(self):
389 for virtual in self.__eventinfo:
390 func, triplets = self.__eventinfo[virtual]
391 if func:
392 for triplet in triplets:
393 self.__binders[triplet[1]].unbind(triplet, func)
394
395
396 _multicall_dict[widget] = MultiCall
397 return MultiCall
398
399if __name__ == "__main__":
400 # Test
Georg Brandl14fc4272008-05-17 18:39:55 +0000401 root = tkinter.Tk()
402 text = MultiCallCreator(tkinter.Text)(root)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000403 text.pack()
404 def bindseq(seq, n=[0]):
405 def handler(event):
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000406 print(seq)
Kurt B. Kaiserb1754452005-11-18 22:05:48 +0000407 text.bind("<<handler%d>>"%n[0], handler)
408 text.event_add("<<handler%d>>"%n[0], seq)
409 n[0] += 1
410 bindseq("<Key>")
411 bindseq("<Control-Key>")
412 bindseq("<Alt-Key-a>")
413 bindseq("<Control-Key-a>")
414 bindseq("<Alt-Control-Key-a>")
415 bindseq("<Key-b>")
416 bindseq("<Control-Button-1>")
417 bindseq("<Alt-Button-1>")
418 bindseq("<FocusOut>")
419 bindseq("<Enter>")
420 bindseq("<Leave>")
421 root.mainloop()