OS/2 Shareware BBS: 10 Tools/10-Tools.zip/tkisrc04.zip/README.Tk

Text File | 1998-08-13 | 14KB | 302 lines

The Tk Toolkit

by John Ousterhout (and many others at Sun Microsystems and elsewhere)
[e-mail]

SCCS: @(#) README 1.29 96/04/11 17:22:21

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 they may be available
    in the future for some 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) Check for patches.  Look in the FTP directory from which you
        retrieved the base distribution and see if there are files with
    names like tk4.1p1.patch, tk4.1p2.patch, etc.  These files may
    also have .gz or .Z extensions to indicate compression.  If you find
    any patch files, apply them to the source directory in order
    from "p1" up.  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 ([e-mail]), Computerized Processes Unlimited
([e-mail]), and Data Kinetics ([e-mail]).

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.