How To Use This Section¶

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:

• The authors strongly suggest getting a copy of the Tk man pages.Specifically, the man pages in themanN directory are most useful.Theman3 man pages describe the C interface to the Tk library and thusare not especially helpful for script writers.

• Addison-Wesley publishes a book called Tcl and the Tk Toolkit by JohnOusterhout (ISBN 0-201-63337-X) which is a good introduction to Tcl and Tk forthe novice. The book is not exhaustive, and for many details it defers to theman pages.

• tkinter/__init__.py is a last resort for most, but can be a goodplace to go when nothing else makes sense.

A Simple Hello World Program¶

importtkinterastkclassApplication(tk.Frame):def__init__(self,master=None):super().__init__(master)self.master=masterself.pack()self.create_widgets()defcreate_widgets(self):self.hi_there=tk.Button(self)self.hi_there["text"]="Hello World\n(click me)"self.hi_there["command"]=self.say_hiself.hi_there.pack(side="top")self.quit=tk.Button(self,text="QUIT",fg="red",command=self.master.destroy)self.quit.pack(side="bottom")defsay_hi(self):print("hi there, everyone!")root=tk.Tk()app=Application(master=root)app.mainloop()

Setting Options¶

Options control things like the color and border width of a widget. Options canbe set in three ways:

At object creation time, using keyword arguments

fred=Button(self,fg="red",bg="blue")

After object creation, treating the option name like a dictionary index

fred["fg"]="red"fred["bg"]="blue"

Use the config() method to update multiple attrs subsequent to object creation

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')).

Example:

>>>print(fred.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¶

The packer is one of Tk’s geometry-management mechanisms. Geometry managersare used to specify the relative positioning of widgets within their container -their mutualmaster. In contrast to the more cumbersomeplacer (which isused less commonly, and we do not cover here), the packer takes qualitativerelationship specification -above,to the left of,filling, etc - andworks everything out to determine the exact placement coordinates 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)

Packer Options¶

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.

anchor

Anchor type. Denotes where the packer is to place each slave in its parcel.

expand

Boolean,0 or1.

fill

Legal values:'x','y','both','none'.

ipadx and ipady

A distance - designating internal padding on each side of the slave widget.

padx and pady

A distance - designating external padding on each side of the slave widget.

side

Legal values are:'left','right','top','bottom'.

Coupling Widget Variables¶

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 intkinter.

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:

importtkinterastkclassApp(tk.Frame):def__init__(self,master):super().__init__(master)self.pack()self.entrythingy=tk.Entry()self.entrythingy.pack()# Create the application variable.self.contents=tk.StringVar()# Set it to some value.self.contents.set("this is a variable")# Tell the entry widget to watch this variable.self.entrythingy["textvariable"]=self.contents# Define a callback for when the user hits return.# It prints the current value of the variable.self.entrythingy.bind('<Key-Return>',self.print_contents)defprint_contents(self,event):print("Hi. The current entry content is:",self.contents.get())root=tk.Tk()myapp=App(root)myapp.mainloop()

The Window Manager¶

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:

importtkinterastkclassApp(tk.Frame):def__init__(self,master=None):super().__init__(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()

Tk Option Data Types¶

anchor

Legal values are points of the compass:"n","ne","e","se","s","sw","w","nw", and also"center".

bitmap

There are eight built-in, named bitmaps:'error','gray25','gray50','hourglass','info','questhead','question','warning'. To specify an X bitmap filename, give the full path to the file,preceded with an@, as in"@/usr/contrib/bitmap/gumby.bit".

boolean

You can pass integers 0 or 1 or the strings"yes" or"no".

callback

This is any Python function that takes no arguments. For example:

defprint_it():print("hi there")fred["command"]=print_it

color

Colors can be given as the names of X colors in the rgb.txt file, or as stringsrepresenting RGB values in 4 bit:"#RGB", 8 bit:"#RRGGBB", 12 bit:"#RRRGGGBBB", or 16 bit:"#RRRRGGGGBBBB" ranges, where R,G,B hererepresent any legal hex digit. See page 160 of Ousterhout’s book for details.

cursor

The standard X cursor names fromcursorfont.h can be used, without theXC_ prefix. For example to get a hand cursor (XC_hand2), use thestring"hand2". You can also specify a bitmap and mask file of your own.See page 179 of Ousterhout’s book.

distance

Screen distances can be specified in either pixels or absolute distances.Pixels are given as numbers and absolute distances as strings, with the trailingcharacter denoting units:c for centimetres,i for inches,m formillimetres,p for printer’s points. For example, 3.5 inches is expressedas"3.5i".

font

Tk uses a list font name format, such as{courier10bold}. Font sizes withpositive numbers are measured in points; sizes with negative numbers aremeasured in pixels.

geometry

This is a string of the formwidthxheight, where width and height aremeasured in pixels for most widgets (in characters for widgets displaying text).For example:fred["geometry"]="200x100".

justify

Legal values are the strings:"left","center","right", and"fill".

region

This is a string with four space-delimited elements, each of which is a legaldistance (see above). For example:"2345" and"3i2i4.5i2i" and"3c2c4c10.43c" are all legal regions.

relief

Determines what the border style of a widget will be. Legal values are:"raised","sunken","flat","groove", and"ridge".

scrollcommand

This is almost always theset() method of some scrollbar widget, but canbe any widget method that takes a single argument.

wrap

Must be one of:"none","char", or"word".

Bindings and Events¶

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:

defbind(self,sequence,func,add=''):

where:

sequence

is a string that denotes the target kind of event. (See the bind man page andpage 201 of John Ousterhout’s book for details).

func

is a Python function, taking one argument, to be invoked when the event occurs.An Event instance will be passed as the argument. (Functions deployed this wayare commonly known ascallbacks.)

add

is optional, either'' or'+'. Passing an empty string denotes thatthis binding is to replace any other bindings that this event is associatedwith. Passing a'+' means that this function is to be added to the listof functions bound to this event type.

For example:

defturn_red(self,event):event.widget["activeforeground"]="red"self.button.bind("<Enter>",self.turn_red)

Notice how the widget field of the event is being accessed in theturn_red() 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.

The index Parameter¶

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 widget indexes (index, view index, etc.)

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:

Text widget indexes

The index notation for Text widgets is very rich and is best described in the Tkman pages.

Menu indexes (menu.invoke(), menu.entryconfig(), etc.)

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:

• an integer which refers to the numeric position of the entry in the widget,counted from the top, starting with 0;

• the string"active", which refers to the menu position that is currentlyunder the cursor;

• the string"last" which refers to the last menu item;

• An integer preceded by@, as in@6, where the integer is interpretedas a y pixel coordinate in the menu’s coordinate system;

• the string"none", which indicates no menu entry at all, most often usedwith menu.activate() to deactivate all entries, and finally,

• a text string that is pattern matched against the label of the menu entry, asscanned from the top of the menu to the bottom. Note that this index type isconsidered after all the others, which means that matches for menu itemslabelledlast,active, ornone may be interpreted as the aboveliterals, instead.

Images¶

Images of different formats can be created through the corresponding subclassoftkinter.Image:

• BitmapImage for images in XBM format.

• PhotoImage for images in PGM, PPM, GIF and PNG formats. The latteris supported starting with Tk 8.6.

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.