README revision 3f54fd611f536639ec30dd53c48e5ec1897cc7d9
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceThe Tk Toolkit
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceSCCS: @(#) README 1.37 97/01/29 13:24:34
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce1. Introduction
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce---------------
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceThis directory and its descendants contain the sources and documentation
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcefor Tk, an X11 toolkit implemented with the Tcl scripting language. The
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceinformation here corresponds to Tk 4.2, patch level 2 for Tk 4.2. This
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceis actually the first official patch release for Tk 4.2: patch level 1
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcewas only released for the Macintosh. Tk 4.2 is designed to work with
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceTcl 7.6 and may not work with any other version of Tcl.
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceTk 4.2 is a minor release. The main changes are a revision of the
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcegridder, a new set of standard dialog boxes, and a new virtual event
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcemechanism. See below for details. There should be no backward
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceincompatibilities in Tk 4.2 except for two small changes related to the
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcegridder.
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce2. Documentation
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce----------------
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceThe best way to get started with Tk is to read one of the introductory
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcebooks on Tcl and Tk:
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce Tcl and the Tk Toolkit, by John Ousterhout,
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce Addison-Wesley, 1994, ISBN 0-201-63337-X
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce Practical Programming in Tcl and Tk, by Brent Welch,
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce Prentice-Hall, 1995, ISBN 0-13-182007-9
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce Exploring Expect, by Don Libes,
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce O'Reilly and Associates, 1995, ISBN 1-56592-090-2
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceThe "doc" subdirectory in this release contains a complete set of
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcereference manual entries for Tk. Files with extension ".1" are for
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceprograms such as wish; files with extension ".3" are for C library
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceprocedures; and files with extension ".n" describe Tcl commands. To
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceprint any of the manual entries, cd to the "doc" directory and invoke
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceyour favorite variant of troff using the normal -man macros, for example
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce ditroff -man wish.1
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceto print wish.1. If Tk has been installed correctly and your "man"
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceprogram supports it, you should be able to access the Tcl manual entries
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceusing the normal "man" mechanisms, such as
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce man wish
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceIf you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may
ab967283b710dfa05d11ee5b30c7ac916486ceecSimo Sorcefind the Postscript file doc/tk4.0.ps useful. It is a porting guide
c6872e79e8496fd075e20aec0343ade99cca725cSimo Sorcethat summarizes the new features and discusses how to deal with the
c6872e79e8496fd075e20aec0343ade99cca725cSimo Sorcechanges in Tk 4.0 that are not backwards compatible.
c6872e79e8496fd075e20aec0343ade99cca725cSimo Sorce
7c69221077c780e62f6c536e78675f2dc1c131bcMichal ZidekThere is also an official home for Tcl and Tk on the Web:
22a21e910fd216ec1468fe769dcc29f1621a52a4Ondrej Kos http://www.smli.com/research/tcl
ab967283b710dfa05d11ee5b30c7ac916486ceecSimo SorceThese Web pages include release updates, reports on bug fixes and porting
ab967283b710dfa05d11ee5b30c7ac916486ceecSimo Sorceissues, HTML versions of the manual pages, and pointers to many other
ab967283b710dfa05d11ee5b30c7ac916486ceecSimo SorceTcl/Tk Web pages at other sites. Check them out!
ab967283b710dfa05d11ee5b30c7ac916486ceecSimo Sorce
233a3c6c48972b177e60d6ef4cecfacd3cf31659Simo Sorce3. Compiling and installing Tk
c6872e79e8496fd075e20aec0343ade99cca725cSimo Sorce------------------------------
c6872e79e8496fd075e20aec0343ade99cca725cSimo Sorce
233a3c6c48972b177e60d6ef4cecfacd3cf31659Simo SorceThis release contains everything you should need to compile and run
233a3c6c48972b177e60d6ef4cecfacd3cf31659Simo SorceTk under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
c9b0071bfcb8eb8c71e40248de46d23aceecc0f3Pavel Reichlor Win 3.1 with Win32s).
c9b0071bfcb8eb8c71e40248de46d23aceecc0f3Pavel Reichl
c9b0071bfcb8eb8c71e40248de46d23aceecc0f3Pavel ReichlBefore trying to compile Tk you should do the following things:
dfd71fc92db940b2892cc996911cec03d7b6c52bSimo Sorce
f9961e5f82e0ef474d6492371bfdf9e74e208a99Pavel Březina (a) Check for a binary release. Pre-compiled binary releases are
f9961e5f82e0ef474d6492371bfdf9e74e208a99Pavel Březina available now for PCs and Macintoshes, and several flavors of
e5f455afbc2d149527bfd08f4e89903a3a8da17aPavel Březina UNIX. Binary releases are much easier to install than source
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek releases. To find out whether a binary release is available for
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek your platform, check the home page for the Sun Tcl/Tk project
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek (http://www.sunlabs.com/research/tcl) and also check in the FTP
7caf7ed4f2eae1ec1c0717b4ee6ce78bdacd5926Jakub Hrozek directory from which you retrieved the base distribution.
dcc6877aa2e2dd63a9dc9c411a9c58feaeb36b9aStephen Gallagher
bc30ce9b7d588a17e58012e699986f0d6898b791Pavel Březina (b) Make sure you have the most recent patch release. Look in the
b5ee224324b0158641d9b110f81d2bc6eddddc13Pavel Reichl FTP directory from which you retrieved this distribution to see
2a96981a0ac781d01e5bba473409ed2bdf4cd4e0Jakub Hrozek if it has been updated with patches. Patch releases fix bugs
e81deec535d11912b87954c81a1edd768c1386c9Jakub Hrozek without changing any features, so you should normally use the
4dd38025efda88f123eac672f87d3cda12f050c8Jakub Hrozek latest patch release for the version of Tk that you want.
4dd38025efda88f123eac672f87d3cda12f050c8Jakub Hrozek Patch releases are available in two forms. A file like
0161a3c5637a0c0092bf54c436bb3d6508d7df26Jakub Hrozek tk4.2p2.tar.Z is a complete release for patch level 2 of Tk
0161a3c5637a0c0092bf54c436bb3d6508d7df26Jakub Hrozek version 4.2. If there is a file with a higher patch level than
10a28f461c25d788ff4dcffefa881e7aa724a25dPavel Březina this release, just fetch the file with the highest patch level
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley and use it.
1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4Stef Walter
0c1d65998907930678da2d091789446f2c344d5dJakub Hrozek Patches are also available in the form of patch files that just
a2ea3f5d9ef9f17efbb61e942c2bc6cff7d1ebf2Jakub Hrozek contain the changes from one patch level to another. These
f3a25949de81f80c136bb073e4a8f504b080c20cJakub Hrozek files have names like tk4.2p2.patch, tk4.2p3.patch, etc. They
8394eddba54b5d3e3fda868145e3751247bdbdb2Michal Zidek may also have .gz or .Z extensions to indicate compression. To
5a5c5cdeb92f4012fc75fd717bfea06598f68f12Pavel Reichl use one of these files, you apply it to an existing release with
804df4040eb142f82a44c019c7a55b5ce524583cMichal Zidek the "patch" program. Patches must be applied in order,
1243e093fd31c5660adf1bb3dd477d6935a755beJakub Hrozek except that there is no patch level 1 for Tcl 7.6:
1243e093fd31c5660adf1bb3dd477d6935a755beJakub Hrozek tk4.2p2.patch must be applied to an unpatched Tk 4.2 release
82a958e6592c4a4078e45b7197bbe4751b70f511Pavel Reichl to produce a Tk 4.2p2 release; tk4.2p3.patch can then be
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce applied to Tk 4.2p2 to produce Tk 4.2p3, and so on. To apply an
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce uncompressed patch file such as tk4.2p2.patch, invoke a shell
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce command like the following from the directory containing this
0c16d2eefbc6ac8331078a4cdcecfee817a71bc6Simo Sorce file:
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce patch -p < tk4.2p2.patch
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce If the patch file has a .gz extension, it was compressed with
7650ded4ffa87fcf7ce5adf00920fecf89cffcf5Michal Zidek gzip. To apply it, invoke a command like the following:
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce gunzip -c tk4.2p2.patch.gz | patch -p
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce If the patch file has a .Z extension, it was compressed with
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce compress. To apply it, invoke a command like the following:
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce zcat tk4.2p2.patch.Z | patch -p
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce If you're applying a patch to a release that has already been
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce compiled, then before applying the patch you should cd to the
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce "unix" subdirectory and type "make distclean" to restore the
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce directory to a pristine state.
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo SorceOnce you've done this, change to the "unix" subdirectory if you're
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcecompiling under UNIX, "win" if you're compiling under Windows, or
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce"mac" if you're compiling on a Macintosh. Then follow the instructions
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorcein the README file in that directory for compiling Tk, installing it,
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorceand running the test suite.
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce4. Getting started
8bcabb97d988d1602882a1f036aac2eaf5e09234Simo Sorce------------------
The best way to get started with Tk is by reading one of the introductory
books.
The subdirectory library/demos contains a number of pre-canned scripts
that demonstrate various features of Tk. 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, see the code that produced the demos,
and modify the code to try out alternatives.
5. Summary of changes in Tk 4.2
-------------------------------
Here are the new features in Tk 4.2. The release also includes several
bug fixes. See the "changes" file for a complete list of all changes.
1. The grid geometry manager has been completely rewritten:
- The layout algorithm produces much better layouts than before,
particularly where rows or columns were stretchable.
- There is a new -pad option for rows and columns.
- The command "grid forget" has been renamed "grid remove",
and "grid forget" now has semantics like "pack forget".
- The "grid" command no longer accepts floating-point values
for row or column weights: integers must be used.
2. There are new commands for creating common dialog boxes:
tk_chooseColor, tk_getOpenFile, tk_getSaveFile and tk_messageBox.
These use native dialog boxes if they are available. Examples of
the dialogs are available in the widget demo.
3. There is a new virtual event mechanism for handling events in a
more portable way. See the new command "event". It also allows
events (both physical and virtual) to be generated dynamically.
The Macintosh now generates <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>>
events from the edit menu.
The only incompatible changes in this release are the last two for the
gridder ("grid forget" and integer row/column weights). Most scripts
that ran under Tk 4.1 should also work under Tk 4.2 with no changes.
6. 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.
We read the newsgroup and will attempt to fix bugs and problems reported
to it.
When using comp.lang.tcl, please be sure that your e-mail return address
is correctly set in your postings. This allows people to respond directly
to you, rather than the entire newsgroup, for answers that are not of
general interest. A bad e-mail return address may prevent you from
getting answers to your questions. You may have to reconfigure your news
reading software to ensure that it is supplying valid e-mail addresses.
7. 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 ftp.neosoft.com. You
can access the archive using anonymous FTP; the Tcl contributed archive is
in the directory "/pub/tcl". The archive also contains several FAQ
("frequently asked questions") documents that provide solutions to problems
that are commonly encountered by TCL newcomers.
8. Support and bug fixes
------------------------
We're very interested in receiving bug reports and suggestions for
improvements. We prefer that you send this information to the
comp.lang.tcl newsgroup rather than to any of us at Sun. We'll see
anything on comp.lang.tcl, and in addition someone else who reads
comp.lang.tcl may be able to offer a solution. The normal turn-around
time for bugs is 3-6 weeks. Enhancements may take longer and may not
happen at all unless there is widespread support for them (we're
trying to slow the rate at which Tk turns into a kitchen sink). It's
very difficult to make incompatible changes to Tcl at this point, due
to the size of the installed base.
When reporting bugs, please provide a short wish script that we can
use to reproduce the bug. Make sure that the script runs with a
bare-bones wish and doesn't depend on any extensions or other
programs, particularly those that exist only at your site. Also,
please include three additional pieces of information with the
script:
(a) how do we use the script to make the problem happen (e.g.
what things do we click on, in what order)?
(b) what happens when you do these things (presumably this is
undesirable)?
(c) what did you expect to happen instead?
The Tcl/Tk community is too large for us to provide much individual
support for users. If you need help we suggest that you post questions
to comp.lang.tcl. We 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 (info@neosoft.com), Computerized Processes Unlimited
(gwl@cpu.com), and Data Kinetics (education@dkl.com).
9. 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.
Alpha and beta releases have an additional suffix of the form a2 or b1.
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. An alpha release is like a beta
release, except it's likely to need even more work before it's "ready
for prime time". New releases are normally preceded by one or more
alpha and beta releases. We hope that lots of people will try out
the alpha and beta releases and report problems. We'll make new alpha/
beta releases to fix the problems, until eventually there is a beta
release that appears to be stable. Once this occurs we'll make the
final release.
We can't promise to maintain compatibility among alpha and beta releases.
For example, release 4.1b2 may not be backward compatible with 4.1b1, even
though the final 4.1 release will be backward compatible with 4.0. This
allows us to change new features as we find problems during beta testing.
We'll try to minimize incompatibilities between beta releases, but if a
major problem turns up then we'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.
Patch releases have a suffix such as p1 or p2. These releases contain
bug fixes only. A patch release (e.g Tk 4.1p2) should be completely
compatible with the base release from which it is derived (e.g. Tk
4.1), and you should normally use the highest available patch release.