TheTkinter module (“Tk interface”) is the standard Python interface tothe Tk GUI toolkit. Both Tk andTkinter are available on most Unixplatforms, as well as on Windows systems. (Tk itself is not part of Python; itis maintained at ActiveState.)
Note
Tkinter has been renamed totkinter in Python 3. The2to3 tool will automatically adapt imports when converting yoursources to Python 3.
See also
Most of the time, theTkinter module is all you really need, but a numberof additional modules are available as well. The Tk interface is located in abinary module named_tkinter. This module contains the low-levelinterface to Tk, and should never be used directly by application programmers.It is usually a shared library (or DLL), but might in some cases be staticallylinked with the Python interpreter.
In addition to the Tk interface module,Tkinter includes a number ofPython modules. The two most important modules are theTkinter moduleitself, and a module calledTkconstants. The former automatically importsthe latter, so to use Tkinter, all you need to do is to import one module:
importTkinter
Or, more often:
fromTkinterimport*
TheTk class is instantiated without arguments. This creates a toplevelwidget of Tk which usually is the main window of an application. Each instancehas its own associated Tcl interpreter.
Changed in version 2.4:TheuseTk parameter was added.
TheTcl() function is a factory function which creates an object much likethat created by theTk class, except that it does not initialize the Tksubsystem. This is most often useful when driving the Tcl interpreter in anenvironment where one doesn’t want to create extraneous toplevel windows, orwhere one cannot (such as Unix/Linux systems without an X server). An objectcreated by theTcl() object can have a Toplevel window created (and the Tksubsystem initialized) by calling itsloadtk() method.
New in version 2.4.
Other modules that provide Tk support include:
These have been renamed as well in Python 3; they were all made submodules ofthe newtkinter package.
This section is not designed to be an exhaustive tutorial on either Tk orTkinter. Rather, it is intended as a stop gap, providing some introductoryorientation on the system.
Credits:
This section is designed in two parts: the first half (roughly) coversbackground material, while the second half can be taken to the keyboard as ahandy reference.
When trying to answer questions of the form “how do I do blah”, it is often bestto find out how to do”blah” in straight Tk, and then convert this back into thecorrespondingTkinter call. Python programmers can often guess at thecorrect Python command by looking at the Tk documentation. This means that inorder to use Tkinter, you will have to know a little bit about Tk. This documentcan’t fulfill that role, so the best we can do is point you to the bestdocumentation that exists. Here are some hints:
See also
fromTkinterimport*classApplication(Frame):defsay_hi(self):print"hi there, everyone!"defcreateWidgets(self):self.QUIT=Button(self)self.QUIT["text"]="QUIT"self.QUIT["fg"]="red"self.QUIT["command"]=self.quitself.QUIT.pack({"side":"left"})self.hi_there=Button(self)self.hi_there["text"]="Hello",self.hi_there["command"]=self.say_hiself.hi_there.pack({"side":"left"})def__init__(self,master=None):Frame.__init__(self,master)self.pack()self.createWidgets()root=Tk()app=Application(master=root)app.mainloop()root.destroy()
The class hierarchy looks complicated, but in actual practice, applicationprogrammers almost always refer to the classes at the very bottom of thehierarchy.
Notes:
To make use of this reference material, there will be times when you will needto know how to read short passages of Tk and how to identify the various partsof a Tk command. (See sectionMapping Basic Tk into Tkinter for theTkinter equivalents of what’s below.)
Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are just listsof tokens separated by spaces. A Tk widget is just itsclass, theoptionsthat help configure it, and theactions that make it do useful things.
To make a widget in Tk, the command is always of the form:
classCommand newPathname options
For example:
button .fred -fg red -text "hi there" ^ ^ \_____________________/ | | | class new optionscommand widget (-opt val -opt val ...)
Once created, the pathname to the widget becomes a new command. This newwidget command is the programmer’s handle for getting the new widget toperform someaction. In C, you’d express this as someAction(fred,someOptions), in C++, you would express this as fred.someAction(someOptions),and in Tk, you say:
.fred someAction someOptions
Note that the object name,.fred, starts with a dot.
As you’d expect, the legal values forsomeAction will depend on the widget’sclass:.freddisable works if fred is a button (fred gets greyed out), butdoes not work if fred is a label (disabling of labels is not supported in Tk).
The legal values ofsomeOptions is action dependent. Some actions, likedisable, require no arguments, others, like a text-entry box’sdeletecommand, would need arguments to specify what range of text to delete.
Class commands in Tk correspond to class constructors in Tkinter.
button .fred =====> fred = Button()
The master of an object is implicit in the new name given to it at creationtime. In Tkinter, masters are specified explicitly.
button .panel.fred =====> fred = Button(panel)
The configuration options in Tk are given in lists of hyphened tags followed byvalues. In Tkinter, options are specified as keyword-arguments in the instanceconstructor, and keyword-args for configure calls or as instance indices, indictionary style, for established instances. See sectionSetting Options on setting options.
button .fred -fg red =====> fred = Button(panel, fg = "red").fred configure -fg red =====> fred["fg"] = red OR ==> fred.config(fg = "red")
In Tk, to perform an action on a widget, use the widget name as a command, andfollow it with an action name, possibly with arguments (options). In Tkinter,you call methods on the class instance to invoke actions on the widget. Theactions (methods) that a given widget can perform are listed in the Tkinter.pymodule.
.fred invoke =====> fred.invoke()
To give a widget to the packer (geometry manager), you call pack with optionalarguments. In Tkinter, the Pack class holds all this functionality, and thevarious forms of the pack command are implemented as methods. All widgets inTkinter are subclassed from the Packer, and so inherit all the packingmethods. See theTix module documentation for additional information onthe Form geometry manager.
pack .fred -side left =====> fred.pack(side = "left")
From the top down:
Options control things like the color and border width of a widget. Options canbe set in three ways:
fred=Button(self,fg="red",bg="blue")
fred["fg"]="red"fred["bg"]="blue"
fred.config(fg="red",bg="blue")
For a complete explanation of a given option and its behavior, see the Tk manpages for the widget in question.
Note that the man pages list “STANDARD OPTIONS” and “WIDGET SPECIFIC OPTIONS”for each widget. The former is a list of options that are common to manywidgets, the latter are the options that are idiosyncratic to that particularwidget. The Standard Options are documented on theoptions(3) manpage.
No distinction between standard and widget-specific options is made in thisdocument. Some options don’t apply to some kinds of widgets. Whether a givenwidget responds to a particular option depends on the class of the widget;buttons have acommand option, labels do not.
The options supported by a given widget are listed in that widget’s man page, orcan be queried at runtime by calling theconfig() method withoutarguments, or by calling thekeys() method on that widget. The returnvalue of these calls is a dictionary whose key is the name of the option as astring (for example,'relief') and whose values are 5-tuples.
Some options, likebg are synonyms for common options with long names(bg is shorthand for “background”). Passing theconfig() method the nameof a shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple passedback will contain the name of the synonym and the “real” option (such as('bg','background')).
| Index | Meaning | Example |
|---|---|---|
| 0 | option name | 'relief' |
| 1 | option name for database lookup | 'relief' |
| 2 | option class for databaselookup | 'Relief' |
| 3 | default value | 'raised' |
| 4 | current value | 'groove' |
Example:
>>>printfred.config(){'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
Of course, the dictionary printed will include all the options available andtheir values. This is meant only as an example.
The packer is one of Tk’s geometry-management mechanisms. Geometry managersare used to specify the relative positioning of the positioning of widgetswithin their container - their mutualmaster. In contrast to the morecumbersomeplacer (which is used less commonly, and we do not cover here), thepacker takes qualitative relationship specification -above,to the left of,filling, etc - and works everything out to determine the exact placementcoordinates for you.
The size of anymaster widget is determined by the size of the “slave widgets”inside. The packer is used to control where slave widgets appear inside themaster into which they are packed. You can pack widgets into frames, and framesinto other frames, in order to achieve the kind of layout you desire.Additionally, the arrangement is dynamically adjusted to accommodate incrementalchanges to the configuration, once it is packed.
Note that widgets do not appear until they have had their geometry specifiedwith a geometry manager. It’s a common early mistake to leave out the geometryspecification, and then be surprised when the widget is created but nothingappears. A widget will appear only after it has had, for example, the packer’spack() method applied to it.
The pack() method can be called with keyword-option/value pairs that controlwhere the widget is to appear within its container, and how it is to behave whenthe main application window is resized. Here are some examples:
fred.pack()# defaults to side = "top"fred.pack(side="left")fred.pack(expand=1)
For more extensive information on the packer and the options that it can take,see the man pages and page 183 of John Ousterhout’s book.
The current-value setting of some widgets (like text entry widgets) can beconnected directly to application variables by using special options. Theseoptions arevariable,textvariable,onvalue,offvalue, andvalue. This connection works both ways: if the variable changes for anyreason, the widget it’s connected to will be updated to reflect the new value.
Unfortunately, in the current implementation ofTkinter it is notpossible to hand over an arbitrary Python variable to a widget through avariable ortextvariable option. The only kinds of variables for whichthis works are variables that are subclassed from a class called Variable,defined in theTkinter module.
There are many useful subclasses of Variable already defined:StringVar,IntVar,DoubleVar, andBooleanVar. To read the current value of such a variable, call theget() method on it, and to change its value you call theset()method. If you follow this protocol, the widget will always track the value ofthe variable, with no further intervention on your part.
For example:
classApp(Frame):def__init__(self,master=None):Frame.__init__(self,master)self.pack()self.entrythingy=Entry()self.entrythingy.pack()# here is the application variableself.contents=StringVar()# set it to some valueself.contents.set("this is a variable")# tell the entry widget to watch this variableself.entrythingy["textvariable"]=self.contents# and here we get a callback when the user hits return.# we will have the program print out the value of the# application variable when the user hits returnself.entrythingy.bind('<Key-Return>',self.print_contents)defprint_contents(self,event):print"hi. contents of entry is now ---->", \self.contents.get()
In Tk, there is a utility command,wm, for interacting with the windowmanager. Options to thewm command allow you to control things like titles,placement, icon bitmaps, and the like. InTkinter, these commands havebeen implemented as methods on theWm class. Toplevel widgets aresubclassed from theWm class, and so can call theWm methodsdirectly.
To get at the toplevel window that contains a given widget, you can often justrefer to the widget’s master. Of course if the widget has been packed inside ofa frame, the master won’t represent a toplevel window. To get at the toplevelwindow that contains an arbitrary widget, you can call the_root() method.This method begins with an underscore to denote the fact that this function ispart of the implementation, and not an interface to Tk functionality.
Here are some examples of typical usage:
fromTkinterimport*classApp(Frame):def__init__(self,master=None):Frame.__init__(self,master)self.pack()# create the applicationmyapp=App()## here are method calls to the window manager class#myapp.master.title("My Do-Nothing Application")myapp.master.maxsize(1000,400)# start the programmyapp.mainloop()
This is any Python function that takes no arguments. For example:
defprint_it():print"hi there"fred["command"]=print_it
The bind method from the widget command allows you to watch for certain eventsand to have a callback function trigger when that event type occurs. The formof the bind method is:
def bind(self, sequence, func, add=''):
where:
For example:
defturnRed(self,event):event.widget["activeforeground"]="red"self.button.bind("<Enter>",self.turnRed)
Notice how the widget field of the event is being accessed in theturnRed() callback. This field contains the widget that caught the Xevent. The following table lists the other event fields you can access, and howthey are denoted in Tk, which can be useful when referring to the Tk man pages.
Tk Tkinter Event Field Tk Tkinter Event Field-- ------------------- -- -------------------%f focus %A char%h height %E send_event%k keycode %K keysym%s state %N keysym_num%t time %T type%w width %W widget%x x %X x_root%y y %Y y_root
A number of widgets require”index” parameters to be passed. These are used topoint at a specific place in a Text widget, or to particular characters in anEntry widget, or to particular menu items in a Menu widget.
Entry widgets have options that refer to character positions in the text beingdisplayed. You can use theseTkinter functions to access these specialpoints in text widgets:
Some options and methods for menus manipulate specific menu entries. Anytime amenu index is needed for an option or a parameter, you may pass in:
Bitmap/Pixelmap images can be created through the subclasses ofTkinter.Image:
Either type of image is created through either thefile or thedataoption (other options are available as well).
The image object can then be used wherever animage option is supported bysome widget (e.g. labels, buttons, menus). In these cases, Tk will not keep areference to the image. When the last Python reference to the image object isdeleted, the image data is deleted as well, and Tk will display an empty boxwherever the image was used.
24. Graphical User Interfaces with Tk
Enter search terms or a module, class or function name.
