We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

Widget Configuration

To control the appearance of a widget, you usually use options rather than method calls. Typical options include text and color, size, command callbacks, etc. To deal with options, all core widgets implement the same configuration interface:

Configuration Interface

widgetclass(master, option=value, …) => widget

(where widgetclass is one of the widget classes mentioned earlier)

Create an instance of this widget class, as a child to the given master, and using the given options. All options have default values, so in the simplest case, you only have to specify the master. You can even leave that out if you really want; Tkinter then uses the most recently created root window as master. Note that the name option can only be set when the widget is created.

cget(“option”) => string

Return the current value of an option. Both the option name, and the returned value, are strings. To get the name option, use str(widget) instead.

config(option=value, …)

configure(option=value, …)

Set one or more options (given as keyword arguments).

Note that some options have names that are reserved words in Python (class, from, …). To use these as keyword arguments, simply append an underscore to the option name (class_, from_, …). Note that you cannot set the name option using this method; it can only be set when the widget is created.

For convenience, the widgets also implement a partial dictionary interface. The __setitem__ method maps to configure, while __getitem__ maps to cget. As a result, you can use the following syntax to set and query options:

value = widget["option"]
widget["option"] = value

Note that each assignment results in one call to Tk. If you wish to change multiple options, it is usually a better idea to change them with a single call to config or configure (personally, I prefer to always change options in that fashion).

The following dictionary method also works for widgets:

keys() => list

Return a list of all options that can be set for this widget. The name option is not included in this list (it cannot be queried or modified through the dictionary interface anyway, so this doesn’t really matter).

Backwards Compatibility

Keyword arguments were introduced in Python 1.3. Before that, options were passed to the widget constructors and configure methods using ordinary Python dictionaries. The source code could then look something like this:

self.button = Button(frame, {"text": "QUIT", "fg": "red", "command": frame.quit})
self.button.pack({"side": LEFT})

The keyword argument syntax is of course much more elegant, and less error prone. However, for compatibility with existing code, Tkinter still supports the older syntax. You shouldn’t use this syntax in new programs, even if it might be tempting in some cases. For example, if you create a custom widget which needs to pass configuration options along to its parent class, you may come up with something like:

def __init__(self, master, **kw):
    Canvas.__init__(self, master, kw) # kw is a dictionary

This works just fine with the current version of Tkinter, but it may not work with future versions. A more general approach is to use the apply function:

def __init__(self, master, **kw):
    apply(Canvas.__init__, (self, master), kw)

The apply function takes a function (an unbound method, in this case), a tuple with arguments (which must include self since we’re calling an unbound method), and optionally, a dictionary which provides the keyword arguments.