Python code coverage for Lib/idlelib/MultiCall.py

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