
TkOAT README

RCS:  $Id: README,v 1.2 1996/11/04 03:00:54 safonov Exp $

1. Introduction
---------------

This directory contains the sources and documentation for TkOAT, an 
extension to Tk that enables tracing attributes of Tk widgets and object
attributes. TkOAT is based on OAT (Object Attribute Trace), an extension 
to Tcl that provides a protocol for creating new traceable object types. 
See the README file in OAT distribution for more information on OAT.

TkOAT adds two new traceable object types, Tk widgets and canvas items.
Traces on widget attributes are manipulated by specifying "widget", "winfo", 
and "wdelete" keywords to the "oatrace" command - similar to original
Tcl "variable", "vinfo", and "vdelete". Traces on canvas items are
manipulated by specifying "citem", "cinfo", and "cdelete" keywords
to the "oatrace" command.

An example of creating a trace on a Tk widget attribute
looks as follows:
  oatrace widget .top -width w update_height
where ``update_width'' is a Tcl procedure that accepts widget name, 
attribute name, operation (write) as arguments, and sets the widget 
``-height'' attrribute to be twice the ``-width''.

Since stock Tk does not have the mechanism to notify about widget
attribute changes, a patch to Tk source was required. It is distrbuted
with TkOAT, and modifies several C files in the ``generic'' subdirectory
of the Tk distribution, as well as the file Makefile.in in the ``unix'' 
subdirectory.

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

Look at README and TODO files for OAT and TkOAT. The header file
oat.h contains documented prototypes for externally accessible C functions
in the OAT extension. Look at tkoat.c in the TkOAT extension, and patches to
Tk 4.1/4.2 for information on how to create new traceable object types.

3. Installation
-------------------------------

TkOAT works with Tcl 7.5/7.6, and Tk 4.1/4.2. It has been developed 
and tested on Unix platforms only (Linux 2.x, Solaris 2.4, Irix 5.3, 
HPUX 10.0). Makefile updates that allow TkOAT to compile
on Windows/Mac are welcome. 

By default TkOAT is compiled as a shared library and requires Tk
to be a dynanically loaded package. Look at Jan Nijtmans's plus-patches at
http://www.nici.kun.nl/~nijtmans/tcl/index.html - they allow Tk
to be dynamically loaded.

- Unarchive the TkOAT distribution in the directory where tcl7.x and 
tk4.y directories are located:
  gunzip -c tkoat.tar.gz | tar xvf -

This will create create subdirectory ``tkoat'' under the current directory,
and place the TkOAT there. It will also create a patch file for Tk, 
``tk4-trace.patch'' in the current directory.

- Patch the Tk source (4.1 or 4.2): from the base Tk source directory, 
run the command:
  patch -p1 < ../tk4-tkoat.patch

- Check for "hunk failed..." messages from patch (there shouldn't be any),
and after patch has completed, check that there are no rejected patches:
  find ./ -name '*.rej' -print

- Change to the newly created ``tkoat'' directory, and run configure:
  ./configure --enable-shared [--with-tcl=DIR] [--with-tk=DIR]

If you do not specify the --with-tcl and --with-tk arguments to configure, 
it assumes Tcl and Tk sources live in directories tcl7.5 and tk4.1 at the 
same level as the tkoat directory. You can choose which Tcl version, 7.5 
or 7.6, to use by setting the tcl_ver variable at the beginning of 
configure and configure.in. Same goes for choosing Tk version: set tk_ver
to 4.1 or 4.2 in configure and configure.in scripts. The Tk directory
should point to the patched one.

Note that the TkOAT configure script relies on tclConfig.sh and tkConfig.sh
scripts being present in tcl7.x/unix and tk4.x/unix directories, respectively,
so Tcl and Tk should be configured prior to configuring TkOAT.

The TkOAT configure script is based on the dynamic extension example 
put out by SunLabs Tcl group. The TkOAT configure scripts accepts the 
standard --enable-gcc switch.

- Run make. If you get an error trying to run tclsh, make sure the Makefile
points to a valid ``tclsh'' executable. If there are errors loading 
libtcl7.x.so or liboatrace.so, make sure that LD_LIBRARY_PATH (or other 
similar variable, e.g., LD_ELF_LIBRARY_PATH), points to the directories 
containing the Tcl and newly compiled OAT shared libraries.

4. Summary of changes in TkOAT 1.0
--------------------------------

This is the first public beta-release.

5. Support and bug fixes
------------------------

Please email your system configuration (uname -a), Tcl and Tk versions,
compiler brand and version (gcc -v for gcc), suggested functionality
or bug reports to me, safonov@cs.umn.edu.

