diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 381 |
1 files changed, 381 insertions, 0 deletions
@@ -0,0 +1,381 @@ +The Tk Toolkit + +SCCS: @(#) README 1.47 97/11/20 12:48:16 + +1. Introduction +--------------- + +This directory and its descendants contain the sources and documentation +for Tk, an X11 toolkit implemented with the Tcl scripting language. The +information here corresponds to Tk 8.0p2, which is the second patch update +for Tk 8.0. This release is designed to work with Tcl 8.0p2 and may not +work with any other version of Tcl. + +Tk 8.0 is a major release with significant new features such as native +look and feel on Macintoshes and PCs, a new font mechanism, application +embedding, and proper support for Safe-Tcl. See below for details. +There should be no backward incompatibilities in Tk 8.0 that affect +scripts. This patch release fixes various bugs in Tk 8.0; there are no +feature changes relative to Tk 8.0. + +Note: with Tk 8.0 the Tk version number skipped from 4.2 to 8.0. The +jump was made in order to synchronize the Tcl and Tk version numbers. + +2. Documentation +---------------- + +The best way to get started with Tk is to read one of the introductory +books on Tcl and Tk: + + Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch, + Prentice-Hall, 1997, ISBN 0-13-616830-2 + + Tcl and the Tk Toolkit, by John Ousterhout, + Addison-Wesley, 1994, ISBN 0-201-63337-X + + Exploring Expect, by Don Libes, + O'Reilly and Associates, 1995, ISBN 1-56592-090-2 + +The "doc" subdirectory in this release contains a complete set of +reference 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 + +If you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may +find the Postscript file doc/tk4.0.ps useful. It is a porting guide +that summarizes the new features and discusses how to deal with the +changes in Tk 4.0 that are not backwards compatible. + +There is also an official home for Tcl and Tk on the Web: + http://www.smli.com/research/tcl +These Web pages include release updates, reports on bug fixes and porting +issues, HTML versions of the manual pages, and pointers to many other +Tcl/Tk Web pages at other sites. Check them out! + +3. Compiling and installing Tk +------------------------------ + +This release contains everything you should need to compile and run +Tk under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95, +or Win 3.1 with Win32s). + +Before trying to compile Tk you should do the following things: + + (a) Check for a binary release. Pre-compiled binary releases are + available now for PCs and Macintoshes, and several flavors of + UNIX. Binary releases are much easier to install than source + releases. To find out whether a binary release is available for + your platform, check the home page for the Sun Tcl/Tk project + (http://www.sunlabs.com/research/tcl) and also check in the FTP + directory from which you retrieved the base distribution. + + (b) Make sure you have the most recent patch release. Look in the + FTP directory from which you retrieved this distribution to see + if it has been updated with patches. Patch releases fix bugs + without changing any features, so you should normally use the + latest patch release for the version of Tk that you want. + Patch releases are available in two forms. A file like + tk8.0p1.tar.Z is a complete release for patch level 1 of Tk + version 8.0. If there is a file with a higher patch level than + this release, just fetch the file with the highest patch level + and use it. + + Patches are also available in the form of patch files that just + contain the changes from one patch level to another. These + files have names like tk8.0p1.patch, tk8.0p2.patch, etc. They + may also have .gz or .Z extensions to indicate compression. To + use one of these files, you apply it to an existing release with + the "patch" program. Patches must be applied in order: + tk8.0p1.patch must be applied to an unpatched Tk 8.0 release + to produce a Tk 8.0p1 release; tk8.0p2.patch can then be + applied to Tk 8.0p1 to produce Tk 8.0p2, and so on. To apply an + uncompressed patch file such as tk8.0p1.patch, invoke a shell + command like the following from the directory containing this + file: + patch -p < tk8.0p1.patch + If the patch file has a .gz extension, it was compressed with + gzip. To apply it, invoke a command like the following: + gunzip -c tk8.0p1.patch.gz | patch -p + If the patch file has a .Z extension, it was compressed with + compress. To apply it, invoke a command like the following: + zcat tk8.0p1.patch.Z | patch -p + If you're applying a patch to a release that has already been + compiled, then before applying the patch you should cd to the + "unix" subdirectory and type "make distclean" to restore the + directory to a pristine state. + +Once you've done this, change to the "unix" subdirectory if you're +compiling under UNIX, "win" if you're compiling under Windows, or +"mac" if you're compiling on a Macintosh. Then follow the instructions +in the README file in that directory for compiling Tk, installing it, +and running the test suite. + +4. Getting started +------------------ + +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 8.0 +------------------------------- + +Here is a list of the most important new features in Tk 8.0. The +release also includes several smaller feature changes and bug fixes. +See the "changes" file for a complete list of all changes. + + 1. Native look and feel. The widgets have been rewritten to provide + (nearly?) native look and feel on the Macintosh and PC. Many + widgets, including scrollbars, menus, and the button family, are + implemented with native platform widgets. Others, such as entries + and texts, have been modified to emulate native look and feel. + These changes are backwards compatible except that (a) some + configuration options are now ignored on some platforms and (b) you + must use the new menu mechanism described below to native look and + feel for menus. + + 2. There is a new interface for creating menus, where a menubar is + implemented as a menu widget instead of a frame containing menubuttons. + The -menu option for a toplevel is used to specify the name of the + menubar; the menu will be displayed *outside* the toplevel using + different mechanisms on each platform (e.g. on the Macintosh the menu + will appear at the top of the screen). See the menu demos in the + widget demo for examples. The old style of menu still works, but + does not provide native look and feel. Menus have several new + features: + - New "-columnbreak" and "-hideMargin" options make it possible + to create multi-column menus. + - It is now possible to manipulate the Apple and Help menus on + the Macintosh, and the system menu on Windows. It is also + possible to have a right justified Help menu on Unix. + - Menus now issue the virtual event <<MenuSelect>> whenever the + current item changes. Applications can use this to generate + help messages. + - There is a new "-direction" option for menubuttons, which + controls where the menu pops up revenues to the button. + + 3. The font mechanism in Tk has been completely reworked: + - Font names need not be nasty X LFDs: more intuitive names + like {Times 12 Bold} can also be used. See the manual entry + font.n for details. + - Font requests always succeed now. If the requested font is + not available, Tk finds the closest available font and uses + that one. + - Tk now supports named fonts whose precise attributes can be + changed dynamically. If a named font is changed, any widget + using that font updates itself to reflect the change. + - There is a new command "font" for creating named fonts and + querying various information about fonts. + - There are now officially supported C APIs for measuring and + displaying text. If you use these APIs now, your code will + automatically handle international text when internationalization + is added to Tk in a future release. See the manual entries + MeasureChar.3, TextLayout.3, and FontId.3. + - The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct, + and Tk_FreeFontStruct have been replaced with more portable + procedures Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont. + + 4. Application embedding. It is now possible to embedded one Tcl/Tk + application inside another, using the -container option on frame + widgets and the -use option for toplevel widgets or on the command + line for wish. Embedding should be fully functional under Unix, + but the implementation is incomplete on the Macintosh and PC. + + 5. Tk now works correctly with Safe-Tcl: it can be loaded into + safe interpreters using safe::loadTk. + + 6. Text widgets now allow images to be embedded directly in the + text without using embedded windows. This is more efficient and + provides smoother scrolling. + + 7. Buttons have a new -default option for drawing default rings in + a platform-specific manner. + + 8. There is a new "gray75" bitmap, and the "gray25" bitmap is now + really 25% on (due to an ancient mistake, it had been only 12% on). + The Macintosh now supports native bitmaps, including new builtin + bitmaps "stop", "caution", and "note", plus the ability to use + bitmaps in the application's resource fork. + + 9. The "destroy" command now ignores windows that don't exist + instead of generating an error. + +Tk 8.0 introduces the following incompatibilities that may affect Tcl/Tk +scripts that worked under Tk 4.2 and earlier releases: + + 1. Font specifications such as "Times 12" now interpret the size + as points, whereas it used to be pixels (this was actually a bug, + since the behavior was documented as points). To get pixels now, + use a negative size such as "Times -12". + + 2. The -transient option for menus is no longer supported. You can + achieve the same effect with the -type field. + + 3. In the canvas "coords" command, polygons now return only the + points that were explicitly specified when the polygon was created + (they used to return an extra point if the polygon wasn't originally + closed). Internally, polygons are still closed automatically for + purposes of display and hit detection; the extra point just isn't + returned by the "coords" command. + + 4. The photo image mechanism now uses Tcl_Channels instead of FILEs, + in order to make it portable. FILEs are no longer used anywhere + in Tk. The procedure Tk_FindPhoto now requires an extra "interp" + argument in order to fix a bug where images in different interpreters + with the same name could get confused. + + 5. The procedures Tk_GetFontStruct, Tk_NameOfFontStruct, + and Tk_FreeFontStruct have been removed. + +Note: the new compiler in Tcl 8.0 may also affect Tcl/Tk scripts; check +the Tcl documentation for information on incompatibilities introduced by +Tcl 8.0. + +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. Mailing lists +---------------- + +A couple of Mailing List have been set up to discuss Macintosh or +Windows related Tcl issues. In order to use these Mailing Lists you +must have access to the internet. If you have access to the WWW the +home pages for these mailing lists are located at the following URLs: + + http://www.sunlabs.com/research/tcl/lists/mactcl-list.html + + -and- + + http://www.sunlabs.com/research/tcl/lists/wintcl-list.html + +The home pages contain information about the lists and an HTML archive +of all the past messages on the list. To subscribe send a message to: + + listserv@sunlabs.sun.com + +In the body of the message (the subject will be ignored) put: + + subscribe mactcl Joe Blow + +Replacing Joe Blow with your real name, of course. (Use wintcl +instead of mactcl if your interested in the Windows list.) If you +would just like to receive more information about the list without +subscribing but the line: + + information mactcl + +in the body instead (or wintcl). + +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 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. + +9. 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). + +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. + +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. |