README
RCS: @(#) $Id: README,v 1.2 1999/05/08 23:27:58 dejong Exp $


Abstract
--------

      This demo shows two ways extend Tcl with Java classes.  Both
      examples use the Java StopWatchThread class.  One interface is
      written in Java; the other in Tcl.

Why Bother?
-----------

      To choose an appropriate design for your program, it is
      important to understand the flexibility and capability
      supplied by these two interfaces.

      The StopWatchThread class, an extension of the thread class, controls
      a stopwatch GUI and alternates between halting and counting down by
      seconds.

      One way to extend Tcl with this class is to write Java code that
      defines Tcl commands which access StopWatchThread methods.  When we
      write the interface in Java, we create a "extension" of Tcl commands.
      The StopWatchExtension contains one Tcl command "sw", through which the
      user controls communication with a StopWatchThread object.

      "sw" command specs:

	sw new           --> starts a new stopwatch at time 0
	sw set [seconds] --> sets time to seconds, starts counting down
	sw stop          --> returns current time, halts the stopwatch
	sw resume        --> returns current time, starts counting down
	sw die           --> removes the stopwatch window


      The second way to extend Tcl with the StopWatchThread class is to
      write Tcl procedures which access its methods directly via the
      the Java Extension.  The swCmd.tcl file contains such code.  The 
      procedures defined in swCmd.tcl include:

	swNew                --> starts a new stopwatch at time 0;
	                         returns the watch's id.
	swSet [id] [seconds] --> sets time to seconds, starts counting down
	swStop [id]          --> returns current time, halts the stopwatch 
	swResume [id]        --> returns current time, starts counting down 
	swDie [id]           --> removes the stopwatch window 


Choosing the Best Interface
---------------------------

      Interfacing Tcl with Java via the Java Extension has several
      advantages and disadvantages.  Coding in Tcl is quick and easy, which
      is great for prototyping.  Also, the Java Extension offers a mechanism
      for dynamically changing code.

      On the other hand, defining new Tcl commands in Java offers more
      structure and possibly fewer programming errors.  This style of
      interface may also be more efficient.

Running the Demo
----------------

      The first thing you will need to do is run "make demos" in your
      build directory. This will create a demos subdirectory in your
      build directory and it will compile any .java files the demo uses.

      To run the StopWatch demo by adding the StopWatchExtension
      ("sw" Tcl command defined in Java), type
      "java::load -classpath . StopWatchExtension" at your java enabled
      Tcl prompt. Now you can execute the "sw" command with the
      appropriate arguments.

      To add the sw* Tcl procedures, after adding the
      StopWatchExtension (as shown above), type
      "source swCmd.tcl" at the Tcl command prompt.  Now you can execute 
      the commands "swNew", "swSet", . . .

