Python code coverage for Lib/lib-tk/ttk.py

#	count	content
1	n/a	"""Ttk wrapper.
2	n/a
3	n/a	This module provides classes to allow using Tk themed widget set.
4	n/a
5	n/a	Ttk is based on a revised and enhanced version of
6	n/a	TIP #48 (http://tip.tcl.tk/48) specified style engine.
7	n/a
8	n/a	Its basic idea is to separate, to the extent possible, the code
9	n/a	implementing a widget's behavior from the code implementing its
10	n/a	appearance. Widget class bindings are primarily responsible for
11	n/a	maintaining the widget state and invoking callbacks, all aspects
12	n/a	of the widgets appearance lies at Themes.
13	n/a	"""
14	n/a
15	n/a	__version__ = "0.3.1"
16	n/a
17	n/a	__author__ = "Guilherme Polo <ggpolo@gmail.com>"
18	n/a
19	n/a	__all__ = ["Button", "Checkbutton", "Combobox", "Entry", "Frame", "Label",
20	n/a	"Labelframe", "LabelFrame", "Menubutton", "Notebook", "Panedwindow",
21	n/a	"PanedWindow", "Progressbar", "Radiobutton", "Scale", "Scrollbar",
22	n/a	"Separator", "Sizegrip", "Style", "Treeview",
23	n/a	# Extensions
24	n/a	"LabeledScale", "OptionMenu",
25	n/a	# functions
26	n/a	"tclobjs_to_py", "setup_master"]
27	n/a
28	n/a	import Tkinter
29	n/a
30	n/a	_flatten = Tkinter._flatten
31	n/a
32	n/a	# Verify if Tk is new enough to not need the Tile package
33	n/a	_REQUIRE_TILE = True if Tkinter.TkVersion < 8.5 else False
34	n/a
35	n/a	def _load_tile(master):
36	n/a	if _REQUIRE_TILE:
37	n/a	import os
38	n/a	tilelib = os.environ.get('TILE_LIBRARY')
39	n/a	if tilelib:
40	n/a	# append custom tile path to the list of directories that
41	n/a	# Tcl uses when attempting to resolve packages with the package
42	n/a	# command
43	n/a	master.tk.eval(
44	n/a	'global auto_path; '
45	n/a	'lappend auto_path {%s}' % tilelib)
46	n/a
47	n/a	master.tk.eval('package require tile') # TclError may be raised here
48	n/a	master._tile_loaded = True
49	n/a
50	n/a	def _format_optdict(optdict, script=False, ignore=None):
51	n/a	"""Formats optdict to a tuple to pass it to tk.call.
52	n/a
53	n/a	E.g. (script=False):
54	n/a	{'foreground': 'blue', 'padding': [1, 2, 3, 4]} returns:
55	n/a	('-foreground', 'blue', '-padding', '1 2 3 4')"""
56	n/a	format = "%s" if not script else "{%s}"
57	n/a
58	n/a	opts = []
59	n/a	for opt, value in optdict.iteritems():
60	n/a	if ignore and opt in ignore:
61	n/a	continue
62	n/a
63	n/a	if isinstance(value, (list, tuple)):
64	n/a	v = []
65	n/a	for val in value:
66	n/a	if isinstance(val, basestring):
67	n/a	v.append(unicode(val) if val else '{}')
68	n/a	else:
69	n/a	v.append(str(val))
70	n/a
71	n/a	# format v according to the script option, but also check for
72	n/a	# space in any value in v in order to group them correctly
73	n/a	value = format % ' '.join(
74	n/a	('{%s}' if ' ' in val else '%s') % val for val in v)
75	n/a
76	n/a	if script and value == '':
77	n/a	value = '{}' # empty string in Python is equivalent to {} in Tcl
78	n/a
79	n/a	opts.append(("-%s" % opt, value))
80	n/a
81	n/a	# Remember: _flatten skips over None
82	n/a	return _flatten(opts)
83	n/a
84	n/a	def _format_mapdict(mapdict, script=False):
85	n/a	"""Formats mapdict to pass it to tk.call.
86	n/a
87	n/a	E.g. (script=False):
88	n/a	{'expand': [('active', 'selected', 'grey'), ('focus', [1, 2, 3, 4])]}
89	n/a
90	n/a	returns:
91	n/a
92	n/a	('-expand', '{active selected} grey focus {1, 2, 3, 4}')"""
93	n/a	# if caller passes a Tcl script to tk.call, all the values need to
94	n/a	# be grouped into words (arguments to a command in Tcl dialect)
95	n/a	format = "%s" if not script else "{%s}"
96	n/a
97	n/a	opts = []
98	n/a	for opt, value in mapdict.iteritems():
99	n/a
100	n/a	opt_val = []
101	n/a	# each value in mapdict is expected to be a sequence, where each item
102	n/a	# is another sequence containing a state (or several) and a value
103	n/a	for statespec in value:
104	n/a	state, val = statespec[:-1], statespec[-1]
105	n/a
106	n/a	if len(state) > 1: # group multiple states
107	n/a	state = "{%s}" % ' '.join(state)
108	n/a	else: # single state
109	n/a	# if it is empty (something that evaluates to False), then
110	n/a	# format it to Tcl code to denote the "normal" state
111	n/a	state = state[0] or '{}'
112	n/a
113	n/a	if isinstance(val, (list, tuple)): # val needs to be grouped
114	n/a	val = "{%s}" % ' '.join(map(str, val))
115	n/a
116	n/a	opt_val.append("%s %s" % (state, val))
117	n/a
118	n/a	opts.append(("-%s" % opt, format % ' '.join(opt_val)))
119	n/a
120	n/a	return _flatten(opts)
121	n/a
122	n/a	def _format_elemcreate(etype, script=False, args, *kw):
123	n/a	"""Formats args and kw according to the given element factory etype."""
124	n/a	spec = None
125	n/a	opts = ()
126	n/a	if etype in ("image", "vsapi"):
127	n/a	if etype == "image": # define an element based on an image
128	n/a	# first arg should be the default image name
129	n/a	iname = args[0]
130	n/a	# next args, if any, are statespec/value pairs which is almost
131	n/a	# a mapdict, but we just need the value
132	n/a	imagespec = _format_mapdict({None: args[1:]})[1]
133	n/a	spec = "%s %s" % (iname, imagespec)
134	n/a
135	n/a	else:
136	n/a	# define an element whose visual appearance is drawn using the
137	n/a	# Microsoft Visual Styles API which is responsible for the
138	n/a	# themed styles on Windows XP and Vista.
139	n/a	# Availability: Tk 8.6, Windows XP and Vista.
140	n/a	class_name, part_id = args[:2]
141	n/a	statemap = _format_mapdict({None: args[2:]})[1]
142	n/a	spec = "%s %s %s" % (class_name, part_id, statemap)
143	n/a
144	n/a	opts = _format_optdict(kw, script)
145	n/a
146	n/a	elif etype == "from": # clone an element
147	n/a	# it expects a themename and optionally an element to clone from,
148	n/a	# otherwise it will clone {} (empty element)
149	n/a	spec = args[0] # theme name
150	n/a	if len(args) > 1: # elementfrom specified
151	n/a	opts = (args[1], )
152	n/a
153	n/a	if script:
154	n/a	spec = '{%s}' % spec
155	n/a	opts = ' '.join(map(str, opts))
156	n/a
157	n/a	return spec, opts
158	n/a
159	n/a	def _format_layoutlist(layout, indent=0, indent_size=2):
160	n/a	"""Formats a layout list so we can pass the result to ttk::style
161	n/a	layout and ttk::style settings. Note that the layout doesn't has to
162	n/a	be a list necessarily.
163	n/a
164	n/a	E.g.:
165	n/a	[("Menubutton.background", None),
166	n/a	("Menubutton.button", {"children":
167	n/a	[("Menubutton.focus", {"children":
168	n/a	[("Menubutton.padding", {"children":
169	n/a	[("Menubutton.label", {"side": "left", "expand": 1})]
170	n/a	})]
171	n/a	})]
172	n/a	}),
173	n/a	("Menubutton.indicator", {"side": "right"})
174	n/a	]
175	n/a
176	n/a	returns:
177	n/a
178	n/a	Menubutton.background
179	n/a	Menubutton.button -children {
180	n/a	Menubutton.focus -children {
181	n/a	Menubutton.padding -children {
182	n/a	Menubutton.label -side left -expand 1
183	n/a	}
184	n/a	}
185	n/a	}
186	n/a	Menubutton.indicator -side right"""
187	n/a	script = []
188	n/a
189	n/a	for layout_elem in layout:
190	n/a	elem, opts = layout_elem
191	n/a	opts = opts or {}
192	n/a	fopts = ' '.join(map(str, _format_optdict(opts, True, "children")))
193	n/a	head = "%s%s%s" % (' ' * indent, elem, (" %s" % fopts) if fopts else '')
194	n/a
195	n/a	if "children" in opts:
196	n/a	script.append(head + " -children {")
197	n/a	indent += indent_size
198	n/a	newscript, indent = _format_layoutlist(opts['children'], indent,
199	n/a	indent_size)
200	n/a	script.append(newscript)
201	n/a	indent -= indent_size
202	n/a	script.append('%s}' % (' ' * indent))
203	n/a	else:
204	n/a	script.append(head)
205	n/a
206	n/a	return '\n'.join(script), indent
207	n/a
208	n/a	def _script_from_settings(settings):
209	n/a	"""Returns an appropriate script, based on settings, according to
210	n/a	theme_settings definition to be used by theme_settings and
211	n/a	theme_create."""
212	n/a	script = []
213	n/a	# a script will be generated according to settings passed, which
214	n/a	# will then be evaluated by Tcl
215	n/a	for name, opts in settings.iteritems():
216	n/a	# will format specific keys according to Tcl code
217	n/a	if opts.get('configure'): # format 'configure'
218	n/a	s = ' '.join(map(unicode, _format_optdict(opts['configure'], True)))
219	n/a	script.append("ttk::style configure %s %s;" % (name, s))
220	n/a
221	n/a	if opts.get('map'): # format 'map'
222	n/a	s = ' '.join(map(unicode, _format_mapdict(opts['map'], True)))
223	n/a	script.append("ttk::style map %s %s;" % (name, s))
224	n/a
225	n/a	if 'layout' in opts: # format 'layout' which may be empty
226	n/a	if not opts['layout']:
227	n/a	s = 'null' # could be any other word, but this one makes sense
228	n/a	else:
229	n/a	s, _ = _format_layoutlist(opts['layout'])
230	n/a	script.append("ttk::style layout %s {\n%s\n}" % (name, s))
231	n/a
232	n/a	if opts.get('element create'): # format 'element create'
233	n/a	eopts = opts['element create']
234	n/a	etype = eopts[0]
235	n/a
236	n/a	# find where args end, and where kwargs start
237	n/a	argc = 1 # etype was the first one
238	n/a	while argc < len(eopts) and not hasattr(eopts[argc], 'iteritems'):
239	n/a	argc += 1
240	n/a
241	n/a	elemargs = eopts[1:argc]
242	n/a	elemkw = eopts[argc] if argc < len(eopts) and eopts[argc] else {}
243	n/a	spec, opts = _format_elemcreate(etype, True, elemargs, *elemkw)
244	n/a
245	n/a	script.append("ttk::style element create %s %s %s %s" % (
246	n/a	name, etype, spec, opts))
247	n/a
248	n/a	return '\n'.join(script)
249	n/a
250	n/a	def _dict_from_tcltuple(ttuple, cut_minus=True):
251	n/a	"""Break tuple in pairs, format it properly, then build the return
252	n/a	dict. If cut_minus is True, the supposed '-' prefixing options will
253	n/a	be removed.
254	n/a
255	n/a	ttuple is expected to contain an even number of elements."""
256	n/a	opt_start = 1 if cut_minus else 0
257	n/a
258	n/a	retdict = {}
259	n/a	it = iter(ttuple)
260	n/a	for opt, val in zip(it, it):
261	n/a	retdict[str(opt)[opt_start:]] = val
262	n/a
263	n/a	return tclobjs_to_py(retdict)
264	n/a
265	n/a	def _list_from_statespec(stuple):
266	n/a	"""Construct a list from the given statespec tuple according to the
267	n/a	accepted statespec accepted by _format_mapdict."""
268	n/a	nval = []
269	n/a	for val in stuple:
270	n/a	typename = getattr(val, 'typename', None)
271	n/a	if typename is None:
272	n/a	nval.append(val)
273	n/a	else: # this is a Tcl object
274	n/a	val = str(val)
275	n/a	if typename == 'StateSpec':
276	n/a	val = val.split()
277	n/a	nval.append(val)
278	n/a
279	n/a	it = iter(nval)
280	n/a	return [_flatten(spec) for spec in zip(it, it)]
281	n/a
282	n/a	def _list_from_layouttuple(ltuple):
283	n/a	"""Construct a list from the tuple returned by ttk::layout, this is
284	n/a	somewhat the reverse of _format_layoutlist."""
285	n/a	res = []
286	n/a
287	n/a	indx = 0
288	n/a	while indx < len(ltuple):
289	n/a	name = ltuple[indx]
290	n/a	opts = {}
291	n/a	res.append((name, opts))
292	n/a	indx += 1
293	n/a
294	n/a	while indx < len(ltuple): # grab name's options
295	n/a	opt, val = ltuple[indx:indx + 2]
296	n/a	if not opt.startswith('-'): # found next name
297	n/a	break
298	n/a
299	n/a	opt = opt[1:] # remove the '-' from the option
300	n/a	indx += 2
301	n/a
302	n/a	if opt == 'children':
303	n/a	val = _list_from_layouttuple(val)
304	n/a
305	n/a	opts[opt] = val
306	n/a
307	n/a	return res
308	n/a
309	n/a	def _val_or_dict(options, func, *args):
310	n/a	"""Format options then call func with args and options and return
311	n/a	the appropriate result.
312	n/a
313	n/a	If no option is specified, a dict is returned. If a option is
314	n/a	specified with the None value, the value for that option is returned.
315	n/a	Otherwise, the function just sets the passed options and the caller
316	n/a	shouldn't be expecting a return value anyway."""
317	n/a	options = _format_optdict(options)
318	n/a	res = func(*(args + options))
319	n/a
320	n/a	if len(options) % 2: # option specified without a value, return its value
321	n/a	return res
322	n/a
323	n/a	return _dict_from_tcltuple(res)
324	n/a
325	n/a	def _convert_stringval(value):
326	n/a	"""Converts a value to, hopefully, a more appropriate Python object."""
327	n/a	value = unicode(value)
328	n/a	try:
329	n/a	value = int(value)
330	n/a	except (ValueError, TypeError):
331	n/a	pass
332	n/a
333	n/a	return value
334	n/a
335	n/a	def tclobjs_to_py(adict):
336	n/a	"""Returns adict with its values converted from Tcl objects to Python
337	n/a	objects."""
338	n/a	for opt, val in adict.iteritems():
339	n/a	if val and hasattr(val, '__len__') and not isinstance(val, basestring):
340	n/a	if getattr(val[0], 'typename', None) == 'StateSpec':
341	n/a	val = _list_from_statespec(val)
342	n/a	else:
343	n/a	val = map(_convert_stringval, val)
344	n/a
345	n/a	elif hasattr(val, 'typename'): # some other (single) Tcl object
346	n/a	val = _convert_stringval(val)
347	n/a
348	n/a	adict[opt] = val
349	n/a
350	n/a	return adict
351	n/a
352	n/a	def setup_master(master=None):
353	n/a	"""If master is not None, itself is returned. If master is None,
354	n/a	the default master is returned if there is one, otherwise a new
355	n/a	master is created and returned.
356	n/a
357	n/a	If it is not allowed to use the default root and master is None,
358	n/a	RuntimeError is raised."""
359	n/a	if master is None:
360	n/a	if Tkinter._support_default_root:
361	n/a	master = Tkinter._default_root or Tkinter.Tk()
362	n/a	else:
363	n/a	raise RuntimeError(
364	n/a	"No master specified and Tkinter is "
365	n/a	"configured to not support default root")
366	n/a	return master
367	n/a
368	n/a
369	n/a	class Style(object):
370	n/a	"""Manipulate style database."""
371	n/a
372	n/a	_name = "ttk::style"
373	n/a
374	n/a	def __init__(self, master=None):
375	n/a	master = setup_master(master)
376	n/a
377	n/a	if not getattr(master, '_tile_loaded', False):
378	n/a	# Load tile now, if needed
379	n/a	_load_tile(master)
380	n/a
381	n/a	self.master = master
382	n/a	self.tk = self.master.tk
383	n/a
384	n/a
385	n/a	def configure(self, style, query_opt=None, **kw):
386	n/a	"""Query or sets the default value of the specified option(s) in
387	n/a	style.
388	n/a
389	n/a	Each key in kw is an option and each value is either a string or
390	n/a	a sequence identifying the value for that option."""
391	n/a	if query_opt is not None:
392	n/a	kw[query_opt] = None
393	n/a	return _val_or_dict(kw, self.tk.call, self._name, "configure", style)
394	n/a
395	n/a
396	n/a	def map(self, style, query_opt=None, **kw):
397	n/a	"""Query or sets dynamic values of the specified option(s) in
398	n/a	style.
399	n/a
400	n/a	Each key in kw is an option and each value should be a list or a
401	n/a	tuple (usually) containing statespecs grouped in tuples, or list,
402	n/a	or something else of your preference. A statespec is compound of
403	n/a	one or more states and then a value."""
404	n/a	if query_opt is not None:
405	n/a	return _list_from_statespec(
406	n/a	self.tk.call(self._name, "map", style, '-%s' % query_opt))
407	n/a
408	n/a	return _dict_from_tcltuple(
409	n/a	self.tk.call(self._name, "map", style, *(_format_mapdict(kw))))
410	n/a
411	n/a
412	n/a	def lookup(self, style, option, state=None, default=None):
413	n/a	"""Returns the value specified for option in style.
414	n/a
415	n/a	If state is specified it is expected to be a sequence of one
416	n/a	or more states. If the default argument is set, it is used as
417	n/a	a fallback value in case no specification for option is found."""
418	n/a	state = ' '.join(state) if state else ''
419	n/a
420	n/a	return self.tk.call(self._name, "lookup", style, '-%s' % option,
421	n/a	state, default)
422	n/a
423	n/a
424	n/a	def layout(self, style, layoutspec=None):
425	n/a	"""Define the widget layout for given style. If layoutspec is
426	n/a	omitted, return the layout specification for given style.
427	n/a
428	n/a	layoutspec is expected to be a list or an object different than
429	n/a	None that evaluates to False if you want to "turn off" that style.
430	n/a	If it is a list (or tuple, or something else), each item should be
431	n/a	a tuple where the first item is the layout name and the second item
432	n/a	should have the format described below:
433	n/a
434	n/a	LAYOUTS
435	n/a
436	n/a	A layout can contain the value None, if takes no options, or
437	n/a	a dict of options specifying how to arrange the element.
438	n/a	The layout mechanism uses a simplified version of the pack
439	n/a	geometry manager: given an initial cavity, each element is
440	n/a	allocated a parcel. Valid options/values are:
441	n/a
442	n/a	side: whichside
443	n/a	Specifies which side of the cavity to place the
444	n/a	element; one of top, right, bottom or left. If
445	n/a	omitted, the element occupies the entire cavity.
446	n/a
447	n/a	sticky: nswe
448	n/a	Specifies where the element is placed inside its
449	n/a	allocated parcel.
450	n/a
451	n/a	children: [sublayout... ]
452	n/a	Specifies a list of elements to place inside the
453	n/a	element. Each element is a tuple (or other sequence)
454	n/a	where the first item is the layout name, and the other
455	n/a	is a LAYOUT."""
456	n/a	lspec = None
457	n/a	if layoutspec:
458	n/a	lspec = _format_layoutlist(layoutspec)[0]
459	n/a	elif layoutspec is not None: # will disable the layout ({}, '', etc)
460	n/a	lspec = "null" # could be any other word, but this may make sense
461	n/a	# when calling layout(style) later
462	n/a
463	n/a	return _list_from_layouttuple(
464	n/a	self.tk.call(self._name, "layout", style, lspec))
465	n/a
466	n/a
467	n/a	def element_create(self, elementname, etype, args, *kw):
468	n/a	"""Create a new element in the current theme of given etype."""
469	n/a	spec, opts = _format_elemcreate(etype, False, args, *kw)
470	n/a	self.tk.call(self._name, "element", "create", elementname, etype,
471	n/a	spec, *opts)
472	n/a
473	n/a
474	n/a	def element_names(self):
475	n/a	"""Returns the list of elements defined in the current theme."""
476	n/a	return self.tk.call(self._name, "element", "names")
477	n/a
478	n/a
479	n/a	def element_options(self, elementname):
480	n/a	"""Return the list of elementname's options."""
481	n/a	return self.tk.call(self._name, "element", "options", elementname)
482	n/a
483	n/a
484	n/a	def theme_create(self, themename, parent=None, settings=None):
485	n/a	"""Creates a new theme.
486	n/a
487	n/a	It is an error if themename already exists. If parent is
488	n/a	specified, the new theme will inherit styles, elements and
489	n/a	layouts from the specified parent theme. If settings are present,
490	n/a	they are expected to have the same syntax used for theme_settings."""
491	n/a	script = _script_from_settings(settings) if settings else ''
492	n/a
493	n/a	if parent:
494	n/a	self.tk.call(self._name, "theme", "create", themename,
495	n/a	"-parent", parent, "-settings", script)
496	n/a	else:
497	n/a	self.tk.call(self._name, "theme", "create", themename,
498	n/a	"-settings", script)
499	n/a
500	n/a
501	n/a	def theme_settings(self, themename, settings):
502	n/a	"""Temporarily sets the current theme to themename, apply specified
503	n/a	settings and then restore the previous theme.
504	n/a
505	n/a	Each key in settings is a style and each value may contain the
506	n/a	keys 'configure', 'map', 'layout' and 'element create' and they
507	n/a	are expected to have the same format as specified by the methods
508	n/a	configure, map, layout and element_create respectively."""
509	n/a	script = _script_from_settings(settings)
510	n/a	self.tk.call(self._name, "theme", "settings", themename, script)
511	n/a
512	n/a
513	n/a	def theme_names(self):
514	n/a	"""Returns a list of all known themes."""
515	n/a	return self.tk.call(self._name, "theme", "names")
516	n/a
517	n/a
518	n/a	def theme_use(self, themename=None):
519	n/a	"""If themename is None, returns the theme in use, otherwise, set
520	n/a	the current theme to themename, refreshes all widgets and emits
521	n/a	a <<ThemeChanged>> event."""
522	n/a	if themename is None:
523	n/a	# Starting on Tk 8.6, checking this global is no longer needed
524	n/a	# since it allows doing self.tk.call(self._name, "theme", "use")
525	n/a	return self.tk.eval("return $ttk::currentTheme")
526	n/a
527	n/a	# using "ttk::setTheme" instead of "ttk::style theme use" causes
528	n/a	# the variable currentTheme to be updated, also, ttk::setTheme calls
529	n/a	# "ttk::style theme use" in order to change theme.
530	n/a	self.tk.call("ttk::setTheme", themename)
531	n/a
532	n/a
533	n/a	class Widget(Tkinter.Widget):
534	n/a	"""Base class for Tk themed widgets."""
535	n/a
536	n/a	def __init__(self, master, widgetname, kw=None):
537	n/a	"""Constructs a Ttk Widget with the parent master.
538	n/a
539	n/a	STANDARD OPTIONS
540	n/a
541	n/a	class, cursor, takefocus, style
542	n/a
543	n/a	SCROLLABLE WIDGET OPTIONS
544	n/a
545	n/a	xscrollcommand, yscrollcommand
546	n/a
547	n/a	LABEL WIDGET OPTIONS
548	n/a
549	n/a	text, textvariable, underline, image, compound, width
550	n/a
551	n/a	WIDGET STATES
552	n/a
553	n/a	active, disabled, focus, pressed, selected, background,
554	n/a	readonly, alternate, invalid
555	n/a	"""
556	n/a	master = setup_master(master)
557	n/a	if not getattr(master, '_tile_loaded', False):
558	n/a	# Load tile now, if needed
559	n/a	_load_tile(master)
560	n/a	Tkinter.Widget.__init__(self, master, widgetname, kw=kw)
561	n/a
562	n/a
563	n/a	def identify(self, x, y):
564	n/a	"""Returns the name of the element at position x, y, or the empty
565	n/a	string if the point does not lie within any element.
566	n/a
567	n/a	x and y are pixel coordinates relative to the widget."""
568	n/a	return self.tk.call(self._w, "identify", x, y)
569	n/a
570	n/a
571	n/a	def instate(self, statespec, callback=None, args, *kw):
572	n/a	"""Test the widget's state.
573	n/a
574	n/a	If callback is not specified, returns True if the widget state
575	n/a	matches statespec and False otherwise. If callback is specified,
576	n/a	then it will be invoked with args, *kw if the widget state
577	n/a	matches statespec. statespec is expected to be a sequence."""
578	n/a	ret = self.tk.call(self._w, "instate", ' '.join(statespec))
579	n/a	if ret and callback:
580	n/a	return callback(args, *kw)
581	n/a
582	n/a	return bool(ret)
583	n/a
584	n/a
585	n/a	def state(self, statespec=None):
586	n/a	"""Modify or inquire widget state.
587	n/a
588	n/a	Widget state is returned if statespec is None, otherwise it is
589	n/a	set according to the statespec flags and then a new state spec
590	n/a	is returned indicating which flags were changed. statespec is
591	n/a	expected to be a sequence."""
592	n/a	if statespec is not None:
593	n/a	statespec = ' '.join(statespec)
594	n/a
595	n/a	return self.tk.splitlist(str(self.tk.call(self._w, "state", statespec)))
596	n/a
597	n/a
598	n/a	class Button(Widget):
599	n/a	"""Ttk Button widget, displays a textual label and/or image, and
600	n/a	evaluates a command when pressed."""
601	n/a
602	n/a	def __init__(self, master=None, **kw):
603	n/a	"""Construct a Ttk Button widget with the parent master.
604	n/a
605	n/a	STANDARD OPTIONS
606	n/a
607	n/a	class, compound, cursor, image, state, style, takefocus,
608	n/a	text, textvariable, underline, width
609	n/a
610	n/a	WIDGET-SPECIFIC OPTIONS
611	n/a
612	n/a	command, default, width
613	n/a	"""
614	n/a	Widget.__init__(self, master, "ttk::button", kw)
615	n/a
616	n/a
617	n/a	def invoke(self):
618	n/a	"""Invokes the command associated with the button."""
619	n/a	return self.tk.call(self._w, "invoke")
620	n/a
621	n/a
622	n/a	class Checkbutton(Widget):
623	n/a	"""Ttk Checkbutton widget which is either in on- or off-state."""
624	n/a
625	n/a	def __init__(self, master=None, **kw):
626	n/a	"""Construct a Ttk Checkbutton widget with the parent master.
627	n/a
628	n/a	STANDARD OPTIONS
629	n/a
630	n/a	class, compound, cursor, image, state, style, takefocus,
631	n/a	text, textvariable, underline, width
632	n/a
633	n/a	WIDGET-SPECIFIC OPTIONS
634	n/a
635	n/a	command, offvalue, onvalue, variable
636	n/a	"""
637	n/a	Widget.__init__(self, master, "ttk::checkbutton", kw)
638	n/a
639	n/a
640	n/a	def invoke(self):
641	n/a	"""Toggles between the selected and deselected states and
642	n/a	invokes the associated command. If the widget is currently
643	n/a	selected, sets the option variable to the offvalue option
644	n/a	and deselects the widget; otherwise, sets the option variable
645	n/a	to the option onvalue.
646	n/a
647	n/a	Returns the result of the associated command."""
648	n/a	return self.tk.call(self._w, "invoke")
649	n/a
650	n/a
651	n/a	class Entry(Widget, Tkinter.Entry):
652	n/a	"""Ttk Entry widget displays a one-line text string and allows that
653	n/a	string to be edited by the user."""
654	n/a
655	n/a	def __init__(self, master=None, widget=None, **kw):
656	n/a	"""Constructs a Ttk Entry widget with the parent master.
657	n/a
658	n/a	STANDARD OPTIONS
659	n/a
660	n/a	class, cursor, style, takefocus, xscrollcommand
661	n/a
662	n/a	WIDGET-SPECIFIC OPTIONS
663	n/a
664	n/a	exportselection, invalidcommand, justify, show, state,
665	n/a	textvariable, validate, validatecommand, width
666	n/a
667	n/a	VALIDATION MODES
668	n/a
669	n/a	none, key, focus, focusin, focusout, all
670	n/a	"""
671	n/a	Widget.__init__(self, master, widget or "ttk::entry", kw)
672	n/a
673	n/a
674	n/a	def bbox(self, index):
675	n/a	"""Return a tuple of (x, y, width, height) which describes the
676	n/a	bounding box of the character given by index."""
677	n/a	return self.tk.call(self._w, "bbox", index)
678	n/a
679	n/a
680	n/a	def identify(self, x, y):
681	n/a	"""Returns the name of the element at position x, y, or the
682	n/a	empty string if the coordinates are outside the window."""
683	n/a	return self.tk.call(self._w, "identify", x, y)
684	n/a
685	n/a
686	n/a	def validate(self):
687	n/a	"""Force revalidation, independent of the conditions specified
688	n/a	by the validate option. Returns False if validation fails, True
689	n/a	if it succeeds. Sets or clears the invalid state accordingly."""
690	n/a	return bool(self.tk.call(self._w, "validate"))
691	n/a
692	n/a
693	n/a	class Combobox(Entry):
694	n/a	"""Ttk Combobox widget combines a text field with a pop-down list of
695	n/a	values."""
696	n/a
697	n/a	def __init__(self, master=None, **kw):
698	n/a	"""Construct a Ttk Combobox widget with the parent master.
699	n/a
700	n/a	STANDARD OPTIONS
701	n/a
702	n/a	class, cursor, style, takefocus
703	n/a
704	n/a	WIDGET-SPECIFIC OPTIONS
705	n/a
706	n/a	exportselection, justify, height, postcommand, state,
707	n/a	textvariable, values, width
708	n/a	"""
709	n/a	# The "values" option may need special formatting, so leave to
710	n/a	# _format_optdict the responsability to format it
711	n/a	if "values" in kw:
712	n/a	kw["values"] = _format_optdict({'v': kw["values"]})[1]
713	n/a
714	n/a	Entry.__init__(self, master, "ttk::combobox", **kw)
715	n/a
716	n/a
717	n/a	def __setitem__(self, item, value):
718	n/a	if item == "values":
719	n/a	value = _format_optdict({item: value})[1]
720	n/a
721	n/a	Entry.__setitem__(self, item, value)
722	n/a
723	n/a
724	n/a	def configure(self, cnf=None, **kw):
725	n/a	"""Custom Combobox configure, created to properly format the values
726	n/a	option."""
727	n/a	if "values" in kw:
728	n/a	kw["values"] = _format_optdict({'v': kw["values"]})[1]
729	n/a
730	n/a	return Entry.configure(self, cnf, **kw)
731	n/a
732	n/a
733	n/a	def current(self, newindex=None):
734	n/a	"""If newindex is supplied, sets the combobox value to the
735	n/a	element at position newindex in the list of values. Otherwise,
736	n/a	returns the index of the current value in the list of values
737	n/a	or -1 if the current value does not appear in the list."""
738	n/a	return self.tk.call(self._w, "current", newindex)
739	n/a
740	n/a
741	n/a	def set(self, value):
742	n/a	"""Sets the value of the combobox to value."""
743	n/a	self.tk.call(self._w, "set", value)
744	n/a
745	n/a
746	n/a	class Frame(Widget):
747	n/a	"""Ttk Frame widget is a container, used to group other widgets
748	n/a	together."""
749	n/a
750	n/a	def __init__(self, master=None, **kw):
751	n/a	"""Construct a Ttk Frame with parent master.
752	n/a
753	n/a	STANDARD OPTIONS
754	n/a
755	n/a	class, cursor, style, takefocus
756	n/a
757	n/a	WIDGET-SPECIFIC OPTIONS
758	n/a
759	n/a	borderwidth, relief, padding, width, height
760	n/a	"""
761	n/a	Widget.__init__(self, master, "ttk::frame", kw)
762	n/a
763	n/a
764	n/a	class Label(Widget):
765	n/a	"""Ttk Label widget displays a textual label and/or image."""
766	n/a
767	n/a	def __init__(self, master=None, **kw):
768	n/a	"""Construct a Ttk Label with parent master.
769	n/a
770	n/a	STANDARD OPTIONS
771	n/a
772	n/a	class, compound, cursor, image, style, takefocus, text,
773	n/a	textvariable, underline, width
774	n/a
775	n/a	WIDGET-SPECIFIC OPTIONS
776	n/a
777	n/a	anchor, background, font, foreground, justify, padding,
778	n/a	relief, text, wraplength
779	n/a	"""
780	n/a	Widget.__init__(self, master, "ttk::label", kw)
781	n/a
782	n/a
783	n/a	class Labelframe(Widget):
784	n/a	"""Ttk Labelframe widget is a container used to group other widgets
785	n/a	together. It has an optional label, which may be a plain text string
786	n/a	or another widget."""
787	n/a
788	n/a	def __init__(self, master=None, **kw):
789	n/a	"""Construct a Ttk Labelframe with parent master.
790	n/a
791	n/a	STANDARD OPTIONS
792	n/a
793	n/a	class, cursor, style, takefocus
794	n/a
795	n/a	WIDGET-SPECIFIC OPTIONS
796	n/a	labelanchor, text, underline, padding, labelwidget, width,
797	n/a	height
798	n/a	"""
799	n/a	Widget.__init__(self, master, "ttk::labelframe", kw)
800	n/a
801	n/a	LabelFrame = Labelframe # Tkinter name compatibility
802	n/a
803	n/a
804	n/a	class Menubutton(Widget):
805	n/a	"""Ttk Menubutton widget displays a textual label and/or image, and
806	n/a	displays a menu when pressed."""
807	n/a
808	n/a	def __init__(self, master=None, **kw):
809	n/a	"""Construct a Ttk Menubutton with parent master.
810	n/a
811	n/a	STANDARD OPTIONS
812	n/a
813	n/a	class, compound, cursor, image, state, style, takefocus,
814	n/a	text, textvariable, underline, width
815	n/a
816	n/a	WIDGET-SPECIFIC OPTIONS
817	n/a
818	n/a	direction, menu
819	n/a	"""
820	n/a	Widget.__init__(self, master, "ttk::menubutton", kw)
821	n/a
822	n/a
823	n/a	class Notebook(Widget):
824	n/a	"""Ttk Notebook widget manages a collection of windows and displays
825	n/a	a single one at a time. Each child window is associated with a tab,
826	n/a	which the user may select to change the currently-displayed window."""
827	n/a
828	n/a	def __init__(self, master=None, **kw):
829	n/a	"""Construct a Ttk Notebook with parent master.
830	n/a
831	n/a	STANDARD OPTIONS
832	n/a
833	n/a	class, cursor, style, takefocus
834	n/a
835	n/a	WIDGET-SPECIFIC OPTIONS
836	n/a
837	n/a	height, padding, width
838	n/a
839	n/a	TAB OPTIONS
840	n/a
841	n/a	state, sticky, padding, text, image, compound, underline
842	n/a
843	n/a	TAB IDENTIFIERS (tab_id)
844	n/a
845	n/a	The tab_id argument found in several methods may take any of
846	n/a	the following forms:
847	n/a
848	n/a	* An integer between zero and the number of tabs
849	n/a	* The name of a child window
850	n/a	* A positional specification of the form "@x,y", which
851	n/a	defines the tab
852	n/a	* The string "current", which identifies the
853	n/a	currently-selected tab
854	n/a	* The string "end", which returns the number of tabs (only
855	n/a	valid for method index)
856	n/a	"""
857	n/a	Widget.__init__(self, master, "ttk::notebook", kw)
858	n/a
859	n/a
860	n/a	def add(self, child, **kw):
861	n/a	"""Adds a new tab to the notebook.
862	n/a
863	n/a	If window is currently managed by the notebook but hidden, it is
864	n/a	restored to its previous position."""
865	n/a	self.tk.call(self._w, "add", child, *(_format_optdict(kw)))
866	n/a
867	n/a
868	n/a	def forget(self, tab_id):
869	n/a	"""Removes the tab specified by tab_id, unmaps and unmanages the
870	n/a	associated window."""
871	n/a	self.tk.call(self._w, "forget", tab_id)
872	n/a
873	n/a
874	n/a	def hide(self, tab_id):
875	n/a	"""Hides the tab specified by tab_id.
876	n/a
877	n/a	The tab will not be displayed, but the associated window remains
878	n/a	managed by the notebook and its configuration remembered. Hidden
879	n/a	tabs may be restored with the add command."""
880	n/a	self.tk.call(self._w, "hide", tab_id)
881	n/a
882	n/a
883	n/a	def identify(self, x, y):
884	n/a	"""Returns the name of the tab element at position x, y, or the
885	n/a	empty string if none."""
886	n/a	return self.tk.call(self._w, "identify", x, y)
887	n/a
888	n/a
889	n/a	def index(self, tab_id):
890	n/a	"""Returns the numeric index of the tab specified by tab_id, or
891	n/a	the total number of tabs if tab_id is the string "end"."""
892	n/a	return self.tk.call(self._w, "index", tab_id)
893	n/a
894	n/a
895	n/a	def insert(self, pos, child, **kw):
896	n/a	"""Inserts a pane at the specified position.
897	n/a
898	n/a	pos is either the string end, an integer index, or the name of
899	n/a	a managed child. If child is already managed by the notebook,
900	n/a	moves it to the specified position."""
901	n/a	self.tk.call(self._w, "insert", pos, child, *(_format_optdict(kw)))
902	n/a
903	n/a
904	n/a	def select(self, tab_id=None):
905	n/a	"""Selects the specified tab.
906	n/a
907	n/a	The associated child window will be displayed, and the
908	n/a	previously-selected window (if different) is unmapped. If tab_id
909	n/a	is omitted, returns the widget name of the currently selected
910	n/a	pane."""
911	n/a	return self.tk.call(self._w, "select", tab_id)
912	n/a
913	n/a
914	n/a	def tab(self, tab_id, option=None, **kw):
915	n/a	"""Query or modify the options of the specific tab_id.
916	n/a
917	n/a	If kw is not given, returns a dict of the tab option values. If option
918	n/a	is specified, returns the value of that option. Otherwise, sets the
919	n/a	options to the corresponding values."""
920	n/a	if option is not None:
921	n/a	kw[option] = None
922	n/a	return _val_or_dict(kw, self.tk.call, self._w, "tab", tab_id)
923	n/a
924	n/a
925	n/a	def tabs(self):
926	n/a	"""Returns a list of windows managed by the notebook."""
927	n/a	return self.tk.call(self._w, "tabs") or ()
928	n/a
929	n/a
930	n/a	def enable_traversal(self):
931	n/a	"""Enable keyboard traversal for a toplevel window containing
932	n/a	this notebook.
933	n/a
934	n/a	This will extend the bindings for the toplevel window containing
935	n/a	this notebook as follows:
936	n/a
937	n/a	Control-Tab: selects the tab following the currently selected
938	n/a	one
939	n/a
940	n/a	Shift-Control-Tab: selects the tab preceding the currently
941	n/a	selected one
942	n/a
943	n/a	Alt-K: where K is the mnemonic (underlined) character of any
944	n/a	tab, will select that tab.
945	n/a
946	n/a	Multiple notebooks in a single toplevel may be enabled for
947	n/a	traversal, including nested notebooks. However, notebook traversal
948	n/a	only works properly if all panes are direct children of the
949	n/a	notebook."""
950	n/a	# The only, and good, difference I see is about mnemonics, which works
951	n/a	# after calling this method. Control-Tab and Shift-Control-Tab always
952	n/a	# works (here at least).
953	n/a	self.tk.call("ttk::notebook::enableTraversal", self._w)
954	n/a
955	n/a
956	n/a	class Panedwindow(Widget, Tkinter.PanedWindow):
957	n/a	"""Ttk Panedwindow widget displays a number of subwindows, stacked
958	n/a	either vertically or horizontally."""
959	n/a
960	n/a	def __init__(self, master=None, **kw):
961	n/a	"""Construct a Ttk Panedwindow with parent master.
962	n/a
963	n/a	STANDARD OPTIONS
964	n/a
965	n/a	class, cursor, style, takefocus
966	n/a
967	n/a	WIDGET-SPECIFIC OPTIONS
968	n/a
969	n/a	orient, width, height
970	n/a
971	n/a	PANE OPTIONS
972	n/a
973	n/a	weight
974	n/a	"""
975	n/a	Widget.__init__(self, master, "ttk::panedwindow", kw)
976	n/a
977	n/a
978	n/a	forget = Tkinter.PanedWindow.forget # overrides Pack.forget
979	n/a
980	n/a
981	n/a	def insert(self, pos, child, **kw):
982	n/a	"""Inserts a pane at the specified positions.
983	n/a
984	n/a	pos is either the string end, and integer index, or the name
985	n/a	of a child. If child is already managed by the paned window,
986	n/a	moves it to the specified position."""
987	n/a	self.tk.call(self._w, "insert", pos, child, *(_format_optdict(kw)))
988	n/a
989	n/a
990	n/a	def pane(self, pane, option=None, **kw):
991	n/a	"""Query or modify the options of the specified pane.
992	n/a
993	n/a	pane is either an integer index or the name of a managed subwindow.
994	n/a	If kw is not given, returns a dict of the pane option values. If
995	n/a	option is specified then the value for that option is returned.
996	n/a	Otherwise, sets the options to the correspoding values."""
997	n/a	if option is not None:
998	n/a	kw[option] = None
999	n/a	return _val_or_dict(kw, self.tk.call, self._w, "pane", pane)
1000	n/a
1001	n/a
1002	n/a	def sashpos(self, index, newpos=None):
1003	n/a	"""If newpos is specified, sets the position of sash number index.
1004	n/a
1005	n/a	May adjust the positions of adjacent sashes to ensure that
1006	n/a	positions are monotonically increasing. Sash positions are further
1007	n/a	constrained to be between 0 and the total size of the widget.
1008	n/a
1009	n/a	Returns the new position of sash number index."""
1010	n/a	return self.tk.call(self._w, "sashpos", index, newpos)
1011	n/a
1012	n/a	PanedWindow = Panedwindow # Tkinter name compatibility
1013	n/a
1014	n/a
1015	n/a	class Progressbar(Widget):
1016	n/a	"""Ttk Progressbar widget shows the status of a long-running
1017	n/a	operation. They can operate in two modes: determinate mode shows the
1018	n/a	amount completed relative to the total amount of work to be done, and
1019	n/a	indeterminate mode provides an animated display to let the user know
1020	n/a	that something is happening."""
1021	n/a
1022	n/a	def __init__(self, master=None, **kw):
1023	n/a	"""Construct a Ttk Progressbar with parent master.
1024	n/a
1025	n/a	STANDARD OPTIONS
1026	n/a
1027	n/a	class, cursor, style, takefocus
1028	n/a
1029	n/a	WIDGET-SPECIFIC OPTIONS
1030	n/a
1031	n/a	orient, length, mode, maximum, value, variable, phase
1032	n/a	"""
1033	n/a	Widget.__init__(self, master, "ttk::progressbar", kw)
1034	n/a
1035	n/a
1036	n/a	def start(self, interval=None):
1037	n/a	"""Begin autoincrement mode: schedules a recurring timer event
1038	n/a	that calls method step every interval milliseconds.
1039	n/a
1040	n/a	interval defaults to 50 milliseconds (20 steps/second) if ommited."""
1041	n/a	self.tk.call(self._w, "start", interval)
1042	n/a
1043	n/a
1044	n/a	def step(self, amount=None):
1045	n/a	"""Increments the value option by amount.
1046	n/a
1047	n/a	amount defaults to 1.0 if omitted."""
1048	n/a	self.tk.call(self._w, "step", amount)
1049	n/a
1050	n/a
1051	n/a	def stop(self):
1052	n/a	"""Stop autoincrement mode: cancels any recurring timer event
1053	n/a	initiated by start."""
1054	n/a	self.tk.call(self._w, "stop")
1055	n/a
1056	n/a
1057	n/a	class Radiobutton(Widget):
1058	n/a	"""Ttk Radiobutton widgets are used in groups to show or change a
1059	n/a	set of mutually-exclusive options."""
1060	n/a
1061	n/a	def __init__(self, master=None, **kw):
1062	n/a	"""Construct a Ttk Radiobutton with parent master.
1063	n/a
1064	n/a	STANDARD OPTIONS
1065	n/a
1066	n/a	class, compound, cursor, image, state, style, takefocus,
1067	n/a	text, textvariable, underline, width
1068	n/a
1069	n/a	WIDGET-SPECIFIC OPTIONS
1070	n/a
1071	n/a	command, value, variable
1072	n/a	"""
1073	n/a	Widget.__init__(self, master, "ttk::radiobutton", kw)
1074	n/a
1075	n/a
1076	n/a	def invoke(self):
1077	n/a	"""Sets the option variable to the option value, selects the
1078	n/a	widget, and invokes the associated command.
1079	n/a
1080	n/a	Returns the result of the command, or an empty string if
1081	n/a	no command is specified."""
1082	n/a	return self.tk.call(self._w, "invoke")
1083	n/a
1084	n/a
1085	n/a	class Scale(Widget, Tkinter.Scale):
1086	n/a	"""Ttk Scale widget is typically used to control the numeric value of
1087	n/a	a linked variable that varies uniformly over some range."""
1088	n/a
1089	n/a	def __init__(self, master=None, **kw):
1090	n/a	"""Construct a Ttk Scale with parent master.
1091	n/a
1092	n/a	STANDARD OPTIONS
1093	n/a
1094	n/a	class, cursor, style, takefocus
1095	n/a
1096	n/a	WIDGET-SPECIFIC OPTIONS
1097	n/a
1098	n/a	command, from, length, orient, to, value, variable
1099	n/a	"""
1100	n/a	Widget.__init__(self, master, "ttk::scale", kw)
1101	n/a
1102	n/a
1103	n/a	def configure(self, cnf=None, **kw):
1104	n/a	"""Modify or query scale options.
1105	n/a
1106	n/a	Setting a value for any of the "from", "from_" or "to" options
1107	n/a	generates a <<RangeChanged>> event."""
1108	n/a	if cnf:
1109	n/a	kw.update(cnf)
1110	n/a	Widget.configure(self, **kw)
1111	n/a	if any(['from' in kw, 'from_' in kw, 'to' in kw]):
1112	n/a	self.event_generate('<<RangeChanged>>')
1113	n/a
1114	n/a
1115	n/a	def get(self, x=None, y=None):
1116	n/a	"""Get the current value of the value option, or the value
1117	n/a	corresponding to the coordinates x, y if they are specified.
1118	n/a
1119	n/a	x and y are pixel coordinates relative to the scale widget
1120	n/a	origin."""
1121	n/a	return self.tk.call(self._w, 'get', x, y)
1122	n/a
1123	n/a
1124	n/a	class Scrollbar(Widget, Tkinter.Scrollbar):
1125	n/a	"""Ttk Scrollbar controls the viewport of a scrollable widget."""
1126	n/a
1127	n/a	def __init__(self, master=None, **kw):
1128	n/a	"""Construct a Ttk Scrollbar with parent master.
1129	n/a
1130	n/a	STANDARD OPTIONS
1131	n/a
1132	n/a	class, cursor, style, takefocus
1133	n/a
1134	n/a	WIDGET-SPECIFIC OPTIONS
1135	n/a
1136	n/a	command, orient
1137	n/a	"""
1138	n/a	Widget.__init__(self, master, "ttk::scrollbar", kw)
1139	n/a
1140	n/a
1141	n/a	class Separator(Widget):
1142	n/a	"""Ttk Separator widget displays a horizontal or vertical separator
1143	n/a	bar."""
1144	n/a
1145	n/a	def __init__(self, master=None, **kw):
1146	n/a	"""Construct a Ttk Separator with parent master.
1147	n/a
1148	n/a	STANDARD OPTIONS
1149	n/a
1150	n/a	class, cursor, style, takefocus
1151	n/a
1152	n/a	WIDGET-SPECIFIC OPTIONS
1153	n/a
1154	n/a	orient
1155	n/a	"""
1156	n/a	Widget.__init__(self, master, "ttk::separator", kw)
1157	n/a
1158	n/a
1159	n/a	class Sizegrip(Widget):
1160	n/a	"""Ttk Sizegrip allows the user to resize the containing toplevel
1161	n/a	window by pressing and dragging the grip."""
1162	n/a
1163	n/a	def __init__(self, master=None, **kw):
1164	n/a	"""Construct a Ttk Sizegrip with parent master.
1165	n/a
1166	n/a	STANDARD OPTIONS
1167	n/a
1168	n/a	class, cursor, state, style, takefocus
1169	n/a	"""
1170	n/a	Widget.__init__(self, master, "ttk::sizegrip", kw)
1171	n/a
1172	n/a
1173	n/a	class Treeview(Widget, Tkinter.XView, Tkinter.YView):
1174	n/a	"""Ttk Treeview widget displays a hierarchical collection of items.
1175	n/a
1176	n/a	Each item has a textual label, an optional image, and an optional list
1177	n/a	of data values. The data values are displayed in successive columns
1178	n/a	after the tree label."""
1179	n/a
1180	n/a	def __init__(self, master=None, **kw):
1181	n/a	"""Construct a Ttk Treeview with parent master.
1182	n/a
1183	n/a	STANDARD OPTIONS
1184	n/a
1185	n/a	class, cursor, style, takefocus, xscrollcommand,
1186	n/a	yscrollcommand
1187	n/a
1188	n/a	WIDGET-SPECIFIC OPTIONS
1189	n/a
1190	n/a	columns, displaycolumns, height, padding, selectmode, show
1191	n/a
1192	n/a	ITEM OPTIONS
1193	n/a
1194	n/a	text, image, values, open, tags
1195	n/a
1196	n/a	TAG OPTIONS
1197	n/a
1198	n/a	foreground, background, font, image
1199	n/a	"""
1200	n/a	Widget.__init__(self, master, "ttk::treeview", kw)
1201	n/a
1202	n/a
1203	n/a	def bbox(self, item, column=None):
1204	n/a	"""Returns the bounding box (relative to the treeview widget's
1205	n/a	window) of the specified item in the form x y width height.
1206	n/a
1207	n/a	If column is specified, returns the bounding box of that cell.
1208	n/a	If the item is not visible (i.e., if it is a descendant of a
1209	n/a	closed item or is scrolled offscreen), returns an empty string."""
1210	n/a	return self.tk.call(self._w, "bbox", item, column)
1211	n/a
1212	n/a
1213	n/a	def get_children(self, item=None):
1214	n/a	"""Returns a tuple of children belonging to item.
1215	n/a
1216	n/a	If item is not specified, returns root children."""
1217	n/a	return self.tk.call(self._w, "children", item or '') or ()
1218	n/a
1219	n/a
1220	n/a	def set_children(self, item, *newchildren):
1221	n/a	"""Replaces item's child with newchildren.
1222	n/a
1223	n/a	Children present in item that are not present in newchildren
1224	n/a	are detached from tree. No items in newchildren may be an
1225	n/a	ancestor of item."""
1226	n/a	self.tk.call(self._w, "children", item, newchildren)
1227	n/a
1228	n/a
1229	n/a	def column(self, column, option=None, **kw):
1230	n/a	"""Query or modify the options for the specified column.
1231	n/a
1232	n/a	If kw is not given, returns a dict of the column option values. If
1233	n/a	option is specified then the value for that option is returned.
1234	n/a	Otherwise, sets the options to the corresponding values."""
1235	n/a	if option is not None:
1236	n/a	kw[option] = None
1237	n/a	return _val_or_dict(kw, self.tk.call, self._w, "column", column)
1238	n/a
1239	n/a
1240	n/a	def delete(self, *items):
1241	n/a	"""Delete all specified items and all their descendants. The root
1242	n/a	item may not be deleted."""
1243	n/a	self.tk.call(self._w, "delete", items)
1244	n/a
1245	n/a
1246	n/a	def detach(self, *items):
1247	n/a	"""Unlinks all of the specified items from the tree.
1248	n/a
1249	n/a	The items and all of their descendants are still present, and may
1250	n/a	be reinserted at another point in the tree, but will not be
1251	n/a	displayed. The root item may not be detached."""
1252	n/a	self.tk.call(self._w, "detach", items)
1253	n/a
1254	n/a
1255	n/a	def exists(self, item):
1256	n/a	"""Returns True if the specified item is present in the three,
1257	n/a	False otherwise."""
1258	n/a	return bool(self.tk.call(self._w, "exists", item))
1259	n/a
1260	n/a
1261	n/a	def focus(self, item=None):
1262	n/a	"""If item is specified, sets the focus item to item. Otherwise,
1263	n/a	returns the current focus item, or '' if there is none."""
1264	n/a	return self.tk.call(self._w, "focus", item)
1265	n/a
1266	n/a
1267	n/a	def heading(self, column, option=None, **kw):
1268	n/a	"""Query or modify the heading options for the specified column.
1269	n/a
1270	n/a	If kw is not given, returns a dict of the heading option values. If
1271	n/a	option is specified then the value for that option is returned.
1272	n/a	Otherwise, sets the options to the corresponding values.
1273	n/a
1274	n/a	Valid options/values are:
1275	n/a	text: text
1276	n/a	The text to display in the column heading
1277	n/a	image: image_name
1278	n/a	Specifies an image to display to the right of the column
1279	n/a	heading
1280	n/a	anchor: anchor
1281	n/a	Specifies how the heading text should be aligned. One of
1282	n/a	the standard Tk anchor values
1283	n/a	command: callback
1284	n/a	A callback to be invoked when the heading label is
1285	n/a	pressed.
1286	n/a
1287	n/a	To configure the tree column heading, call this with column = "#0" """
1288	n/a	cmd = kw.get('command')
1289	n/a	if cmd and not isinstance(cmd, basestring):
1290	n/a	# callback not registered yet, do it now
1291	n/a	kw['command'] = self.master.register(cmd, self._substitute)
1292	n/a
1293	n/a	if option is not None:
1294	n/a	kw[option] = None
1295	n/a
1296	n/a	return _val_or_dict(kw, self.tk.call, self._w, 'heading', column)
1297	n/a
1298	n/a
1299	n/a	def identify(self, component, x, y):
1300	n/a	"""Returns a description of the specified component under the
1301	n/a	point given by x and y, or the empty string if no such component
1302	n/a	is present at that position."""
1303	n/a	return self.tk.call(self._w, "identify", component, x, y)
1304	n/a
1305	n/a
1306	n/a	def identify_row(self, y):
1307	n/a	"""Returns the item ID of the item at position y."""
1308	n/a	return self.identify("row", 0, y)
1309	n/a
1310	n/a
1311	n/a	def identify_column(self, x):
1312	n/a	"""Returns the data column identifier of the cell at position x.
1313	n/a
1314	n/a	The tree column has ID #0."""
1315	n/a	return self.identify("column", x, 0)
1316	n/a
1317	n/a
1318	n/a	def identify_region(self, x, y):
1319	n/a	"""Returns one of:
1320	n/a
1321	n/a	heading: Tree heading area.
1322	n/a	separator: Space between two columns headings;
1323	n/a	tree: The tree area.
1324	n/a	cell: A data cell.
1325	n/a
1326	n/a	* Availability: Tk 8.6"""
1327	n/a	return self.identify("region", x, y)
1328	n/a
1329	n/a
1330	n/a	def identify_element(self, x, y):
1331	n/a	"""Returns the element at position x, y.
1332	n/a
1333	n/a	* Availability: Tk 8.6"""
1334	n/a	return self.identify("element", x, y)
1335	n/a
1336	n/a
1337	n/a	def index(self, item):
1338	n/a	"""Returns the integer index of item within its parent's list
1339	n/a	of children."""
1340	n/a	return self.tk.call(self._w, "index", item)
1341	n/a
1342	n/a
1343	n/a	def insert(self, parent, index, iid=None, **kw):
1344	n/a	"""Creates a new item and return the item identifier of the newly
1345	n/a	created item.
1346	n/a
1347	n/a	parent is the item ID of the parent item, or the empty string
1348	n/a	to create a new top-level item. index is an integer, or the value
1349	n/a	end, specifying where in the list of parent's children to insert
1350	n/a	the new item. If index is less than or equal to zero, the new node
1351	n/a	is inserted at the beginning, if index is greater than or equal to
1352	n/a	the current number of children, it is inserted at the end. If iid
1353	n/a	is specified, it is used as the item identifier, iid must not
1354	n/a	already exist in the tree. Otherwise, a new unique identifier
1355	n/a	is generated."""
1356	n/a	opts = _format_optdict(kw)
1357	n/a	if iid:
1358	n/a	res = self.tk.call(self._w, "insert", parent, index,
1359	n/a	"-id", iid, *opts)
1360	n/a	else:
1361	n/a	res = self.tk.call(self._w, "insert", parent, index, *opts)
1362	n/a
1363	n/a	return res
1364	n/a
1365	n/a
1366	n/a	def item(self, item, option=None, **kw):
1367	n/a	"""Query or modify the options for the specified item.
1368	n/a
1369	n/a	If no options are given, a dict with options/values for the item
1370	n/a	is returned. If option is specified then the value for that option
1371	n/a	is returned. Otherwise, sets the options to the corresponding
1372	n/a	values as given by kw."""
1373	n/a	if option is not None:
1374	n/a	kw[option] = None
1375	n/a	return _val_or_dict(kw, self.tk.call, self._w, "item", item)
1376	n/a
1377	n/a
1378	n/a	def move(self, item, parent, index):
1379	n/a	"""Moves item to position index in parent's list of children.
1380	n/a
1381	n/a	It is illegal to move an item under one of its descendants. If
1382	n/a	index is less than or equal to zero, item is moved to the
1383	n/a	beginning, if greater than or equal to the number of children,
1384	n/a	it is moved to the end. If item was detached it is reattached."""
1385	n/a	self.tk.call(self._w, "move", item, parent, index)
1386	n/a
1387	n/a	reattach = move # A sensible method name for reattaching detached items
1388	n/a
1389	n/a
1390	n/a	def next(self, item):
1391	n/a	"""Returns the identifier of item's next sibling, or '' if item
1392	n/a	is the last child of its parent."""
1393	n/a	return self.tk.call(self._w, "next", item)
1394	n/a
1395	n/a
1396	n/a	def parent(self, item):
1397	n/a	"""Returns the ID of the parent of item, or '' if item is at the
1398	n/a	top level of the hierarchy."""
1399	n/a	return self.tk.call(self._w, "parent", item)
1400	n/a
1401	n/a
1402	n/a	def prev(self, item):
1403	n/a	"""Returns the identifier of item's previous sibling, or '' if
1404	n/a	item is the first child of its parent."""
1405	n/a	return self.tk.call(self._w, "prev", item)
1406	n/a
1407	n/a
1408	n/a	def see(self, item):
1409	n/a	"""Ensure that item is visible.
1410	n/a
1411	n/a	Sets all of item's ancestors open option to True, and scrolls
1412	n/a	the widget if necessary so that item is within the visible
1413	n/a	portion of the tree."""
1414	n/a	self.tk.call(self._w, "see", item)
1415	n/a
1416	n/a
1417	n/a	def selection(self, selop=None, items=None):
1418	n/a	"""If selop is not specified, returns selected items."""
1419	n/a	return self.tk.call(self._w, "selection", selop, items)
1420	n/a
1421	n/a
1422	n/a	def selection_set(self, items):
1423	n/a	"""items becomes the new selection."""
1424	n/a	self.selection("set", items)
1425	n/a
1426	n/a
1427	n/a	def selection_add(self, items):
1428	n/a	"""Add items to the selection."""
1429	n/a	self.selection("add", items)
1430	n/a
1431	n/a
1432	n/a	def selection_remove(self, items):
1433	n/a	"""Remove items from the selection."""
1434	n/a	self.selection("remove", items)
1435	n/a
1436	n/a
1437	n/a	def selection_toggle(self, items):
1438	n/a	"""Toggle the selection state of each item in items."""
1439	n/a	self.selection("toggle", items)
1440	n/a
1441	n/a
1442	n/a	def set(self, item, column=None, value=None):
1443	n/a	"""With one argument, returns a dictionary of column/value pairs
1444	n/a	for the specified item. With two arguments, returns the current
1445	n/a	value of the specified column. With three arguments, sets the
1446	n/a	value of given column in given item to the specified value."""
1447	n/a	res = self.tk.call(self._w, "set", item, column, value)
1448	n/a	if column is None and value is None:
1449	n/a	return _dict_from_tcltuple(res, False)
1450	n/a	else:
1451	n/a	return res
1452	n/a
1453	n/a
1454	n/a	def tag_bind(self, tagname, sequence=None, callback=None):
1455	n/a	"""Bind a callback for the given event sequence to the tag tagname.
1456	n/a	When an event is delivered to an item, the callbacks for each
1457	n/a	of the item's tags option are called."""
1458	n/a	self._bind((self._w, "tag", "bind", tagname), sequence, callback, add=0)
1459	n/a
1460	n/a
1461	n/a	def tag_configure(self, tagname, option=None, **kw):
1462	n/a	"""Query or modify the options for the specified tagname.
1463	n/a
1464	n/a	If kw is not given, returns a dict of the option settings for tagname.
1465	n/a	If option is specified, returns the value for that option for the
1466	n/a	specified tagname. Otherwise, sets the options to the corresponding
1467	n/a	values for the given tagname."""
1468	n/a	if option is not None:
1469	n/a	kw[option] = None
1470	n/a	return _val_or_dict(kw, self.tk.call, self._w, "tag", "configure",
1471	n/a	tagname)
1472	n/a
1473	n/a
1474	n/a	def tag_has(self, tagname, item=None):
1475	n/a	"""If item is specified, returns 1 or 0 depending on whether the
1476	n/a	specified item has the given tagname. Otherwise, returns a list of
1477	n/a	all items which have the specified tag.
1478	n/a
1479	n/a	* Availability: Tk 8.6"""
1480	n/a	return self.tk.call(self._w, "tag", "has", tagname, item)
1481	n/a
1482	n/a
1483	n/a	# Extensions
1484	n/a
1485	n/a	class LabeledScale(Frame, object):
1486	n/a	"""A Ttk Scale widget with a Ttk Label widget indicating its
1487	n/a	current value.
1488	n/a
1489	n/a	The Ttk Scale can be accessed through instance.scale, and Ttk Label
1490	n/a	can be accessed through instance.label"""
1491	n/a
1492	n/a	def __init__(self, master=None, variable=None, from_=0, to=10, **kw):
1493	n/a	"""Construct an horizontal LabeledScale with parent master, a
1494	n/a	variable to be associated with the Ttk Scale widget and its range.
1495	n/a	If variable is not specified, a Tkinter.IntVar is created.
1496	n/a
1497	n/a	WIDGET-SPECIFIC OPTIONS
1498	n/a
1499	n/a	compound: 'top' or 'bottom'
1500	n/a	Specifies how to display the label relative to the scale.
1501	n/a	Defaults to 'top'.
1502	n/a	"""
1503	n/a	self._label_top = kw.pop('compound', 'top') == 'top'
1504	n/a
1505	n/a	Frame.__init__(self, master, **kw)
1506	n/a	self._variable = variable or Tkinter.IntVar(master)
1507	n/a	self._variable.set(from_)
1508	n/a	self._last_valid = from_
1509	n/a
1510	n/a	self.label = Label(self)
1511	n/a	self.scale = Scale(self, variable=self._variable, from_=from_, to=to)
1512	n/a	self.scale.bind('<<RangeChanged>>', self._adjust)
1513	n/a
1514	n/a	# position scale and label according to the compound option
1515	n/a	scale_side = 'bottom' if self._label_top else 'top'
1516	n/a	label_side = 'top' if scale_side == 'bottom' else 'bottom'
1517	n/a	self.scale.pack(side=scale_side, fill='x')
1518	n/a	tmp = Label(self).pack(side=label_side) # place holder
1519	n/a	self.label.place(anchor='n' if label_side == 'top' else 's')
1520	n/a
1521	n/a	# update the label as scale or variable changes
1522	n/a	self.__tracecb = self._variable.trace_variable('w', self._adjust)
1523	n/a	self.bind('<Configure>', self._adjust)
1524	n/a	self.bind('<Map>', self._adjust)
1525	n/a
1526	n/a
1527	n/a	def destroy(self):
1528	n/a	"""Destroy this widget and possibly its associated variable."""
1529	n/a	try:
1530	n/a	self._variable.trace_vdelete('w', self.__tracecb)
1531	n/a	except AttributeError:
1532	n/a	# widget has been destroyed already
1533	n/a	pass
1534	n/a	else:
1535	n/a	del self._variable
1536	n/a	Frame.destroy(self)
1537	n/a
1538	n/a
1539	n/a	def _adjust(self, *args):
1540	n/a	"""Adjust the label position according to the scale."""
1541	n/a	def adjust_label():
1542	n/a	self.update_idletasks() # "force" scale redraw
1543	n/a
1544	n/a	x, y = self.scale.coords()
1545	n/a	if self._label_top:
1546	n/a	y = self.scale.winfo_y() - self.label.winfo_reqheight()
1547	n/a	else:
1548	n/a	y = self.scale.winfo_reqheight() + self.label.winfo_reqheight()
1549	n/a
1550	n/a	self.label.place_configure(x=x, y=y)
1551	n/a
1552	n/a	from_, to = self.scale['from'], self.scale['to']
1553	n/a	if to < from_:
1554	n/a	from_, to = to, from_
1555	n/a	newval = self._variable.get()
1556	n/a	if not from_ <= newval <= to:
1557	n/a	# value outside range, set value back to the last valid one
1558	n/a	self.value = self._last_valid
1559	n/a	return
1560	n/a
1561	n/a	self._last_valid = newval
1562	n/a	self.label['text'] = newval
1563	n/a	self.after_idle(adjust_label)
1564	n/a
1565	n/a
1566	n/a	def _get_value(self):
1567	n/a	"""Return current scale value."""
1568	n/a	return self._variable.get()
1569	n/a
1570	n/a
1571	n/a	def _set_value(self, val):
1572	n/a	"""Set new scale value."""
1573	n/a	self._variable.set(val)
1574	n/a
1575	n/a
1576	n/a	value = property(_get_value, _set_value)
1577	n/a
1578	n/a
1579	n/a	class OptionMenu(Menubutton):
1580	n/a	"""Themed OptionMenu, based after Tkinter's OptionMenu, which allows
1581	n/a	the user to select a value from a menu."""
1582	n/a
1583	n/a	def __init__(self, master, variable, default=None, values, *kwargs):
1584	n/a	"""Construct a themed OptionMenu widget with master as the parent,
1585	n/a	the resource textvariable set to variable, the initially selected
1586	n/a	value specified by the default parameter, the menu values given by
1587	n/a	*values and additional keywords.
1588	n/a
1589	n/a	WIDGET-SPECIFIC OPTIONS
1590	n/a
1591	n/a	style: stylename
1592	n/a	Menubutton style.
1593	n/a	direction: 'above', 'below', 'left', 'right', or 'flush'
1594	n/a	Menubutton direction.
1595	n/a	command: callback
1596	n/a	A callback that will be invoked after selecting an item.
1597	n/a	"""
1598	n/a	kw = {'textvariable': variable, 'style': kwargs.pop('style', None),
1599	n/a	'direction': kwargs.pop('direction', None)}
1600	n/a	Menubutton.__init__(self, master, **kw)
1601	n/a	self['menu'] = Tkinter.Menu(self, tearoff=False)
1602	n/a
1603	n/a	self._variable = variable
1604	n/a	self._callback = kwargs.pop('command', None)
1605	n/a	if kwargs:
1606	n/a	raise Tkinter.TclError('unknown option -%s' % (
1607	n/a	kwargs.iterkeys().next()))
1608	n/a
1609	n/a	self.set_menu(default, *values)
1610	n/a
1611	n/a
1612	n/a	def __getitem__(self, item):
1613	n/a	if item == 'menu':
1614	n/a	return self.nametowidget(Menubutton.__getitem__(self, item))
1615	n/a
1616	n/a	return Menubutton.__getitem__(self, item)
1617	n/a
1618	n/a
1619	n/a	def set_menu(self, default=None, *values):
1620	n/a	"""Build a new menu of radiobuttons with *values and optionally
1621	n/a	a default value."""
1622	n/a	menu = self['menu']
1623	n/a	menu.delete(0, 'end')
1624	n/a	for val in values:
1625	n/a	menu.add_radiobutton(label=val,
1626	n/a	command=Tkinter._setit(self._variable, val, self._callback))
1627	n/a
1628	n/a	if default:
1629	n/a	self._variable.set(default)
1630	n/a
1631	n/a
1632	n/a	def destroy(self):
1633	n/a	"""Destroy this widget and its associated variable."""
1634	n/a	del self._variable
1635	n/a	Menubutton.destroy(self)