The Tk Toolkit
by John Ousterhout
University of California at Berkeley
ouster@cs.berkeley.edu
1. Introduction
---------------
This directory contains the sources and documentation for Tk, an
X11 toolkit that provides the Motif look and feel and is implemented
using the Tcl scripting language. The information here corresponds
to Tk 3.6. It is designed to work with Tcl 7.3 and may not work
with other releases of Tcl.
2. Documentation
----------------
The best way to get started with Tk is to read the draft of my upcoming
book on Tcl and Tk, which can be retrieved using anonymous FTP from the
directory "ucb/tcl" on ftp.cs.berkeley.edu. Part II of the book provides
an introduction to writing Tcl scripts for Tk and Part IV describes how
to build new widgets and geometry managers in C using Tk's library
procedures.
The "doc" subdirectory in this release contains a complete set of manual
entries for Tk. Files with extension ".1" are for programs such as
wish; files with extension ".3" are for C library procedures; and files
with extension ".n" describe Tcl commands. To print any of the manual
entries, cd to the "doc" directory and invoke your favorite variant of
troff using the normal -man macros, for example
ditroff -man wish.1
to print wish.1. If Tk has been installed correctly and your "man"
program supports it, you should be able to access the Tcl manual entries
using the normal "man" mechanisms, such as
man wish
3. Compiling and installing Tk
------------------------------
This release should compile and run with little or no effort on any
UNIX-like system that approximates POSIX, BSD, or System V and runs
the X Window System. I know that it runs on workstations from Sun,
DEC, H-P, IBM, and Silicon Graphics, and on PC's running SCO UNIX
and Xenix. To compile Tk, do the following:
(a) Make sure that this directory and the corresponding release of
Tcl are both subdirectories of the same directory. This
directory should be named tk3.6 and the Tcl release directory
should be named tcl7.3.
(b) Type "./configure" in this directory. This runs a configuration
script created by GNU autoconf, which configures Tcl for your
system and creates a Makefile. The configure script allows you
to customize the Tk configuration for your site; for details on
how you can do this, see the file "configure.info".
(c) Type "make". This will create a library archive called "libtk.a"
and an interpreter application called "wish" that allows you to type
Tcl commands interactively or execute script files.
(d) If the make fails then you'll have to personalize the Makefile
for your site or possibly modify the distribution in other ways.
First check the file "porting.notes" to see if there are hints
for compiling on your system. If you need to modify Makefile,
there are comments at the beginning of it that describe the things
you might want to change and how to change them.
(e) Type "make install" to install Tk's binaries and script files in
standard places. In the default configuration information will
be installed in /usr/local so you'll need write permission on
this directory.
(f) At this point you can play with Tcl by invoking the "wish"
program and typing Tcl commands. However, if you haven't installed
Tk then you'll first need to set your TK_LIBRARY environment
variable to hold the full path name of the "library" subdirectory.
If you haven't installed Tcl either then you'll need to set your
TCL_LIBRARY environment variable as well (see the Tcl README file
for information on this).
If you have trouble compiling Tk, I'd suggest looking at the file
"porting.notes". It contains information that people have sent me about
changes they had to make to compile Tcl in various environments. I make
no guarantees that this information is accurate, complete, or up-to-date,
but you may find it useful. If you get Tk running on a new configuration
and had to make non-trivial changes to do it, I'd be happy to receive new
information to add to "porting.notes". I'm also interested in hearing
how to change the configuration setup so that Tcl compiles on additional
platforms "out of the box".
4. Test suite
-------------
Tk now has the beginnings of a self-test suite, consisting of a set of
scripts in the subdirectory "tests". To run the test suite just type
"make test" in this directory. You should then see a printout of the
test files processed. If any errors occur, you'll see a much more
substantial printout for each error. See the README file in the
"tests" directory for more information on the test suite.
5. Getting started
------------------
Once wish is compiled you can use it to play around with the Tk
facilities. If you run wish with no arguments, it will open a small
window on the screen and read Tcl commands from standard input.
Or, you can play with some of the pre-canned scripts in the subdirectory
library/demos. See the README file in the directory for a description
of what's available. The file library/demos/widget is a script that
you can use to invoke many individual demonstrations of Tk's facilities.
If you want to start typing Tcl/Tk commands to wish, I'd suggest
starting with a widget-creation command like "button", and also learn
about the "pack" and "place" commands for geometry management. Note:
when you create a widget, it won't appear on the screen until you tell
a geometry manager about it. The only geometry managers at present
are the packer and the placer. If you don't already know Tcl, read the
Tcl book excerpt that can be FTP'ed separately from the distribution
directory.
Andrew Payne has written a very nice demo script called "The Widget Tour"
that introduces you to writing Tk scripts. This script is available
from the Tcl contributed archive described below. If you're just
getting started with Tk I strongly recommend trying out the widget tour.
6. Summary of changes in recent releases
----------------------------------------
Tk 3.6 is a minor new release that is identical to 3.4 except that it
fixes a portability bug that prevents tkMain.c from compiling on some
machines (R_OK isn't properly defined). Tk 3.6 should be completely
compatible with both 3.4 and 3.3.
Tk 3.5 was mistake, and was withdrawn shortly after it was released.
Tk 3.4 is a minor release consisting almost entirely of bug fixes. There
are no significant feature changes and Tk 3.4 should be completely
compatible with Tk 3.3.
Tk 3.3 consists mostly of bug fixes plus upgrades to make it compatible
with Tcl 7.0. It should not introduce any compatibility problems itself,
but it requires Tcl 7.0, which introduces several incompatibilities
(see the Tcl README file for details). The file "changes" contains a
complete list of all changes to Tk, including both bug fixes and new
features. Here is a short list of a few of the most significant new
features:
1. Tk is now consistent with the book drafts. This means that the
new packer syntax has been implemented and additional bitmaps and
reliefs are available.
2. Tk now supports stacking order. Windows will stack in the order
created, and "raise" and "lower" commands are available to change
the stacking order.
3. There have been several improvements in configuration: GNU
autoconf is now used for configuration; wish now supports the
Tcl_AppInit procedure; and there's a patchlevel.h file that will
be used for future patches. The Tk release no longer includes a
Tcl release; you'll have to retrieve Tcl separately.
4. The Tk script library contains a new procedure "tk_dialog" for
creating dialog boxes, and the default "tkerror" has been improved
to use tk_dialog.
5. Tk now provides its own "exit" command that cleans up properly,
so it's now safe to use "exit" instead of "destroy ." to end wish
applications.
6. Cascade menu entries now display proper Motif arrows.
7. The main window is now a legitimate toplevel widget.
8. Wish allows prompts to be user-settable via the "tcl_prompt1"
and "tcl_prompt2" variables.
7. Tcl/Tk newsgroup
-------------------
There is a network news group "comp.lang.tcl" intended for the exchange
of information about Tcl, Tk, and related applications. Feel free to use
this newsgroup both for general information questions and for bug reports.
I read the newsgroup and will attempt to fix bugs and problems reported
to it.
8. Tcl/Tk contributed archive
--------------------------
Many people have created exciting packages and applications based on Tcl
and/or Tk and made them freely available to the Tcl community. An archive
of these contributions is kept on the machine harbor.ecn.purdue.edu. You
can access the archive using anonymous FTP; the Tcl contributed archive is
in the directory "pub/tcl".
9. Support and bug fixes
------------------------
I'm very interested in receiving bug reports and suggestions for
improvements. Bugs usually get fixed quickly (particularly if they
are serious), but enhancements may take a while and may not happen at
all unless there is widespread support for them (I'm trying to slow
the rate at which Tk turns into a kitchen sink). It's becoming
increasingly difficult to make incompatible changes to Tk, but it's
not totally out of the question.
The Tcl/Tk community is too large for me to provide much individual
support for users. If you need help I suggest that you post questions
to comp.lang.tcl. I read the newsgroup and will attempt to answer
esoteric questions for which no-one else is likely to know the answer.
In addition, Tcl/Tk support and training are available commercially from
NeoSoft. For more information, send e-mail to "info@neosoft.com".
10. Release organization
---------------------------
Each Tk release is identified by two numbers separated by a dot, e.g.
3.2 or 3.3. If a new release contains changes that are likely to break
existing C code or Tcl scripts then the major release number increments
and the minor number resets to zero: 3.0, 4.0, etc. If a new release
contains only bug fixes and compatible changes, then the minor number
increments without changing the major number, e.g. 3.1, 3.2, etc. If
you have C code or Tcl scripts that work with release X.Y, then they
should also work with any release X.Z as long as Z > Y.
Beta releases have an additional suffix of the form bx. For example,
Tk 3.3b1 is the first beta release of Tk version 3.3, Tk 3.3b2 is
the second beta release, and so on. A beta release is an initial
version of a new release, used to fix bugs and bad features before
declaring the release stable. Each new release will be preceded by
one or more beta releases. I hope that lots of people will try out
the beta releases and report problems back to me. I'll make new beta
releases to fix the problems, until eventually there is a beta release
that appears to be stable. Once this occurs I'll remove the beta
suffix so that the last beta release becomes the official release.
If a new release contains incompatibilities (e.g. 4.0) then I can't
promise to maintain compatibility among its beta releases. For example,
release 4.0b2 may not be backward compatible with 4.0b1. I'll try
to minimize incompatibilities between beta releases, but if a major
problem turns up then I'll fix it even if it introduces an
incompatibility. Once the official release is made then there won't
be any more incompatibilities until the next release with a new major
version number.
