Widget Reference

This is a big list of widgets and explanations of what they do. As usual, don’t try to read all of it, unless you’re very bored; it’s best to find what you’re looking for, and ignore rest of this.

class teek.Widget(parent, **kwargs)

This is a base class for all widgets.

All widgets inherit from this class, and they have all the attributes and methods documented here.

Don’t create instances of Widget yourself like Widget(...); use one of the classes documented below instead. However, you can use Widget with isinstance(); e.g. isinstance(thingy, teek.Widget) returns True if thingy is a teek widget.

config

A dict-like object that represents the widget’s options.

>>> window = teek.Window()
>>> label = teek.Label(window, text='Hello World')
>>> label.config
<a config object, behaves like a dict>
>>> label.config['text']
'Hello World'
>>> label.config['text'] = 'New Text'
>>> label.config['text']
'New Text'
>>> label.config.update({'text': 'Even newer text'})
>>> label.config['text']
'Even newer text'
>>> import pprint
>>> pprint.pprint(dict(label.config))  # prints everything nicely          # doctest: +ELLIPSIS
{...,
 'text': 'Even newer text',
 ...}

state

Represents the Ttk state of the widget. The state object behaves like a set of strings. For example, widget.state.add('disabled') makes a widget look like it’s grayed out, and widget.state.remove('disabled') undoes that. See STATES in ttk_intro(3tk) for more details about states.

Note

Only Ttk widgets have states, and this attribute is set to None for non-Ttk widgets. If you don’t know what Ttk is, you should read about it in the teek tutorial. Most teek widgets are ttk widgets, but some aren’t, and that’s mentioned in the documentation of those widgets.

tk_class_name

Tk’s class name of the widget class, as a string.

This is a class attribute, but it can be accessed from instances as well:

>>> text = teek.Text(teek.Window())
>>> text.tk_class_name
'Text'
>>> teek.Text.tk_class_name
'Text'

Note that Tk’s class names are sometimes different from the names of Python classes, and this attribute can also be None in some special cases.

>>> teek.Label.tk_class_name
'TLabel'
>>> class AsdLabel(teek.Label):
...     pass
...
>>> AsdLabel.tk_class_name
'TLabel'
>>> print(teek.Window.tk_class_name)
None
>>> print(teek.Widget.tk_class_name)
None

command_list

A list of command strings from create_command().

Append a command to this if you want the command to be deleted with delete_command() when the widget is destroyed (with e.g. destroy()).

destroy()

Delete this widget and all child widgets.

Manual page: destroy(3tk)

Note

Don’t override this in a subclass. In some cases, the widget is destroyed without a call to this method.

>>> class BrokenFunnyLabel(teek.Label):
...     def destroy(self):
...         print("destroying")
...         super().destroy()
...
>>> BrokenFunnyLabel(teek.Window()).pack()
>>> teek.quit()
>>> # nothing was printed!

Use the <Destroy> event instead:

>>> class WorkingFunnyLabel(teek.Label):
...     def __init__(self, *args, **kwargs):
...         super().__init__(*args, **kwargs)
...         self.bind('<Destroy>', self._destroy_callback)
...     def _destroy_callback(self):
...         print("destroying")
...
>>> WorkingFunnyLabel(teek.Window()).pack()
>>> teek.quit()
destroying

focus(*, force=False)

Focuses the widget with focus(3tk).

If force=True is given, the -force option is used.

classmethod from_tcl(path_string)

Creates a widget from a Tcl path name.

In Tcl, widgets are represented as commands, and doing something to the widget invokes the command. Use this method if you know the Tcl command and you would like to have a widget object instead.

This method raises TypeError if it’s called from a different Widget subclass than what the type of the path_string widget is:

>>> window = teek.Window()
>>> teek.Button.from_tcl(teek.Label(window).to_tcl())  # doctest: +ELLIPSIS
Traceback (most recent call last):
    ...
TypeError: '...' is a Label, not a Button

to_tcl()

Returns the widget’s Tcl command name. See from_tcl().

winfo_children()

Returns a list of child widgets that this widget has.

Manual page: winfo(3tk)

winfo_exists()

Returns False if the widget has been destroyed. See destroy().

Manual page: winfo(3tk)

winfo_height()

Calls winfo height. Returns an integer.

Manual page: winfo(3tk)

winfo_id()

Calls winfo id. Returns an integer.

Manual page: winfo(3tk)

winfo_reqheight()

Calls winfo reqheight. Returns an integer.

Manual page: winfo(3tk)

winfo_reqwidth()

Calls winfo reqwidth. Returns an integer.

Manual page: winfo(3tk)

winfo_rootx()

Calls winfo rootx. Returns an integer.

Manual page: winfo(3tk)

winfo_rooty()

Calls winfo rooty. Returns an integer.

Manual page: winfo(3tk)

winfo_toplevel()

Returns the Toplevel widget that this widget is in.

Manual page: winfo(3tk)

winfo_width()

Calls winfo width. Returns an integer.

Manual page: winfo(3tk)

winfo_x()

Calls winfo x. Returns an integer.

Manual page: winfo(3tk)

winfo_y()

Calls winfo y. Returns an integer.

Manual page: winfo(3tk)

class teek.Button(parent, text='', command=None, **kwargs)

A widget that runs a callback when it’s clicked.

See examples/button.py for example code.

text can be given as with Label. The 'command' option is not settable, and its value is a Callback that runs with no arguments when the button is clicked. If the command argument is given, it will be treated so that this…

button = teek.Button(some_widget, "Click me", do_something)

…does the same thing as this:

button = teek.Button(some_widget, "Click me")
button.config['command'].connect(do_something)

See Callback.connect() documentation if you need to pass arguments to the do_something function.

Manual page: ttk_button(3tk)

invoke()

Runs the command callback.

See pathname invoke in ttk_button(3tk) for details.

class teek.Canvas

See Canvas Widget.

class teek.Checkbutton(parent, text='', command=None, **kwargs)

A square-shaped, checkable box with text next to it.

See examples/checkbutton.py for example code.

For convenience, text and command arguments work the same way as with Button.

The 'command' option is not settable, and its value is a Callback. By default, it runs with True as the only argument when the checkbutton is checked, and with False when the checkbutton is unchecked. You can pass onvalue=False, offvalue=True to reverse this if you find it useful for some reason. This also affects the values that end up in the 'variable' option (see manual page), which is a BooleanVar.

Manual page: ttk_checkbutton(3tk)

invoke()

Checks or unchecks the checkbutton, updates the variable and runs the command callback.

See pathname invoke in ttk_checkbutton(3tk) for details.

class teek.Combobox(parent, text='', **kwargs)

An entry that displays a list of valid values.

This class inherits from Entry, so it has all the attributes and methods of Entry, like text and cursor_pos.

Manual page: ttk_combobox(3tk)

class teek.Entry(parent, text='', **kwargs)

A widget for asking the user to enter a one-line string.

The text option works as with Label.

See also

Use Label if you want to display text without letting the user edit it. Entries are also not suitable for text with more than one line; use Text instead if you want multiple lines.

Manual page: ttk_entry(3tk)

cursor_pos

The integer index of the cursor in the entry, so that entry.text[:entry.cursor_pos] and entry.text[entry.cursor_pos:] are the text before and after the cursor, respectively.

You can set this attribute to move the cursor.

text

The string of text in the entry widget.

Setting and getting this attribute calls get, insert and delete documented in ttk_entry(3tk).

class teek.Frame(parent, **kwargs)

An empty widget. Frames are often used as containers for other widgets.

Manual page: ttk_frame(3tk)

class teek.Label(parent, text='', **kwargs)

A widget that displays text.

For convenience, the text option can be also given as a positional initialization argument, so teek.Label(parent, "hello") and teek.Label(parent, text="hello") do the same thing.

Manual page: ttk_label(3tk)

class teek.LabelFrame(parent, text='', **kwargs)

A frame with a visible border line and title text.

For convenience, the text option can be given as with Label.

Manual page: ttk_labelframe(3tk)

class teek.Menu

See Menu Widget.

class teek.Notebook

See Notebook Widget.

class teek.Progressbar(parent, **kwargs)

Displays progress of a long-running operation. This is useful if you are running something concurrently and you want to let the user know that something is happening.

The progress bar can be used in two modes. Pass mode='indeterminate' and call start() to make the progress bar bounce back and forth forever. If you want to create a progress bar that actually displays progress instead of just letting the user know that something is happening, don’t pass mode='indeterminate'; the default is mode='determinate', which does what you want.

There’s a 'value' option that can be used to set the progress in determinate mode. A value of 0 means that nothing is done, and 100 means that we are ready. If you do math on a regular basis, that’s all you need to know, but if you are not very good at math, keep reading:

Progress Math

If your program does 5 things, and 2 of them are done, you should do this:

progress_bar.config['value'] = (2 / 5) * 100

It works like this:

• The program has done 2 things out of 5; that is, 2/5. That is a division. Its value turns out to be 0.4.
• We want percents. They are numbers between 0 and 100. The done / total calculation gives us a number between 0 and 1; if we have done nothing, we have 0 / 5 == 0.0, and if we have done everything, we have 5 / 5 == 1.0. If we add * 100, we get 0.0 * 100 = 0.0 when we haven’t done anything, and 1.0 * 100 == 100.0 when we have done everything. Awesome!

progress_bar.config['value'] = (done / total) * 100

However, this fails if total == 0:

>>> 1/0
Traceback (most recent call last):
    ...
ZeroDivisionError: division by zero

If we have no work to do and we have done nothing (0/0), then how many percents of the work is done? It doesn’t make sense. You can handle these cases e.g. like this:

if total == 0:
    # 0/0 things done, make the progress bar grayed out because
    # there is no progress to indicate
    progress_bar.state.add('disabled')
else:
    progress_bar.config['value'] = (done / total) * 100

If multiplying by 100 is annoying, you can create the progress bar like this…

progress_bar = teek.Progressbar(parent_widget, maximum=1)

…and then set numbers between 0 and 1 to progress_bar.config['value']:

if total == 0:
    progress_bar.state.add('disabled')
else:
    progress_bar.config['value'] = done / total

Manual page: ttk_progressbar(3tk)

start(interval=50)

Makes an indeterminate mode progress bar bounce back and forth.

The progress bar will move by a tiny bit every interval milliseconds. A small interval makes the progress bar look smoother, but don’t make it too small to avoid keeping CPU usage down. The default should be good enough for most things.

stop()

Stops the bouncing started by start().

class teek.Scrollbar(parent, **kwargs)

A widget for scrolling other widgets, like Text.

In order to use a scrollbar, there are two things you need to do:

1. Tell a scrollable widget (e.g. Text) to use the scrollbar.
2. Tell the scrollbar to scroll the widget.

For example:

import teek

window = teek.Window()

text = teek.Text(window)
text.pack(side='left', fill='both', expand=True)
scrollbar = teek.Scrollbar(window)
scrollbar.pack(side='left', fill='y')

text.config['yscrollcommand'].connect(scrollbar.set)  # 1.
scrollbar.config['command'].connect(text.yview)       # 2.

window.on_delete_window.connect(teek.quit)
teek.run()

The value of the scrollbar’s 'command' option is a Callback that runs when the scrollbar is scrolled. It runs with arguments suitable for Text.xview() or Text.yview(). See SCROLLING COMMANDS in ttk_scrollbar(3tk) for details about the arguments.

Manual page: ttk_scrollbar(3tk)

get()

Return a two-tuple of floats that have been passed to set().

See also pathName get in ttk_scrollbar(3tk).

set(first, last)

Set the scrollbar’s position.

See pathName set in ttk_scrollbar(3tk) for details.

class teek.Separator(parent, **kwargs)

A horizontal or vertical line, depending on an orient option.

Create a horizontal separator like this…

separator = teek.Separator(some_widget, orient='horizontal')
separator.pack(fill='x')    # default is side='top'

…and create a vertical separator like this:

separator = teek.Separator(some_widget, orient='vertical')
separator.pack(fill='y', side='left')   # can also use side='right'

See examples/separator.py for more example code.

Manual page: ttk_separator(3tk)

class teek.Spinbox(parent, *, command=None, **kwargs)

An entry with up and down buttons.

This class inherits from Entry, so it has all the attributes and methods of Entry, like text and cursor_pos.

The value of the 'command' option is a Callback that is ran with no arguments. If a command keyword argument is given, it will be connected to the callback automatically.

Manual page: ttk_spinbox(3tk)

class teek.Text

See Text Widget.

class teek.Toplevel(title=None, **options)

This represents a non-Ttk toplevel widget.

Usually it’s easiest to use Window instead. It behaves like a Toplevel widget, but it’s actually a Toplevel with a Frame inside it.

Manual page: toplevel(3tk)

geometry(width=None, height=None, x=None, y=None)

Set or get the size and place of the window in pixels.

Tk’s geometries are strings like '100x200+300+400', but that’s not very pythonic, so this method works with integers and namedtuples instead. This method can be called in a few different ways:

• If width and height are given, the window is resized.
• If x and y are given, the window is moved.
• If all arguments are given, the window is resized and moved.
• If no arguments are given, the current geometry is returned as a namedtuple with width, height, x and y fields.
• Calling this method otherwise raises an error.

Examples:

>>> import teek
>>> window = teek.Window()
>>> window.geometry(300, 200)    # resize to 300px wide, 200px high
>>> window.geometry(x=0, y=0)    # move to upper left corner
>>> window.geometry()            
Geometry(width=300, height=200, x=0, y=0)
>>> window.geometry().width      
300

See also wm geometry in wm(3tk).

iconphoto(*images, default=False)

Calls wm iconphoto documented in wm(3tk).

Positional arguments should be Image objects. If default=True is given, the -default switch is used; otherwise it isn’t.

title

wm_state

transient

minsize

maxsize

withdraw()

iconify()

deiconify()

These attributes and methods correspond to similarly named things in wm(3tk). Note that wm_state is state in the manual page; the teek attribute is wm_state to make it explicit that it is the wm state, not some other state.

All of the attributes are settable, so you can do e.g. my_toplevel.title = "lol". Here are the types of the attributes:

• title and wm_state are strings.
• transient is a widget.
• minsize and maxsize are tuples of two integers.

Note

If transient is set to a Window, looking it up won’t give back that same window; instead, it gives the toplevel of the window.

wait_window()

Waits until the window is destroyed with destroy().

This method blocks until the window is destroyed, but it can still be called from the event loop; behind the covers, it runs another event loop that makes the GUI not freeze.

See tkwait window in tkwait(3tk) for more details.

on_delete_window

on_take_focus

Callback objects that run with no arguments when a WM_DELETE_WINDOW or WM_TAKE_FOCUS event occurs. See wm(3tk). These are connected to nothing by default.

class teek.Window(*args, **kwargs)

A convenient widget that represents a Ttk frame inside a toplevel.

Tk’s windows like Toplevel are not Ttk widgets, and there are no Ttk window widgets. If you add Ttk widgets to Tk windows like Toplevel so that the widgets don’t fill the entire window, your GUI looks messy on some systems, like my linux system with MATE desktop. This is why you should always create a big Ttk frame that fills the window, and then add all widgets into that frame. That’s kind of painful and most people don’t bother with it, but this class does that for you, so you can just create a Window and add widgets to that.

All initialization arguments are passed to Toplevel.

The config attribute combines options from the Frame and the Toplevel so that it uses Frame options whenever they are available, and Toplevel options otherwise. For example, Frame has an option named 'width', so some_window.config['width'] uses that, but frames don’t have a 'menu' option, so some_window.config['menu'] uses the toplevel’s menu option.

There is no manual page for this class because this is purely a teek feature; there is no window widget in Tk.

See also

Toplevel, Frame

toplevel

The Toplevel widget that the frame is in. The Window object itself has all the attributes and methods of the Frame inside the window, and for convenience, also many Toplevel things like title, withdraw() and on_delete_window.

destroy()

Destroys the toplevel and the frame in it.

This overrides Widget.destroy().