A Hello World Program¶

We’ll start by walking through a “Hello World” application in Tkinter. Thisisn’t the smallest one we could write, but has enough to illustrate somekey concepts you’ll need to know.

fromtkinterimport*fromtkinterimportttkroot=Tk()frm=ttk.Frame(root,padding=10)frm.grid()ttk.Label(frm,text="Hello World!").grid(column=0,row=0)ttk.Button(frm,text="Quit",command=root.destroy).grid(column=1,row=0)root.mainloop()

After the imports, the next line creates an instance of theTk class,which initializes Tk and creates its associated Tcl interpreter. It alsocreates a toplevel window, known as the root window, which serves as the mainwindow of the application.

The following line creates a frame widget, which in this case will containa label and a button we’ll create next. The frame is fit inside the rootwindow.

The next line creates a label widget holding a static text string. Thegrid() method is used to specify the relative layout (position) of thelabel within its containing frame widget, similar to how tables in HTML work.

A button widget is then created, and placed to the right of the label. Whenpressed, it will call thedestroy() method of the root window.

Finally, themainloop() method puts everything on the display, andresponds to user input until the program terminates.

Important Tk Concepts¶

Even this simple program illustrates the following key Tk concepts:

widgets

A Tkinter user interface is made up of individualwidgets. Each widget isrepresented as a Python object, instantiated from classes likettk.Frame,ttk.Label, andttk.Button.

widget hierarchy

Widgets are arranged in ahierarchy. The label and button were containedwithin a frame, which in turn was contained within the root window. Whencreating eachchild widget, itsparent widget is passed as the firstargument to the widget constructor.

configuration options

Widgets haveconfiguration options, which modify their appearance andbehavior, such as the text to display in a label or button. Differentclasses of widgets will have different sets of options.

geometry management

Widgets aren’t automatically added to the user interface when they arecreated. Ageometry manager likegrid controls where in theuser interface they are placed.

event loop

Tkinter reacts to user input, changes from your program, and even refreshesthe display only when actively running anevent loop. If your programisn’t running the event loop, your user interface won’t update.

Understanding How Tkinter Wraps Tcl/Tk¶

When your application uses Tkinter’s classes and methods, internally Tkinteris assembling strings representing Tcl/Tk commands, and executing thosecommands in the Tcl interpreter attached to your application’sTkinstance.

Whether it’s trying to navigate reference documentation, trying to findthe right method or option, adapting some existing code, or debugging yourTkinter application, there are times that it will be useful to understandwhat those underlying Tcl/Tk commands look like.

To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinterscript above.

ttk::frame.frm-padding10grid.frmgrid[ttk::label.frm.lbl-text"Hello World!"]-column0-row0grid[ttk::button.frm.btn-text"Quit"-command"destroy ."]-column1-row0

Tcl’s syntax is similar to many shell languages, where the first word is thecommand to be executed, with arguments to that command following it, separatedby spaces. Without getting into too many details, notice the following:

• The commands used to create widgets (likettk::frame) correspond towidget classes in Tkinter.

• Tcl widget options (like-text) correspond to keyword arguments inTkinter.

• Widgets are referred to by apathname in Tcl (like.frm.btn),whereas Tkinter doesn’t use names but object references.

• A widget’s place in the widget hierarchy is encoded in its (hierarchical)pathname, which uses a. (dot) as a path separator. The pathname forthe root window is just. (dot). In Tkinter, the hierarchy is definednot by pathname but by specifying the parent widget when creating eachchild widget.

• Operations which are implemented as separatecommands in Tcl (likegrid ordestroy) are represented asmethods on Tkinter widgetobjects. As you’ll see shortly, at other times Tcl uses what appear to bemethod calls on widget objects, which more closely mirror what would isused in Tkinter.

How do I…? What option does…?¶

If you’re not sure how to do something in Tkinter, and you can’t immediatelyfind it in the tutorial or reference documentation you’re using, there are afew strategies that can be helpful.

First, remember that the details of how individual widgets work may varyacross different versions of both Tkinter and Tcl/Tk. If you’re searchingdocumentation, make sure it corresponds to the Python and Tcl/Tk versionsinstalled on your system.

When searching for how to use an API, it helps to know the exact name of theclass, option, or method that you’re using. Introspection, either in aninteractive Python shell or withprint(), can help you identify whatyou need.

To find out what configuration options are available on any widget, call itsconfigure() method, which returns a dictionary containing a variety ofinformation about each object, including its default and current values. Usekeys() to get just the names of each option.

btn=ttk.Button(frm,...)print(btn.configure().keys())

As most widgets have many configuration options in common, it can be usefulto find out which are specific to a particular widget class. Comparing thelist of options to that of a simpler widget, like a frame, is one way todo that.

print(set(btn.configure().keys())-set(frm.configure().keys()))

Similarly, you can find the available methods for a widget object using thestandarddir() function. If you try it, you’ll see there are over 200common widget methods, so again identifying those specific to a widget classis helpful.

print(dir(btn))print(set(dir(btn))-set(dir(frm)))

Navigating the Tcl/Tk Reference Manual¶

As noted, the officialTk commandsreference manual (man pages) is often the most accurate description of whatspecific operations on widgets do. Even when you know the name of the optionor method that you need, you may still have a few places to look.

While all operations in Tkinter are implemented as method calls on widgetobjects, you’ve seen that many Tcl/Tk operations appear as commands thattake a widget pathname as its first parameter, followed by optionalparameters, e.g.

destroy.grid.frm.btn-column0-row0

Others, however, look more like methods called on a widget object (in fact,when you create a widget in Tcl/Tk, it creates a Tcl command with the nameof the widget pathname, with the first parameter to that command being thename of a method to call).

.frm.btninvoke.frm.lblconfigure-text"Goodbye"

In the official Tcl/Tk reference documentation, you’ll find most operationsthat look like method calls on the man page for a specific widget (e.g.,you’ll find theinvoke() method on thettk::buttonman page), while functions that take a widget as a parameter often havetheir own man page (e.g.,grid).

You’ll find many common options and methods in theoptions orttk::widget manpages, while others are found in the man page for a specific widget class.

You’ll also find that many Tkinter methods have compound names, e.g.,winfo_x(),winfo_height(),winfo_viewable(). You’d finddocumentation for all of these in thewinfo man page.

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 thebind(3tk) man page, and page 201 of John Ousterhout’s book,Tcl and the Tk Toolkit (2nd edition), 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.