Subversion Repositories or1k

The Tk Toolkit

RCS: @(#) $Id: README,v 1.1.1.1 2002-01-16 10:25:47 markom Exp $

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.0.3, which is the third patch update

for Tk 8.0.  This release is designed to work with Tcl 8.0.3 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

Other books are listed at

http://www.scriptics.com/resource/doc/books/

http://www.tclconsortium.org/resources/books.html

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.scriptics.com/

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 Windows 98.)

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 Tcl/Tk

        (http://www.scriptics.com/) 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 (you may need to replace "patch -p" with "patch -p0"

        depending on your version of the patch program):

            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 <> 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. To subscribe send a message to:

        wintcl-request@tclconsorium.org

        or

        mactcl-request@tclconsorium.org

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. Tcl Resource Center

----------------------

Visit http://www.scritics.com/resource/ to see an annotated index of

many Tcl resources available on the World Wide Web.  This includes

papers, books, and FAQs, as well as extensions, applications, binary

releases, and patches.  You can contribute patches by sending them

to .  You can also recommend more URLs for the

resource center using the forms labeled "Add a Resource".

10. 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 Scriptics.  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

Scriptics (info@scriptics.com), NeoSoft (info@neosoft.com),

Computerized Processes Unlimited (gwl@cpu.com),

and Data Kinetics (education@dkl.com).

11. Release organization

------------------------

The version numbers described below are available to Tcl scripts

as the tk_version and tk_patchLevel Tcl variables.

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 used to have a suffix such as p1 or p2.  Now we use

a 3-part version number: major.minor.patchlevel. (e.g., 8.0.3)

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.