path: root/README

README:  Tk

	Tk is maintained, enhanced, and distributed freely as a
	service to the Tcl community by Scriptics Corporation.

RCS: @(#) $Id: README,v 1.12 1999/02/17 02:05:30 hershey Exp $

Contents
--------
    1. Introduction
    2. Documentation
    3. Compiling and installing Tk
    4. Getting started
    5. Summary of changes in Tcl 8.0
    6. Development tools
    7. Tcl newsgroup
    8. Tcl contributed archive
    9. Tcl Resource Center
    10. Mailing lists
    11. Support and bug fixes
    12. Tk version numbers

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.5, which is the fifth patch update
for Tk 8.0.  This release is designed to work with Tcl 8.0.5 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.

Tk is a freely available open source package.  You can do virtually
anything you like with it, such as modifying it, redistributing it ,
and selling it either in whole or in part.  See the file
"license.terms" for complete information.

2. Documentation
----------------

The best way to get started with Tk is to read about Tk on the
Scriptics Web site at:

	http://www.scriptics.com/scripting

Another good way to get started with Tcl is to read one of the
introductory books on Tcl:

    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/

There is also an official home for Tcl and Tk on the Scriptics Web site:

	http://www.scriptics.com

These Web pages include information about the latest releases, products
related to Tcl and Tk, 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!

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.

2a. Unix Documentation
----------------------

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

2b. Windows Documentation
-------------------------

The "doc/help" subdirectory in this release contains a complete set of
Windows help files for TclPro.  Once you install this Tcl release, a
shortcut to the Windows help Tcl documentation will appear in the
"Start" menu:

	Start | Programs | Tk | Tk Help

3. Compiling and installing Tk
------------------------------

This release contains everything you should need to compile and run
Tk under UNIX, PCs (either Windows NT, Windows 95, or Win 3.1 with
Win32s), and Macintoshes.

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, 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 Scriptics Tcl Resource Center
        (http://www.scriptics.com/resource).  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. 

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.  See the documentation section above for more
details.

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. Development tools
--------------------

A high quality set of commercial development tools is now available to
accelerate your Tk application development.  Scriptics' TclPro
product provides a debugger, static code checker, packaging utility,
and bytecode compiler.  Visit the Scriptics Web site at:

	http://www.scriptics.com/tclpro

for more information on TclPro and for a free 30-day evaluation
download.

7. Tcl newsgroup
----------------

There is a network news group "comp.lang.tcl" intended for the
exchange of information about Tcl, Tk, and related applications.  The
newsgroup is a greata place to ask general information questions.  For
bug reports, please see the "Support and bug fixes" section below.

8. Tcl 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.scriptics.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 development tools, extensions,
applications, binary releases, and patches.  You can also recommend
additional URLs for the resource center using the forms labeled "Add a
Resource".

10. Mailing lists
-----------------

A couple of  Mailing List have been set up to discuss Macintosh or
Windows related Tcl issues.  To subscribe send a message to:
	
	wintcl-request@tclconsortium.org
	mactcl-request@tclconsortium.org
	
In the body of the message (the subject will be ignored) put:
	
	subscribe mactcl Joe Smith
	
Replacing Joe Smith 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 put the line:

	information mactcl
	
in the body instead (or wintcl).

11. Support and bug fixes
-------------------------

Scriptics is very interested in receiving bug reports, patches, and
suggestions for improvements.  We prefer that you send this
information to us via the bug form on the Scriptics Web site, rather
than emailing us directly.  The bug form is at:

	http://www.scriptics.com/support/bugForm.html

The bug form was designed to give uniform structure to bug reports as
well as to solicit enough information to minimize followup questions.
The bug form also includes an option to automatically post your report
on comp.lang.tcl.  We strongly recommend that you select this option
because someone else who reads comp.lang.tcl may be able to offer a
solution.

When reporting bugs, please provide full information about the Tcl/Tk
version and the platform on which you are running Tcl/Tk.  Also,
please include 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?

We will log and follow-up on each bug, although we cannot promise a
specific turn-around time.  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 Tcl/Tk turns into a kitchen sink).
It's very difficult to make incompatible changes to Tcl/Tk at this
point, due to the size of the installed base.

The Tcl 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 at:

	http://www.scriptics.com/training

Also see the following Web site for links to other organizations that
offer Tcl/Tk training:

	http://www.scriptics.com/resource/commercial/training

12. Tk version numbers
----------------------

You can test the current version of Tk by examining the
tk_version and tk_patchLevel variables.  The tk_patchLevel
variable follows the naming rules outlined below (e.g., 8.0.5).
The tk_version just has the major.minor numbers in it (e.g., 8.0)

Each Tk release is identified by two numbers separated by a dot, e.g.
3.6 or 4.0.  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. 4.1, 4.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 4.0b1 is the first beta release of Tk version
4.0, Tk 4.0b2 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.

(Note: This compatibility is true for Tcl scripts, but historically
the Tcl C APIs have changed enough between releases that you may need
to work a bit to upgrade extensions.)

Patch releases now have a suffix such as ".4" or ".5".  Prior to
version 8.0.3, patch releases had the suffix "p1" or "p2".  So, the
8.0 release went to 8.0p1, 8.0p2, 8.0.3, 8.0.4, and 8.0.5.  The alphas
and betas continue to use the 'a' and 'b' letters in their
tk_patchLevel.  Patch releases normally contain bug fixes only.  A
patch release (e.g Tk 8.0.5) should be completely compatible with the
base release from which it is derived (e.g. Tk 8.0), and you should
normally use the highest available patch release.

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.

13. Thank You
-------------

We'd like to express our thanks to the Tcl community for all the
helpful suggestions, bug reports, and patches we have received.
Tcl/Tk has improved vastly and will continue to do so with your help.