Home Contact

TkDocs

Information you need to build high-quality Tk user interfaces.

close

Modern Tkinter ebook If you've found the material on this site useful, please consider purchasing this e-book (only $10), which is based on the Python material in the tutorial. Doing so helps me maintain and update this site. Thank you very much!


 
 
@markroseman
mark@markroseman.com

 

Kindle Buy now for your Kindle
Kindle apps are also available for most smartphones, tablets, and desktops. Payment and download handled by Amazon's Kindle Store.

 

PDF Buy the DRM-free PDF
Downloads handled by SendOwl.com. Payment handled via PayPal
(click "Don't have a PayPal account" to use a credit card).

This tutorial will quickly get you up and running with the latest Tk from Tcl, Ruby, Perl or Python on Mac, Windows or Linux. It provides all the essentials about core Tk concepts, the various widgets, layout, events and more that you need for your application.

 

Installing Tk

In this chapter, you'll get Tk installed on your machine, verify it works, and then see a quick example of what a Tk program looks like.

Though pretty much all Mac OS X and Linux machines come with Tk installed already, it's usually an older version (typically 8.4.x). You want to make sure you've got at least version 8.5 to use the new widget set, so if that's not already there, you'll want to install the newer version.

Though there are lots of ways to install Tk, the easiest is to download and install one of the versions provided by ActiveState (www.activestate.com).

ActiveState is a company that sells professional developer tools for dynamic languages. They also provide (for free) quality-controlled distributions of some of these languages, and happen to employ a number of core developers of these languages.

 

Installing Tk on Mac OS X

On Mac OS X, the easiest way to get Tk is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl, available as a universal binary. Make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Run the installer to get everything loaded onto your machine. When you're done, you'll find a shiny new application called "Wish 8.5" inside the Utilities folder of your Applications folder. This is the "wish" shell, an application that includes both Tcl and Tk.

If you launch that application, you'll see two windows popup (see below), one titled "Wish" which will contain your application, and the second titled "Console" which is where you can type in Tcl/Tk commands.


The Wish application running on Mac OS X.

For convenient use from the Unix command line, you'll also find a script installed as /usr/local/bin/wish8.5 which will launch the same application.

To verify the exact version of Tcl/Tk that you are running, from the Wish console type the following:

% info patchlevel

We want this to be returning something like '8.5.10'.

Verified install using ActiveTcl 8.5.10.1 on Mac OS X 10.7.1.

While previous versions of Mac OS X included both Ruby and Tk (albeit older 8.4 versions), since Snow Leopard this has no longer been the case.

RubyTk is a binding that links against an existing but separate Tk library. So, to get the latest version of Tk for Ruby, we're going to have to do two things, first download the latest 8.5.x Tcl/Tk version from ActiveState, and then compile (or re-compile) Ruby to use it.

Install ActiveTcl

The "ActiveTcl" distribution from ActiveState contains the latest Tk, as well as the latest version of Tcl (which Ruby's Tk bindings use internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl, available as a universal binary. Again, make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Run the installer and everything will be loaded onto your machine.

Compile Ruby

Make sure you've got Apple's developer tools (i.e. Xcode, which includes gcc and friends). Then if you haven't already got it, go to www.ruby-lang.org to download the latest stable (currently 1.9.x) version of Ruby.

Unpack it, and then from the Unix command line, run (note that the "configure" command should all be entered on one line, the <install-dir> should be replaced with the location you'd like your version of Ruby installed:

% ./configure --prefix=<install-dir>
		  --with-arch=x86_64,i386
		  --enable-pthread
		  --enable-shared
% make && make install

To verify that everything worked, start up your newly compiled copy of 'irb', and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk; typically if there was a problem with compiling it would show up here. The second line will return the version of Tk that you're running, which should be something like "8.5.10".

Verified steps using ActiveTcl 8.5.10, Ruby 1.9.3-p0, and Mac OS X 10.7.2.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl, available as a universal binary.

Run the installer and everything will be loaded onto your machine. Note that ActivePerl will be installed in /usr/local/ActivePerl-5.x (where 'x' is the actual version, e.g. '14').

To find out what version of Tk Perl and Tkx are using, run this from the Unix command line:

% /usr/local/ActivePerl-5.14/bin/perl -MTkx -e 'print Tkx::info("patchlevel");'

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.

Verified install using ActivePerl 5.14.2 on Mac OS X 10.7.2.

Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions. It is important that you use a version of Python supporting Tk 8.5 or greater, and ttk. We recommend installing the "ActivePython" distribution from ActiveState, which includes everything you'll need.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePython for Mac OS X, available as a universal binary. Make sure you're downloading a 3.1 or newer version.

Run the installer and follow allong. You'll end up with a fresh install of ActivePython in /Library/Frameworks, along with links to the versioned Python binaries placed in /usr/local/bin (e.g. 'python3.2' if you downloaded ActivePython 3.2.x). From a Terminal window you should then be able to run a Python shell:

% /usr/local/bin/python3.2

This should give you the Python command prompt. From the prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.5"; make sure it is not 8.4!

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.5.10'.

Verified install using ActivePython 3.2.1.2 on Mac OS X 10.7.1.

 

Installing Tk on Windows

On Windows, the easiest way to get Tcl/Tk onto your machine is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Windows. Make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Run the installer, and follow along. You'll end up with a fresh install of ActiveTcl, usually located in C:\Tcl. From a DOS command prompt, or the Start Menu's "Run..." command, you should then be able to run a Tcl/Tk 8.5 shell via:

% C:\Tcl\bin\wish85

This should pop up a small window titled "wish85", which will contain your application. A second, larger window titled "Console" is where you can type in Tcl/Tk commands. To verify the exact version of Tcl/Tk that you are running, type the following:

% info patchlevel

We want this to be returning something like '8.5.10'.

Type "exit" in the console window to exit. You may also want to add C:\Tcl\bin to your PATH environment variable.

Verified install using ActiveTcl 8.5.10.1 on Windows 7.

RubyTk is the binding for Tk. Installing it on your Windows machine used to be pure hell, involving installing a separate version of Tcl/Tk, downloading a development environment like Visual Studio, downloading the Ruby source code, carefully compiling Ruby, ...

Luckily, it is (since July 2011) now remarkably easy, because the good RubyInstaller for Windows people now include Tk 8.5 as part of their excellent and easy to use installer. Thanks very much!

So all you'll need to do is download and run RubyInstaller, making sure to check the option in the installer to include Tcl/Tk support. This will install everything into the directory you choose, e.g. "C:\Ruby192".

To verify the version of Tk, start up your newly installed copy of 'irb' (which would have been installed in e.g. "C:\Ruby192\bin"), and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk. The second line will return the version of Tk that you're running, which should be something like "8.5.10".

Verified install using RubyInstaller 1.9.2-p290 on Windows 7.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl.

Run the installer and everything will be loaded onto your machine. On our machine, perl.exe was installed at "C:\perlin"

To find out what version of Tk Perl and Tkx are using, run this from the Windows command prompt:

% perl -MTkx -e "print Tkx::info("patchlevel");"

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.

Verified install using ActivePerl 5.12.4 on Windows 7.

Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions. It is important that you use a version of Python supporting Tk 8.5 or greater, and ttk. We recommend installing the "ActivePython" distribution from ActiveState, which includes everything you'll need.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePython for Windows. Make sure you're downloading a 3.1 or newer version, not a 2.x version.

Run the installer, and follow along. You'll end up with a fresh install of ActivePython, located in, e.g. C:\python32. From a Windows command prompt, or the Start Menu's "Run..." command, you should then be able to run a Python shell via:

% C:\python32\python

This should give you the Python command prompt. From the prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.5"; make sure it is not 8.4!

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.5.9'.

Verified install using ActivePython 3.2.1.2 on Windows 7.

 

Installing Tk on Linux

While Linux distributions pretty much all come with Tcl/Tk installed, most include Tk 8.4.x, and we want to make sure to get an 8.5.x version. The easiest way to do this is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Linux. Make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Unpack it, and run the installer (install.sh), and follow along. You'll end up with a fresh install of ActiveTcl, located in /opt/ActiveTcl-8.5. You should then be able to run a Tcl/Tk 8.5 shell via:

% /opt/ActiveTcl-8.5/bin/wish8.5

This should pop up a window titled "wish8.5". To verify the exact version of Tcl/Tk that you are running, from the Wish prompt (in the terminal window) type the following:

	% info patchlevel

We want this to be returning something like '8.5.10'. Type a control-D at the prompt in the terminal window to exit. You may also want to add /opt/ActiveTcl-8.5/bin to your Unix path.

Verified install using ActiveTcl 8.5.10.1 on Ubuntu 11.04.

While Linux distributions pretty much all come with both Tk and Ruby installed, one of them (or the connection between them) is usually very out of date.

RubyTk is a binding that links against an existing but separate Tk library. So, to get the latest version of Tk for Ruby, we're going to have to do two things, first download the latest 8.5.x Tcl/Tk version from ActiveState, and then compile Ruby to use it.

And don't think you're going to get away with just doing an apt-get with one of the prebuilt Ruby packages, oh no. Even the RubyTk packages for the newest Ruby versions still tend to be built against Tk 8.4. It's not like Tk 8.5 hasn't been out of beta for (as of this writing) almost five years...

Install ActiveTcl

The "ActiveTcl" distribution from ActiveState contains the latest Tk, as well as the latest version of Tcl (which Ruby's Tk bindings use internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Linux. Again, make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Unpack it, and run the installer (install.sh), and follow along. You'll end up with a fresh install of ActiveTcl, located in /opt/ActiveTcl-8.5.

Setup your Development Environment

You'll need to make sure you have a fairly robust development environment on your machine. Besides the usual gcc and friends, make sure that you've got the X11 development files (e.g. all the include files; on Ubuntu there were included in the "libx11-dev" package).

Really, you need the X11 development files to compile, even though ActiveTcl is prebuilt and so doesn't need them. I wasted hours on this playing with various options, because the error messages if the headers aren't there are either missing or misleading.

Compile Ruby

Next, go to www.ruby-lang.org to download the latest stable (currently 1.9.x) version of Ruby.

Unpack it, and then from the Unix command line, run (note that the <install-dir> should be replaced with the location you'd like your version of Ruby installed):

% ./configure --prefix=<install-dir> && make && make install

This should locate the copy of ActiveTcl that you installed. To verify that everything worked, start up your newly compiled copy of 'irb', and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk; typically if there was a problem with compiling it would show up here. The second line will return the version of Tk that you're running, which should be something like "8.5.10".

Verified install using ActiveTcl 8.5.10.1, Ruby 1.9.3-p0 on Ubuntu 11.04.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl.

Run the installer and everything will be loaded onto your machine, in e.g. /opt/ActivePerl-5.12.

To find out what version of Tk Perl and Tkx are using, run this from the command line:

% perl -MTkx -e 'print Tkx::info("patchlevel");'

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.Verified install using ActivePerl 5.12.4 on Ubuntu 11.04.

Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions. It is important that you use a version of Python supporting Tk 8.5 or greater, and ttk. We recommend installing the "ActivePython" distribution from ActiveState, which includes everything you'll need.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePython for Linux. Make sure you're downloading a 3.1 or newer version.

Unpack it, run the installer (./install.sh), and follow along. You'll end up with a fresh install of ActivePython, located in e.g. /opt/ActivePython-3.2. From a Terminal window you should then be able to run a Python shell via:

% /opt/ActivePython-3.2/bin/python3.2

This should give you the Python command prompt. From the prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.5"; make sure it is not 8.4!

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.5.9'.

Verified install using ActivePython 3.2.1.2 on Ubuntu 11.04

 

The Obligatory First Program

To make sure that everything actually did work, let's try to run a "Hello World" program in Tk. While for something this short you could just type it in directly to the interpreter, instead use your favorite text editor to put it in a file.

package require Tk
grid [ttk::button .b -text "Hello World"] 

Save this to a file named 'hello.tcl'. From the wish shell, type:

% source hello.tcl

Couldn't find hello.tcl? You might be looking in the wrong directory. You can either give the full path to hello.tcl, or use Tcl's "pwd" and "cd" commands to see what directory you're in, and change to a different one.

require 'tk'
require 'tkextlib/tile'
root = TkRoot.new() 
button = Tk::Tile::TButton.new(root) {text "Hello World"}.grid
Tk.mainloop()

Save this to a file named 'hello.rb'. Start up 'irb', and from the command prompt, type:

% source "hello.rb"

Couldn't find hello.rb? You might be looking in the wrong directory. You can either give the full path to hello.rb, or use Ruby's "Dir.pwd" and "Dir.chdir" commands to see what directory you're in, and change to a different one.

use Tkx;
Tkx::grid( Tkx::ttk__button(".b", -text => "Hello, world" ) );
Tkx::MainLoop();

Note that there are two underscores between "ttk" and "button".

Save this to a file named 'hello.pl'. From a command prompt, type:

% perl hello.pl

Couldn't find hello.pl? You might be looking in the wrong directory. Try providing the full path to hello.pl.

Not working? Are you sure you're using an 8.5.x version of Tcl/Tk? See the install chapter...

from tkinter import *
from tkinter import ttk
root = Tk()
ttk.Button(root, text="Hello World").grid()
root.mainloop()

Save this to a file named 'hello.py'. From a command prompt, type:

% python hello.py

Couldn't find hello.py? You might be looking in the wrong directory. Try providing the full path to hello.py.


Our First Program. Some work left to do before the IPO.