8 This directory and its descendants contain the sources and documentation
9 for Tk, an X11 toolkit implemented with the Tcl scripting language. The
10 information here corresponds to Tk 8.0.3, which is the third patch update
11 for Tk 8.0. This release is designed to work with Tcl 8.0.3 and may not
12 work with any other version of Tcl.
14 Tk 8.0 is a major release with significant new features such as native
15 look and feel on Macintoshes and PCs, a new font mechanism, application
16 embedding, and proper support for Safe-Tcl. See below for details.
17 There should be no backward incompatibilities in Tk 8.0 that affect
18 scripts. This patch release fixes various bugs in Tk 8.0; there are no
19 feature changes relative to Tk 8.0.
21 Note: with Tk 8.0 the Tk version number skipped from 4.2 to 8.0. The
22 jump was made in order to synchronize the Tcl and Tk version numbers.
27 The best way to get started with Tk is to read one of the introductory
30 Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
31 Prentice-Hall, 1997, ISBN 0-13-616830-2
33 Tcl and the Tk Toolkit, by John Ousterhout,
34 Addison-Wesley, 1994, ISBN 0-201-63337-X
36 Exploring Expect, by Don Libes,
37 O'Reilly and Associates, 1995, ISBN 1-56592-090-2
39 Other books are listed at
40 http://www.scriptics.com/resource/doc/books/
41 http://www.tclconsortium.org/resources/books.html
43 The "doc" subdirectory in this release contains a complete set of
44 reference manual entries for Tk. Files with extension ".1" are for
45 programs such as wish; files with extension ".3" are for C library
46 procedures; and files with extension ".n" describe Tcl commands. To
47 print any of the manual entries, cd to the "doc" directory and invoke
48 your favorite variant of troff using the normal -man macros, for example
52 to print wish.1. If Tk has been installed correctly and your "man"
53 program supports it, you should be able to access the Tcl manual entries
54 using the normal "man" mechanisms, such as
58 If you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may
59 find the Postscript file doc/tk4.0.ps useful. It is a porting guide
60 that summarizes the new features and discusses how to deal with the
61 changes in Tk 4.0 that are not backwards compatible.
63 There is also an official home for Tcl and Tk on the Web:
64 http://www.scriptics.com/
65 These Web pages include release updates, reports on bug fixes and porting
66 issues, HTML versions of the manual pages, and pointers to many other
67 Tcl/Tk Web pages at other sites. Check them out!
69 3. Compiling and installing Tk
70 ------------------------------
72 This release contains everything you should need to compile and run
73 Tk under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
76 Before trying to compile Tk you should do the following things:
78 (a) Check for a binary release. Pre-compiled binary releases are
79 available now for PCs and Macintoshes, and several flavors of
80 UNIX. Binary releases are much easier to install than source
81 releases. To find out whether a binary release is available for
82 your platform, check the home page for Tcl/Tk
83 (http://www.scriptics.com/) and also check in the FTP
84 directory from which you retrieved the base distribution.
86 (b) Make sure you have the most recent patch release. Look in the
87 FTP directory from which you retrieved this distribution to see
88 if it has been updated with patches. Patch releases fix bugs
89 without changing any features, so you should normally use the
90 latest patch release for the version of Tk that you want.
91 Patch releases are available in two forms. A file like
92 tk8.0p1.tar.Z is a complete release for patch level 1 of Tk
93 version 8.0. If there is a file with a higher patch level than
94 this release, just fetch the file with the highest patch level
97 Patches are also available in the form of patch files that just
98 contain the changes from one patch level to another. These
99 files have names like tk8.0p1.patch, tk8.0p2.patch, etc. They
100 may also have .gz or .Z extensions to indicate compression. To
101 use one of these files, you apply it to an existing release with
102 the "patch" program. Patches must be applied in order:
103 tk8.0p1.patch must be applied to an unpatched Tk 8.0 release
104 to produce a Tk 8.0p1 release; tk8.0p2.patch can then be
105 applied to Tk 8.0p1 to produce Tk 8.0p2, and so on. To apply an
106 uncompressed patch file such as tk8.0p1.patch, invoke a shell
107 command like the following from the directory containing this
108 file (you may need to replace "patch -p" with "patch -p0"
109 depending on your version of the patch program):
110 patch -p < tk8.0p1.patch
111 If the patch file has a .gz extension, it was compressed with
112 gzip. To apply it, invoke a command like the following:
113 gunzip -c tk8.0p1.patch.gz | patch -p
114 If the patch file has a .Z extension, it was compressed with
115 compress. To apply it, invoke a command like the following:
116 zcat tk8.0p1.patch.Z | patch -p
117 If you're applying a patch to a release that has already been
118 compiled, then before applying the patch you should cd to the
119 "unix" subdirectory and type "make distclean" to restore the
120 directory to a pristine state.
122 Once you've done this, change to the "unix" subdirectory if you're
123 compiling under UNIX, "win" if you're compiling under Windows, or
124 "mac" if you're compiling on a Macintosh. Then follow the instructions
125 in the README file in that directory for compiling Tk, installing it,
126 and running the test suite.
131 The best way to get started with Tk is by reading one of the introductory
134 The subdirectory library/demos contains a number of pre-canned scripts
135 that demonstrate various features of Tk. See the README file in the
136 directory for a description of what's available. The file
137 library/demos/widget is a script that you can use to invoke many individual
138 demonstrations of Tk's facilities, see the code that produced the demos,
139 and modify the code to try out alternatives.
141 5. Summary of changes in Tk 8.0
142 -------------------------------
144 Here is a list of the most important new features in Tk 8.0. The
145 release also includes several smaller feature changes and bug fixes.
146 See the "changes" file for a complete list of all changes.
148 1. Native look and feel. The widgets have been rewritten to provide
149 (nearly?) native look and feel on the Macintosh and PC. Many
150 widgets, including scrollbars, menus, and the button family, are
151 implemented with native platform widgets. Others, such as entries
152 and texts, have been modified to emulate native look and feel.
153 These changes are backwards compatible except that (a) some
154 configuration options are now ignored on some platforms and (b) you
155 must use the new menu mechanism described below to native look and
158 2. There is a new interface for creating menus, where a menubar is
159 implemented as a menu widget instead of a frame containing menubuttons.
160 The -menu option for a toplevel is used to specify the name of the
161 menubar; the menu will be displayed *outside* the toplevel using
162 different mechanisms on each platform (e.g. on the Macintosh the menu
163 will appear at the top of the screen). See the menu demos in the
164 widget demo for examples. The old style of menu still works, but
165 does not provide native look and feel. Menus have several new
167 - New "-columnbreak" and "-hideMargin" options make it possible
168 to create multi-column menus.
169 - It is now possible to manipulate the Apple and Help menus on
170 the Macintosh, and the system menu on Windows. It is also
171 possible to have a right justified Help menu on Unix.
172 - Menus now issue the virtual event <<MenuSelect>> whenever the
173 current item changes. Applications can use this to generate
175 - There is a new "-direction" option for menubuttons, which
176 controls where the menu pops up revenues to the button.
178 3. The font mechanism in Tk has been completely reworked:
179 - Font names need not be nasty X LFDs: more intuitive names
180 like {Times 12 Bold} can also be used. See the manual entry
182 - Font requests always succeed now. If the requested font is
183 not available, Tk finds the closest available font and uses
185 - Tk now supports named fonts whose precise attributes can be
186 changed dynamically. If a named font is changed, any widget
187 using that font updates itself to reflect the change.
188 - There is a new command "font" for creating named fonts and
189 querying various information about fonts.
190 - There are now officially supported C APIs for measuring and
191 displaying text. If you use these APIs now, your code will
192 automatically handle international text when internationalization
193 is added to Tk in a future release. See the manual entries
194 MeasureChar.3, TextLayout.3, and FontId.3.
195 - The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
196 and Tk_FreeFontStruct have been replaced with more portable
197 procedures Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont.
199 4. Application embedding. It is now possible to embedded one Tcl/Tk
200 application inside another, using the -container option on frame
201 widgets and the -use option for toplevel widgets or on the command
202 line for wish. Embedding should be fully functional under Unix,
203 but the implementation is incomplete on the Macintosh and PC.
205 5. Tk now works correctly with Safe-Tcl: it can be loaded into
206 safe interpreters using safe::loadTk.
208 6. Text widgets now allow images to be embedded directly in the
209 text without using embedded windows. This is more efficient and
210 provides smoother scrolling.
212 7. Buttons have a new -default option for drawing default rings in
213 a platform-specific manner.
215 8. There is a new "gray75" bitmap, and the "gray25" bitmap is now
216 really 25% on (due to an ancient mistake, it had been only 12% on).
217 The Macintosh now supports native bitmaps, including new builtin
218 bitmaps "stop", "caution", and "note", plus the ability to use
219 bitmaps in the application's resource fork.
221 9. The "destroy" command now ignores windows that don't exist
222 instead of generating an error.
224 Tk 8.0 introduces the following incompatibilities that may affect Tcl/Tk
225 scripts that worked under Tk 4.2 and earlier releases:
227 1. Font specifications such as "Times 12" now interpret the size
228 as points, whereas it used to be pixels (this was actually a bug,
229 since the behavior was documented as points). To get pixels now,
230 use a negative size such as "Times -12".
232 2. The -transient option for menus is no longer supported. You can
233 achieve the same effect with the -type field.
235 3. In the canvas "coords" command, polygons now return only the
236 points that were explicitly specified when the polygon was created
237 (they used to return an extra point if the polygon wasn't originally
238 closed). Internally, polygons are still closed automatically for
239 purposes of display and hit detection; the extra point just isn't
240 returned by the "coords" command.
242 4. The photo image mechanism now uses Tcl_Channels instead of FILEs,
243 in order to make it portable. FILEs are no longer used anywhere
244 in Tk. The procedure Tk_FindPhoto now requires an extra "interp"
245 argument in order to fix a bug where images in different interpreters
246 with the same name could get confused.
248 5. The procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
249 and Tk_FreeFontStruct have been removed.
251 Note: the new compiler in Tcl 8.0 may also affect Tcl/Tk scripts; check
252 the Tcl documentation for information on incompatibilities introduced by
258 There is a network news group "comp.lang.tcl" intended for the exchange
259 of information about Tcl, Tk, and related applications. Feel free to use
260 this newsgroup both for general information questions and for bug reports.
261 We read the newsgroup and will attempt to fix bugs and problems reported
264 When using comp.lang.tcl, please be sure that your e-mail return address
265 is correctly set in your postings. This allows people to respond directly
266 to you, rather than the entire newsgroup, for answers that are not of
267 general interest. A bad e-mail return address may prevent you from
268 getting answers to your questions. You may have to reconfigure your news
269 reading software to ensure that it is supplying valid e-mail addresses.
274 A couple of Mailing List have been set up to discuss Macintosh or
275 Windows related Tcl issues. In order to use these Mailing Lists you
276 must have access to the internet. To subscribe send a message to:
278 wintcl-request@tclconsorium.org
280 mactcl-request@tclconsorium.org
282 In the body of the message (the subject will be ignored) put:
284 subscribe mactcl Joe Blow
286 Replacing Joe Blow with your real name, of course. (Use wintcl
287 instead of mactcl if your interested in the Windows list.) If you
288 would just like to receive more information about the list without
289 subscribing but the line:
293 in the body instead (or wintcl).
295 8. Tcl/Tk contributed archive
296 --------------------------
298 Many people have created exciting packages and applications based on Tcl
299 and/or Tk and made them freely available to the Tcl community. An archive
300 of these contributions is kept on the machine ftp.neosoft.com. You
301 can access the archive using anonymous FTP; the Tcl contributed archive is
302 in the directory "/pub/tcl". The archive also contains several FAQ
303 ("frequently asked questions") documents that provide solutions to problems
304 that are commonly encountered by TCL newcomers.
306 9. Tcl Resource Center
307 ----------------------
308 Visit http://www.scritics.com/resource/ to see an annotated index of
309 many Tcl resources available on the World Wide Web. This includes
310 papers, books, and FAQs, as well as extensions, applications, binary
311 releases, and patches. You can contribute patches by sending them
312 to <patches@scriptics.com>. You can also recommend more URLs for the
313 resource center using the forms labeled "Add a Resource".
315 10. Support and bug fixes
316 ------------------------
318 We're very interested in receiving bug reports and suggestions for
319 improvements. We prefer that you send this information to the
320 comp.lang.tcl newsgroup rather than to any of us at Scriptics. We'll see
321 anything on comp.lang.tcl, and in addition someone else who reads
322 comp.lang.tcl may be able to offer a solution. The normal turn-around
323 time for bugs is 3-6 weeks. Enhancements may take longer and may not
324 happen at all unless there is widespread support for them (we're
325 trying to slow the rate at which Tk turns into a kitchen sink). It's
326 very difficult to make incompatible changes to Tcl at this point, due
327 to the size of the installed base.
329 When reporting bugs, please provide a short wish script that we can
330 use to reproduce the bug. Make sure that the script runs with a
331 bare-bones wish and doesn't depend on any extensions or other
332 programs, particularly those that exist only at your site. Also,
333 please include three additional pieces of information with the
335 (a) how do we use the script to make the problem happen (e.g.
336 what things do we click on, in what order)?
337 (b) what happens when you do these things (presumably this is
339 (c) what did you expect to happen instead?
341 The Tcl/Tk community is too large for us to provide much individual
342 support for users. If you need help we suggest that you post questions
343 to comp.lang.tcl. We read the newsgroup and will attempt to answer
344 esoteric questions for which no-one else is likely to know the answer.
345 In addition, Tcl/Tk support and training are available commercially from
346 Scriptics (info@scriptics.com), NeoSoft (info@neosoft.com),
347 Computerized Processes Unlimited (gwl@cpu.com),
348 and Data Kinetics (education@dkl.com).
350 11. Release organization
351 ------------------------
353 The version numbers described below are available to Tcl scripts
354 as the tk_version and tk_patchLevel Tcl variables.
356 Each Tk release is identified by two numbers separated by a dot, e.g.
357 3.2 or 3.3. If a new release contains changes that are likely to break
358 existing C code or Tcl scripts then the major release number increments
359 and the minor number resets to zero: 3.0, 4.0, etc. If a new release
360 contains only bug fixes and compatible changes, then the minor number
361 increments without changing the major number, e.g. 3.1, 3.2, etc. If
362 you have C code or Tcl scripts that work with release X.Y, then they
363 should also work with any release X.Z as long as Z > Y.
365 Alpha and beta releases have an additional suffix of the form a2 or b1.
366 For example, Tk 3.3b1 is the first beta release of Tk version 3.3,
367 Tk 3.3b2 is the second beta release, and so on. A beta release is an
368 initial version of a new release, used to fix bugs and bad features
369 before declaring the release stable. An alpha release is like a beta
370 release, except it's likely to need even more work before it's "ready
371 for prime time". New releases are normally preceded by one or more
372 alpha and beta releases. We hope that lots of people will try out
373 the alpha and beta releases and report problems. We'll make new alpha/
374 beta releases to fix the problems, until eventually there is a beta
375 release that appears to be stable. Once this occurs we'll make the
378 We can't promise to maintain compatibility among alpha and beta releases.
379 For example, release 4.1b2 may not be backward compatible with 4.1b1, even
380 though the final 4.1 release will be backward compatible with 4.0. This
381 allows us to change new features as we find problems during beta testing.
382 We'll try to minimize incompatibilities between beta releases, but if a
383 major problem turns up then we'll fix it even if it introduces an
384 incompatibility. Once the official release is made then there won't
385 be any more incompatibilities until the next release with a new major
388 Patch releases used to have a suffix such as p1 or p2. Now we use
389 a 3-part version number: major.minor.patchlevel. (e.g., 8.0.3)
390 These releases contain bug fixes only. A patch release (e.g Tk 4.1p2)
391 should be completely compatible with the base release from which it is
392 derived (e.g. Tk 4.1), and you should normally use the highest available