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