
This is version 2.3 of the BLT library.  It's an extension to the
Tcl/Tk toolkit.  You simply compile and link with the Tcl/Tk
libraries. It does not require the Tcl or Tk source files.

BLT is available from 

    ftp.tcltk.com 

in the "pub/blt" directory. The URL is 

    ftp://ftp.tcltk.com/pub/blt/BLT2.3.tar.gz


This release has been compiled and tested with versions:

	Tk 4.1 and 4.2.  

What is BLT? 

    BLT is an extension to the Tk toolkit. It adds new widgets such as
    plotting widgets (X-Y graph, barchart), geometry managers, and 
    miscellaneous commands.  

    BLT adds the following commands to Tk:

      graph      An X-Y graph widget.  

      barchart   Displays 2-D data as bars.

      stripchart 

      vector     Creates a vector of floating point values.  The vector's 
		 components can be manipulated in three ways: through a Tcl 
		 array variable, a Tcl command, or the C API. 

      table      Table-based geometry manager that lets you specify widget 
		 layouts by row and column positions in the table. Unlike 
		 the packer or grid, you finely control and constrain 
	         window sizes.

      busy       For handling user-interaction when the application is "busy".
		 Manages an invisible "busy" window which prevents further 
		 user device (keyboard, mouse, button, etc.) interactions.
		 Also provides a different cursor which supersedes application
		 cursors.

      bgexec     Like Tcl's "exec ... &", but collects the output, error, and 
		 status of the detached UNIX subprocesses.  Sets a Tcl variable 
		 upon completion.  

      bitmap     Lets you read and write bitmaps from Tcl. You can also define 
		 X bitmaps and create bitmaps from text strings.  Other options 
		 let you rotate and scale bitmaps.

      drag&drop  Adds drag-n-drop capabilities to Tk.  It uses "send"-style 
		 communication between drag-drop sources and targets.  The 
		 result is a much more powerful drag-and-drop mechanism than 
 		 is available with OpenLook or Motif.  

      spline     Computes a spline fitting a set of data points (x and y 
 		 vectors) and produces a vector of the interpolated images 
                 (y-coordinates) at a given set of x-coordinates.

      htext      A simple hypertext widget. Allows text and Tk widgets to
		 be combined in a scroll-able text window.  Any Tk widget 
		 can be embedded and used to form hyper-links.  Other 
		 options allow for selections and text searches.

      winop      Basic window operations. You can raise, lower, map, or, 
		 unmap windows.  Other operations let you move the pointer
		 or take photo image snapshots of Tk widgets.

      watch      Lets you specify Tcl procedures to be run before and/or
		 after every Tcl command.  May be used for logging, tracing, 
		 profiling, or debugging or Tcl code.

      bltdebug   Prints out each Tcl command before it's executed.  


How to compile and test BLT?

 The following describes how to compile and install the BLT library.

   1. Uncompress and untar the distribution file.  

	   zcat BLT2.3.tar.gz | tar -xvf - 

      This will create a directory "blt2.3" with the following subdirectories:

			   blt2.3
 	 	______________|______________
		|          |       |        |
	      demos   library     man      src
					    |
					  shared

   2. Run ./configure

      Go into the "blt2.3" directory 

	   cd blt2.3

      and run the auto-configuration script "./configure".  Tell where to find 
      the Tcl and Tk header files and libraries with the "--with-tcl" switch.

	   ./configure --with-tcl=/util/lang/tcl

      Switches:

	  --with-tcl=dir	Top level directory where the Tcl and/or Tk 
				header files and libraries are installed. Will 
				search both "$dir/include" and "$dir/lib".

	  --with-tk=dir		Top level directory where the Tk header files 
				and libraries are installed.

	  --with-cc=program	Lets you specify the C compiler, such as 
				"acc" or "gcc". 

	  --prefix=path		By default, the bltwish demo program, the BLT
				header files, libraries, scripts, and manual
				pages are installed in "/usr/local/blt".  This 
				lets you pick another location.

     The configure script creates a header file "src/bltConfig.h". It will also 
     generate new Makefiles from their respective templates (Makefile.in).

	   Makefile.in	 	        ==> Makefile
	   src/Makefile.in	        ==> src/Makefile
	   src/shared/Makefile.in	==> src/shared/Makefile
	   man/Makefile.in		==> man/Makefile
	   library/Makefile.in		==> library/Makefile

   3. Compile the libraries and build the demonstration program "bltwish".

	   make 

   4. Test by running the demos. 

      Go into the demos directory 

	   cd demos

      and run the test scripts.

	   ./graph

      If your system doesn't support "#!" in shell scripts, then it's

	   ../bltwish ./graph


   5. Installing BLT

	  make install

      The following directories will be created when BLT is installed.  
      By default, the top directory is /usr/local/blt.  
                     
              ___________|__________
              |     |        |     |
             bin  include   lib   man
                             |
                           blt2.3   
                         ____|____
                         |       |
                       demos   dd_protocols

      You can change the top directory by supplying the "--prefix=dir" switch 
      to ./configure.

   *6. (Optional) Compiling BLT into your own custom "wish".

      Add the following lines to your program's Tcl_AppInit routine in
      tkAppInit.c

	   if (Blt_Init(interp) != TCL_OK) {
	       return TCL_ERROR;
	   }

      then link with libBLT.a.  And that's all there's to it.
	
   7. Send bugs reports, suggestions, etc. to

	   gah@bell-labs.com and/or ghowlett@fast.net

      Make sure you include BLT and the version number in the subject line.


What's new in 2.3?

 1. A new stripchart widget.  It is essentially the graph widget with
    additional capabilities, such as pen styles for individual line 
    segments, automatic axis shifting, etc.  Thanks to Thomas Accardo and
    Computerized Processes Unlimited for their contributions.

   New axis options

    -range value	Says how big a range of values to display. 

    -shiftby value	Automatically shift the axis range by this amount.

 2. New features in the graph and barchart widgets.

  o Virtual axis components

    You can now create any number of axes and map elements to them.

        .graph axis create "temp"
	.graph axis configure "temp" -loose yes
	.graph element create "e1" -mapy "temp"

    Only four axes can be displayed at a time, but you can swap axes
    in and out.

	.graph yaxis use "temp"
		...
	.graph yaxis use "y"

    Or you can display the min/max values of the axis in the top/bottom
    of the plotting area. New axis options include 

    -limits specList	Specifies printf-like description for the min
			and max values.
	
  o Pen components	

    Pens hold line or bar attributes.  You can use the pen names with
    elements to define pen styles for specific data points (symbols or
    bars).

        .graph pen operation penName args...

  o New options for elements.

    -weights vector	The weight vector lets you specify a value for each 
			data point.  These values are used to determine
			which pen style is to be used to draw the data point
			(symbol or bar segment).

    -styles styleList   Defines a set of pens and their weight ranges. 

    -smooth level	Specifies how smoothly to draw  line segments 
			connecting data points. The smoothing levels are:

			"linear"     A single segment is drawn between points.

			"step"       Two segments are drawn. One is horizontal 
				     at the old y-coordinate, the second is
				     vertical at the new x-coordinate. 

			"natural"    Multiple line segments are drawn using
				     a cubic spline.

			"quadratic"  Multiple line segments are drawn using
				     a quadratic spline.

    -pen penName	Specifies a default pen for the element.

    -activepen penName	Specifies the active pen for the element.

    -hide boolean	Takes the place of the "-mapped" option.  The "-mapped"
			will be removed in an upcoming release.

    -symbol "bitmap mask" 
			X-Y graph elements now let you use X bitmaps as symbols.
			
  o Miscellaneous changes to graph and barchart widgets

    New "image" marker type.  Lets you imbed images into the graph.  

    Bitmap markers are now stretch-able.  You can also specify a mask for
    them.

    Additional -barmode mode "overlap". 

    Hierarchical resource names and classes.  Class names no longer prefix
    the option resource names.  For example you can specify the line width
    for all elements and the color of a single element.

    	option add *Graph.Element.LineWidth	1
	option add *Graph.line1.LineWidth	2

    This works for all graph components.

    Better PostScript generation. All markers can be printed, including 
    "window" and "image" markers.

    Grid lines -mapx and -mapy options now take the name of an axis as
    a value.  The value can also be "", which indicates no lines for
    that X-axis or Y-axis.  The new default for barcharts is to display
    only the Y-axis grid lines.

    There's a new "snap" operation that lets you take a snapshot of a graph
    and saves it to a photo image.  Using the image command you can write 
    out a PPM file.

 3. Vector improvements.

    New -command and -variable switches let you create a vector using
    a Tcl command and variable of different names from the vector.

	# Create a new command "fred" and array variable "barney"
	vector -command fred -variable barney wilma(50)
 
    Sometimes you don't want to automatically create a variable or command. 
    If the name is "", no command and/or variable is used.

	# Create an vector without a Tcl variable.
	vector -command "fred" -variable "" wilma(50)

    Future Incompatibility:  In the next release, vectors will, by default, 
			     NOT create array variables. You'll need to set 
			     the -variable switch.

    C API now lets you define your own variable indices like "q1" "skew"
     
 4. Bgexec working again

    Fixed bgexec to not use Tcl_CreatePipeline (aka the MX missle system of
    C API's).  This kind-of works in Tcl 8.0. [Are anonymous pipes (not 
    file-based psuedo-pipes) supported at all in the Mac or Windows (especially 
    NT) ports?]

    If the command doesn't end in an "&", bgexec now returns the output of 
    the command. 

    Fixed memory overwrite errors due to the way cleanups were triggered.
    
 5. bltdebug 

    Bltdebug now lets you selectively trace procedures.

 6. Drag&drop interface improved.

 7. winop

    New "snap" operation lets you take a snapshot of a Tk widget and
    saves it in a photo image.  You can then write the image out as
    as ppm (possibly gif) file, etc.

	image create photo "fred"
        winop snap . fred

	fred write "fred.ppm"

What's incompatibile with releases prior to BLT 2.3?

 1. Resource names and classes have changed in the graph and barchart widgets.
    Old names and classes won't work. 

	# won't work anymore
	option add *elemLineWidth 2	

	# change this to
	option add *Element.LineWidth 2

 2. Marker and element -mapx and -mapy options no longer take "both" as
    a value.  You can't automatically have two X or Y axes mirror each other
    anymore.  

 3. Element -active* options have been replaced.

    They are replaced by the "-activepen penName" option.  For barcharts
    this defaults to "activeBar", for graphs "activeLine".  These pens 
    are created automatically for you.  This means that all elements will
    by default, share the same pen.  So if you change the configuration 
    options of "activeLine" all the rest of the elements will see it 
    (which is generally what you want).

	# Old: 
	.g element create "fred" -activecolor blue2 -activefill blue4

	# New:
	.g pen configure "activeLine" -color blue2 -fill blue4


 4. Vector C API has changed (ouch).  You now get your hands on the actual
    memory for the vector.  

    /* OLD */
	Blt_Vector vector;
	double x[50];

	Blt_CreateVector(interp, "fred", 0, &vector);
	Blt_GetVector(interp, "fred", &vector);
	printf("vector size is %d\n", vector.numValues);

	vector.valueArr = x;
	vector.arraySize = vector.numValues = 50;
	Blt_ResetVector(interp, &vector, TCL_VOLATILE);

    /* NEW */
	Blt_Vector *vecPtr;
	double x[50];

	Blt_CreateVector(interp, "fred", 50, &vecPtr);
	Blt_GetVector(interp, "fred", &vecPtr);
	printf("vector size is %d\n", vecPtr->numValues);

	Blt_ResetVector(vecPtr, x, 50, 50, TCL_VOLATILE);

    Before the vector's fields were copied into the Blt_Vector structure that
    you passed in as an argument.  But since the array of doubles is shared, 
    the copying was little more than a facade, since it really didn't provide 
    any safety.  

 5. "blt_versions" array replaced by the scalar "blt_version" variable.
    You can check only the version number of BLT itself now.

 6. Future change. The "-mapped" options throughout the graph will be removed.  
    The various "-map*" options were getting confusing.  Use the new "-hide" 
    option instead.  

	# Works for now.
	.graph legend configure -mapped no

	# Instead use this.
	.graph legend configure -hide yes    
 
 7. Future change.  Vectors will, by default, NOT create and use array variables. 
    You'll need to set the "-variable" switch or use the "variable" operation.

	# Works for now
	vector x
	set x(++end) 1.0

	# Instead use this. 
	vector -variable x x
	set x(++end) 1.0

	# Or use this.
	vector x
	x variable x
	set x(++end) 1.0

   Of course you don't need to use the same name for the variable as the vector.

When will BLT work with Tcl 8.0?

  It's kind-of working with the beta right now.  I've just started looking 
  at the 8.0 features.  Namespace support mostly works. The isn't any
  documentation yet and the Tcl API doesn't appear as complete as [incr Tcl]'s.
  Since Tcl/Tk 8.0 is still solidifying (purify isn't very happy with the beta),
  a TclObj-full version of BLT won't happen immediately.  
  
  There are few areas that need fixing.  

   o bgexec (fixed for Tk 4.2) hopefully will work with 8.0.  
     My own Unix-only version of Blt_CreatePipeline is the current bandaid.  

   o The new font mechanisms mean that any code using XFontStruct is broken. 
     PostScript generation works with X fonts, but Windows is a guess.
 
   o The tiled versions of the Tk widgets may or may not be supported.

When will the so-called "official" BLT work with Windows?  

  It's on my ever-sliding schedule. Fortunately, much of the work (if not
  all) has already been done by Gordon Chaffee and Robin Becker. Many thanks
  to the both of them for their fantastic efforts.  

  My goal is to get "busy" and "bgexec" (at least for NT) working too.
   
When will...?

  In general, I can't answer the "When will" questions, mostly out of 
  embarassment.  My estimates of when new features and releases will
  occur usually turn out to be way way off.  

What does BLT stand for?

  Whatever you want it to.

--gah
