318 lines
15 KiB
Plaintext
318 lines
15 KiB
Plaintext
The Tk Toolkit
|
|
|
|
SCCS: @(#) README 1.32 96/07/31 16:29:10
|
|
|
|
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 4.1. This release is designed to work
|
|
with Tcl 7.5 and may not work with any other version of Tcl.
|
|
|
|
The main new feature in this release is support for the Mac and PC
|
|
platforms. Aside from the ports, the release consists mostly of bug
|
|
fixes. There are no major new features.
|
|
|
|
2. Documentation
|
|
----------------
|
|
|
|
The best way to get started with Tk is to read one of the introductory
|
|
books on Tcl and Tk:
|
|
|
|
Tcl and the Tk Toolkit, by John Ousterhout,
|
|
Addison-Wesley, 1994, ISBN 0-201-63337-X
|
|
|
|
Practical Programming in Tcl and Tk, by Brent Welch,
|
|
Prentice-Hall, 1995, ISBN 0-13-182007-9
|
|
|
|
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, 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 Tcl that you want.
|
|
Patch releases are available in two forms. A file like
|
|
tk4.1p1.tar.Z is a complete release for patch level 1 of Tk
|
|
version 4.1. 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 tk4.1p1.patch, tk4.1p2.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:
|
|
tk4.1p1.patch must be applied to an unpatched Tk 4.1 release
|
|
to produce a Tk 4.1p1 release; tk4.1p2.patch can then be
|
|
applied to Tk 4.1p1 to produce Tk 4.1p2, and so on. To apply an
|
|
uncompressed patch file such as tk4.1p1.patch, invoke a shell
|
|
command like the following from the directory containing this
|
|
file:
|
|
patch -p < tk4.1p1.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 tk4.1p1.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 tk4.1p1.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 4.1
|
|
-------------------------------
|
|
|
|
The main change for Tk 4.1 is that Tk now runs on Macintosh and
|
|
PC platforms as well as UNIX. The PC port runs under Windows 3.1
|
|
(with Win32s), Windows 95, and Windows NT. This required a lot of
|
|
reorganization of the sources but it didn't require any changes to
|
|
Tk's externally visible interfaces.
|
|
|
|
Besides the ports and numerous bug fixes, Tk 4.1 contains the following
|
|
new features. Existing scripts for Tk 4.0 should run unchanged under
|
|
Tk 4.1.
|
|
|
|
1. There is a new command "grid" that implements a table style of
|
|
geometry management. This will be used by future releases of
|
|
the SpecTcl GUI builder.
|
|
|
|
2. The wish main program now supports -visual and -colormap command-
|
|
line arguments.
|
|
|
|
3. Text widgets have been improved in several ways:
|
|
- Performance when there are many tags should be much better now;
|
|
tags should only be slow if there are a very large number of tags
|
|
on an individual character.
|
|
- There are new "dump", "mark next", "mark prev" and "tag prevrange"
|
|
widget commands for extracting information out of a text widget.
|
|
|
|
4. Tk is now a first-class Tcl package (in the sense of the new
|
|
Tcl "package" command). You can load Tk into a slave interpreter
|
|
"foo" with the command "load {} Tk foo" if Tk is statically
|
|
linked. Tk can also be compiled as a shared library using the
|
|
--enable-shared switch for "configure".
|
|
|
|
5. The event loop has moved to Tcl. Many procedures and #defines
|
|
have been renamed, such as the "tkerror" command (now "bgerror"),
|
|
TK_READABLE (now TCL_READABLE), and Tk_DoOneEvent (now
|
|
Tcl_DoOneEvent). All of the old Tk names are still supported
|
|
for backwards compatibility but you should switch over ASAP to
|
|
the new ones.
|
|
|
|
6. Tk_Preserve, Tk_Release, and Tk_Eventually have been moved to Tcl.
|
|
There are #defines in tk.h for backward compatibility, but you
|
|
should switch ASAP to the new Tcl APIs.
|
|
|
|
7. There is a new command "after info" that allows you to find out about
|
|
pending "after" handlers that haven't yet fired.
|
|
|
|
8. Scrollbars and scales now have proper button 2 support as required
|
|
by Motif.
|
|
|
|
9. Menus have two new options, -transient and -tearoffcommand.
|
|
|
|
10. Entries have a new "bbox" widget command.
|
|
|
|
11. When manual pages are installed, additional links are created for
|
|
each of the procedures described in the manual page, so that it's
|
|
easier to invoke the "man" command.
|
|
|
|
12. Wish supports a new "--" option: it will only process options
|
|
up through the --; anything after that will be passed through
|
|
to the application in the argc and argv variables.
|
|
|
|
Although Tk 4.1 is compatible with Tk 4.0 scripts at the Tcl level,
|
|
there are a few incompatible changes in Tk's C APIs. These will
|
|
only affect C code, not Tcl/Tk scripts, and they are obscure enough that
|
|
they probably won't affect many existing extensions. If there are any
|
|
potential problems, they will be detected by an ANSI-compliant C compiler
|
|
such as gcc.
|
|
|
|
1. The procedure Tk_CreateMainWindow no longer exists. Instead,
|
|
Tk_Init does everything that Tk_CreateMainWindow used to do.
|
|
|
|
2. The procedures Tk_EventInit and Tk_CreateFileHandler2 have been
|
|
eliminated. Tk_EventInit is no longer needed since the event loop
|
|
is always available. Tk_CreateFileHandler doesn't make sense with
|
|
the new notifier in Tcl, but you can get the same effect with the
|
|
new "event source" mechanism (see the Notifier.3 manual entry in
|
|
Tcl).
|
|
|
|
3. Tk doesn't export any global C variables anymore, because this
|
|
doesn't work with Windows DLLs. The C variable tk_NumMainWindows
|
|
has been replaced with the procedures Tk_GetNumMainWindows(), and
|
|
the variable tk_CanvasTagsOption has been replaced with the
|
|
procedures Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc.
|
|
|
|
4. The interface to Tk_RestrictProc has changed so that the restrict
|
|
procedure can ask for an event to be discarded, as well as processed
|
|
or deferred.
|
|
|
|
For a complete list of all the changes in this release, see the file
|
|
"changes" in this directory.
|
|
|
|
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
|
|
omp.lang.tcl may be able to offer a solution. The normal turn-around
|
|
time for bugs is 2-4 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.
|