| 1 | The Tk Toolkit, Version 2.3 |
| 2 | |
| 3 | by John Ousterhout |
| 4 | University of California at Berkeley |
| 5 | |
| 6 | 1. Introduction |
| 7 | --------------- |
| 8 | |
| 9 | This directory contains the sources and documentation for Tk, which |
| 10 | is an X11 toolkit that provides the Motif look and feel and is |
| 11 | implemented using the Tcl command language. |
| 12 | |
| 13 | For an introduction to Tcl and Tk you may wish to read two papers: |
| 14 | ``Tcl: An Embeddable Command Language'', in the Proceedings of the |
| 15 | 1990 Winter USENIX Conference, and ``An X11 Toolkit Based on the Tcl |
| 16 | Language'', in the Proceedings of the 1991 Winter USENIX Conference. |
| 17 | A copy of the first paper is present in Postscript form in the file |
| 18 | "tcl/usenix.ps"; Postscript for the second paper is in "doc/usenix.ps". |
| 19 | Both Tcl and Tk have evolved quite a bit since these papers were |
| 20 | written so the papers are no longer complete or correct, but they will |
| 21 | give you an introduction to the systems. |
| 22 | |
| 23 | The following things are present in this directory and its subdirectories: |
| 24 | |
| 25 | 1. Tk, a toolkit for X11 windowing applications. |
| 26 | 2. Tcl, an embeddable command language on which Tk is based. |
| 27 | 3. Wish, a simple windowing shell that uses Tk and Tcl. |
| 28 | 4. A collection of demonstration scripts to illustrate the use |
| 29 | of various features of Tk. |
| 30 | |
| 31 | The enclosed code is known to run on most versions of SunOS and Ultrix |
| 32 | in combination with the X11R4 and X11R5 window servers from MIT. It |
| 33 | should also run with few or no changes on H-P and IBM workstations. |
| 34 | |
| 35 | 2. What's New In This Release |
| 36 | ----------------------------- |
| 37 | |
| 38 | Tk 2.2 is a major new release with a number of new features relative |
| 39 | to the 2.1 release. Here is a summary of some of the most significant |
| 40 | improvements: |
| 41 | |
| 42 | - There is now a text widget. It will display multiple lines of text |
| 43 | and allows the text to be edited (but the set of bindings for |
| 44 | editing isn't very rich yet). It also includes a tagging mechanism |
| 45 | that allows you to change the fonts, colors, etc. on a character- |
| 46 | by-character basis, and you can associate bindings with tags to |
| 47 | implement hypertext-like features. It handles large texts |
| 48 | efficiently. |
| 49 | |
| 50 | - Canvases have been improved in many ways, including new item types |
| 51 | (arcs, bitmaps, and subwindows), Bezier spline support for lines |
| 52 | and polygons, "coords" and "bbox" widget commands, and many other |
| 53 | improvements and bug fixes. |
| 54 | |
| 55 | - There is a new "grab" command that can be used to create modal dialog |
| 56 | boxes. |
| 57 | |
| 58 | - There is a new "tkwait" command for waiting for particular events to |
| 59 | occur (such as modal dialog box to complete its task). |
| 60 | |
| 61 | - The menu bindings have been completely reworked to have better Motif |
| 62 | compliance, such as keyboard traversal. |
| 63 | |
| 64 | - Individual menu entries can now have their own colors and fonts. |
| 65 | |
| 66 | - Most widgets (e.g. buttons, entries, text) now have a "-state" option |
| 67 | that can be set to "disabled" to make the widget insensitive. |
| 68 | |
| 69 | - A new "-disabledForeground" option allows you to request that disabled |
| 70 | buttons and menu entries be displayed in a dimmer color rather than with |
| 71 | a stippled version of the original color. |
| 72 | |
| 73 | - Entries and messages can now be tied to a variable so that either is |
| 74 | updated if the other changes. |
| 75 | |
| 76 | A good way to try out the new features is to run the "widget" demo; |
| 77 | there are a number of new demonstrations to illustrate the new features. |
| 78 | This release also contains many bug fixes. For a complete description |
| 79 | of the changes in this release, see the file "changes". As far as I |
| 80 | know there should not be any compatibility problems with respect to the |
| 81 | 2.1 release. |
| 82 | |
| 83 | 3. Documentation |
| 84 | ---------------- |
| 85 | |
| 86 | Manual entries for Tk are in the "doc" subdirectory as a set of files |
| 87 | with ".man" extensions. Man pages whose names start with capital letters |
| 88 | are for the procedures in Tk's C library. All other man pages document Tcl |
| 89 | commands provided by Tk. To print any of the man pages, cd to the "doc" |
| 90 | directory and invoke your favorite variant of troff using the normal |
| 91 | -man macros, for example |
| 92 | |
| 93 | ditroff -man <file> |
| 94 | |
| 95 | where <file> is the name of the man page you'd like to print. If you'd |
| 96 | like a complete set of hardcopy manual entries, send me a message with |
| 97 | your street address. |
| 98 | |
| 99 | Manual entries for Tcl are available in the subdirectory "tcl/doc"; |
| 100 | see the README file in the "tcl" directory for more information. |
| 101 | |
| 102 | Unfortunately, there doesn't yet exist a tutorial-style introduction |
| 103 | to the facilities of Tcl and Tk. The papers give a general introduction, |
| 104 | but it may be difficult to make the transition from the papers to the |
| 105 | manual entries. If you are familiar with the Xt toolkit then the Tk |
| 106 | facilities will probably be easy to pick up from the manual entries. |
| 107 | If you have no experience with X or Xt, you may wish to wait another |
| 108 | 6-12 months to use Tk, until a more gentle introduction is available. |
| 109 | |
| 110 | 4. Compiling Tk |
| 111 | --------------- |
| 112 | |
| 113 | Before attempting to compile Tk, personalize Makefile by following the |
| 114 | directions at the beginning of the file. You should also configure |
| 115 | Tcl by following the directions in the file "tcl/README". Then type |
| 116 | "make" in the top-level directory (the one that contains this file). |
| 117 | This will compile the Tk library and generate a simple windowing shell |
| 118 | called "wish". It will also compile the Tcl library, which is in the |
| 119 | "tcl" subdirectory. |
| 120 | |
| 121 | 5. Installing Scripts |
| 122 | --------------------- |
| 123 | |
| 124 | Tk depends on a library of scripts that establish default behaviors |
| 125 | for Tk widgets and do many other things. Tk normally expects the |
| 126 | scripts to be in /usr/local/lib/tk. Create this directory and copy |
| 127 | everything in the "library" subdirectory to it, including both files |
| 128 | and subdirectories. Or, if you don't want to create a subdirectory of |
| 129 | /usr/local/lib (or if you can't), you can either make a symbolic link |
| 130 | from there to the library subdirectory or you can add a "-DTK_LIBRARY" |
| 131 | switch to CFLAGS in Makefile; this will allow you to put the script |
| 132 | library anywhere you like. |
| 133 | |
| 134 | I also recommend installing the wish binary in /usr/local. The demo |
| 135 | scripts all work best when it is installed there. |
| 136 | |
| 137 | 6. Getting Started |
| 138 | ------------------ |
| 139 | |
| 140 | Once wish is compiled you can use it to play around with the Tk |
| 141 | facilities. If you run wish with no arguments, it will open a small |
| 142 | window on the screen and read Tcl commands from standard input. |
| 143 | Or, you can play with some of the pre-canned scripts in the subdirectory |
| 144 | scripts/demos. See the README file in the directory for a description |
| 145 | of what's available. The file scripts/demos/widget is a script that |
| 146 | you can use to invoke many individual demostrations of Tk's facilities. |
| 147 | |
| 148 | If you want to start typing Tcl/Tk commands to wish, I'd suggest |
| 149 | starting with the "bind" command. Then learn about a widget-creation |
| 150 | command like "button", and also learn about the "pack" and "place" |
| 151 | commands for geometry management. Note: when you create a widget, |
| 152 | it won't appear on the screen until you tell a geometry manager about |
| 153 | it. The only geometry managers at present are the packer and the placer. |
| 154 | If you don't already know Tcl, read the Tcl paper and the Tcl.man manual |
| 155 | entry in the tcl subdirectory. |
| 156 | |
| 157 | The easiest way to learn about writing new widgets is probably to look |
| 158 | at existing widget implementations. The demos directory contains an |
| 159 | example of a trivial widget, which you might find useful as a starting |
| 160 | point for writing new widgets. You might also take a look at main.c, |
| 161 | the main program for wish, to see how to write a main program that uses |
| 162 | the facilities of Tk and Tcl. |
| 163 | |
| 164 | 7. Newsgroup |
| 165 | ------------ |
| 166 | |
| 167 | There is a network news group "comp.lang.tcl" intended for the exchange |
| 168 | of information about Tcl, Tk, and related applications. Feel free to use |
| 169 | this newsgroup both for general information questions and for bug reports. |
| 170 | I read the newsgroup and will attempt to fix bugs and problems reported |
| 171 | to it. |
| 172 | |
| 173 | 8. Known Problems |
| 174 | ----------------- |
| 175 | |
| 176 | There are still many imperfections with the system. Below is a list |
| 177 | of some of the more serious omissions and bugs: |
| 178 | |
| 179 | 1. The widgets don't look very good on monochrome displays right now, |
| 180 | because I haven't had a chance to figure out how to do the 3-D |
| 181 | effects right without color. The widgets should look pretty good in |
| 182 | color. The widgets aren't fully Motif-compliant yet. In particular, |
| 183 | there is no keyboard navigation yet. The widgets will eventually |
| 184 | become fully Motif-compatible (assuming I can figure out how Motif |
| 185 | widgets are supposed to look and feel). |
| 186 | |
| 187 | 2. Tk doesn't work very well with virtual-root window managers such |
| 188 | as tvtwm. |
| 189 | |
| 190 | The file ToDo contains a list of various smaller bugs and mis-features |
| 191 | that haven't been fixed yet. |
| 192 | |
| 193 | 9. Feedback Wanted |
| 194 | ------------------ |
| 195 | |
| 196 | I'm very interested in getting feedback from you both about bugs and about |
| 197 | overall design issues. Send your comments to "ouster@sprite.berkeley.edu". |
| 198 | I'll do my best to fix show-stopping bugs quickly, but most other things |
| 199 | may not get fast turnaround, since I already have a zillion high-priority |
| 200 | things to fix or implement. Before submitting requests for new features |
| 201 | you may wish to check the file ToDo, which has a list of things I already |
| 202 | know about and plan to implement soon. |
| 203 | |
| 204 | 7. The Future |
| 205 | ------------- |
| 206 | |
| 207 | Tk is still young. I expect it to undergo substantial changes as I learn |
| 208 | more about its strengths and weaknesses. Some of the changes will not be |
| 209 | backward compatible: at this point I think it's more important to fix |
| 210 | problems and improve Tk's structure than to maintain compatibility. At |
| 211 | some point in the next year or so there will be a new release with major |
| 212 | incompatibilities. My plan is to save up as many as possible of the |
| 213 | incompatible changes that are needed and do them all at once. |