-*- text -*- $Id: CHANGED-V4,v 1.0 91/08/22 15:36:20 gnb Exp $

This document outlines the major changes since Version 4 of the
plotter widget set and gives some porting hints.

Let me start by outlining why I have had to do what I have done.  Then
I will describe what I have done, and how well it works.  Then I will
describe what I have not done, then include any conversion
experiences/gotchas that I have been sent.

Why I Did It.
-------------

When we first got the version 4 of the Plotter widget set, I was most
excited.  It did about 90% of what we needed.  There were a few
drawbacks, though:

1) It was written in ANSI C.  We use the gcc compiler for development,
   but policy says all installed/delivered products must be compiled
   with the system compiler.  Fair enough too; we don't have the
   resources to properly support gcc.  The additional problem was that
   gcc couldn't generate shared library code, and we expected to be
   using this code a lot, so wanted shared libraries.

2) It was strongly directed towards "engineering" graphics (i.e. real
   vs. real).  We need more "business" graphics (i.e. data vs date).
   There was not enough flexability in the axis code to enable
   labelling by dates, at least not enough to do things like tics at
   the start of each month....  This was the real killer in our
   business environment.

3) All our existing applications stored the application data as an
   array of structs.  The plotter expected a "tree" of arrays of
   doubles.  It would have been very hard and wasteful to maintain two
   copies of the data.  (Not easy to re-cast the applications either
   as the rest of our libraries assume the array-of-structs model).
   Again, FORTRAN-like thinking from engineers!  (I can talk - I'm an
   engineer myself!)

4) It wasn't clear to me how to link multiple instances of the graph
   into one application so that common axes shared the same scale,
   min, max etc.  (It may have been possible, but it wasn't very well
   documented).

5) The refresh/redraw code was a real mess, with policy and
   implementation being strewn amongst all classes in a fairly
   haphazard manner.  There was no well-specified interface between
   plotter and axis and plotter and plot.  This made making changes a
   very dificult task.  In fact, the redrawing code had huge holes in
   it.  Often no redraw would be done when it was needed but far more
   often many redraws, each with expensive layout and scale
   operations, were required to change one simple element of the graph.
   Hence the refresh and update had a very annoying flicker.

What I Did
----------

We have had some discussions on the bug-at mailinglist about the
redraw code and logic.  That was after I had hit problem 5) above in
the attempt to work out how to solve 2).  After a few comments and a
lot of thinking, I decided to have a go at implementing a new redraw
protocol, based on those discussions and a few principles outlines in
the redraw-protocol document.  One thing led to another, and the short
answer is I wound up rewriting most of the core of the widget set.

So I have more-or-less new versions of the plotter code and the axis
code, and slightly hacked versions of the plot widget, the postscript
and text code necessary to go with all this.  Rather than hack on the
existing xyplot widget, I wrote a very very simple lineplot widget
that conforms to the new redraw protocol as well as offers support for
the array-of-structs data model.  I have not touched the xyplot, the
barchart, the countour plot or any of the subclasses thereof.

In the course of this rewriting, I did the following things, some of
which may be considered gratuitous changes:

1) Make it compilable with either K&R C or ANSI C, including full
   prototypes in all header files and using the fully prototyped Xt
   headers.  Rather than the fairly verbose method of compiling
   prototypes used in the Xt headers, I used this arrangement (stolen
   from I don't remember where):

	/* This bit in each header file */
	#ifndef P
	# ifdef __STDC__
	#  define P(args) args
	# else
	#  define P(args) ()
	# endif 
	#endif 

	/* This is how header files delcare routines */
	extern int AtAxisWidth P((AtAxisObject));

	/* This is how static functions are declared in each c file */
	static void funtion P((String arg1, int arg2));
	static void function(arg1, arg2)
		String arg1;
		int arg2;
	{
		/* Code of function */
	}


   This means that every function is fully prototyped.  The result is
   that it all compiled "gcc -Wall", including X header prototypes,
   with no errors or warnings (in our setup, which declares almost the
   entire C library in the stdlib.h file).

2) Changed the names of the structure members from the existing style
   ("ticInterval") to that recommended in the Xt manual (sec 1.6.1)
   ("tic_interval").  Gratuitous change, but it helped in the
   conversion process!!

3) Used AtText's to do axis numbering instead of the original string +
   XFont stuff. For consitency rather than anything else.

4) Chopped out a lot of unused crud - an amaazing amount!
   Unfortunately, I probably chopped out some potentially-used crud,
   probably bvecause I didn't need it, didn't understand it or it was
   hard to convert.  All of which can be added back later if anyone is
   crying.

5) Implemented the new redraw protocol (and refined it quite a bit on
   the basis of the experience!).  All the logic for scaling, layout,
   drawing etc is collected in the one place, with clearly defined
   interfaces between objects.  It makes them all much easier to
   understand.  It is certainly _MUCH_ more efficient at redraws etc.

6) Changed parts of the interface to the plotter and the new LinePlot
   widget to use member functions rather than the SetValues stuff,
   mainly for the sort of things that have to be done in C anyway
   (i.e. pointers to functions and data).  This sort of change will
   mainly affect the plot widgets I haven't touched yet.

6) Used the region for handling exposure events to cut down on flicker.

7) Added a few new features, e.g. automatic horizontal sizing of the
   legend; more flexible handling of axis tics and labels, much more
   generalized axis handling.

8) Fixed a number of bugs/oversights, especially in the SetValues
   handling (most of the resources wouldn't force a redraw if they
   changed as the SetValues routines ignored them).

9) A registration function to register the relevent bits with WCL (the
   Widget creation Library -- see comp.sources.x Vol 11, Issues 13ff),
   and a new test program that is built using WCL.  This test routine
   can be very quickly changed and allows rapid testing of just about
   everything.  (It currently has 10 resources it can alter, adding
   new ones is very easy).

10) A new Imakefile for building shared libraries and the new test
    code, including strcasecmp for old C libs and the Wcl stuff.

11) Reformatted the whole code to use the one consistent coding style
    (K&R c-style from gnu emacs), naming schemes, etc.

12) Totally rethought the whole axis concept.  Now, there are four
    axes (X, X2, Y, Y2), each more or less identical.  The single axis
    class has been split into several classes, each of which does a
    specific job.  The autoscaling and endpoint decisions are now made
    by the axes, not the plotter.  The axes are no longer
    automatically created when the plotter is created, as there are
    many axis classes.  Instead, the application must the axis
    children then attach them to the parent plotter.  The whole
    concept of framed axes was ripped out of the plotter, and a new
    axis class created to do the same job.

13) Added an extra parameter to the AtTextCreate() and AtTextFormat()
    routines to specify an initial font style.  Hence all text objects
    now have a style resource as well as a size resource.

The re-implementation involved dropping a lot of crud for various
reasons, mainly on the basis that it is easier to add it back later
(and properly designed and implemented) if someone screams.

As such, it comes under a couple of headings:

1) Some features were dropped because they were badly thought out,
   didn't work, I couldn't understand what they were for or how they
   worked.  This includes the XtNforceSquare and XtNforceAspect
   resources, the floating axis code, and all the selection mechanism
   and mouse action routines.

2) Some features haven't been converted to the current version, mainly
   because I don't need them and haven't the resources to do the
   conversion (this has already taken up WAY too much of my time --- just
   ask my Boss!).  This included the Log axis code (which should go into
   a subclass of AtAxis), the XYPlot, XYErrorPlot and Contourplot classes
   (which would need a generalized version of the AtSPlot class to
   subclass from, but the Plotter and Axis code should handle it all OK),  

3) Some things were taken more-or-less unchanged, with the exception of
   being reformatted to be compilable with K&R C compilers.  This
   includes the AtFontFamily, and Scale code, and most of the
   PostScript code.  These retain the original MIT copyright.

4) Some things were modified to some small extent, either to fix bugs,
   add features or make compatible with the rest of the code.  These
   include the Text and AtTextPlot modules, as well as the AtPlot class.
   They retain the MIT copyright.

5) Some things were substantially modified, or re-written with constant
   and detailed references to the original code and algorithms.  This
   includes much of the Plotter and Axis code (most of which ended up in
   the AtAxisCore class).  These retain the MIT copyright and have a BBY
   copyright added.

6) A fair quantity of stuff was written from the ground up by me.  This
   comes with a BBY copyright that is the same as the MIT one (but with
   the name changed!)  This includes the AtSPlot, AtLinePlot, AtBarPlot,
   AtFrameAxis and AtLabelAxis classes, the test and sample programs, this
   document, and much of the implementation and design of the Plotter and
   AxisCore classes.


What I Have Not Implemented:
----------------------------

- The other plot widgets. This is pretty low on my list at this point
  due to a combination of the array vs. structure problem and the
  scientific vs business use.  I will be looking at the barchart
  fairly soon however.

- Log axis.  

(See also the "ToDo" file.

Some final points.
------------------

Coding styles/formatting: I have used the K&R c-style from emacs'
electric-c for all of the code.  The original was in some other
similar format.

IMnsHO the code has benefitted an awful lot from being under just one
hand for a while, as opposed to the somewhat organic,
undergrad-project status it seems to have had earlier.  I am actually
being paid to work on this, and will have resources to put in for the
next month or so, provided I can convince the Powers That Be that the
work I am doing is useful to us.  Given that, I am more than happy to
share the results of my labor with the world in one form or another;
especially if I can get help in return!

I await your wisdom, criticism, observations, praise, Nobel Prizes,
offers of help, etc.  Even flames!

Greg.

Gregory Bond
Burdett, Buckeridget & Young Ltd.
Melbourne, AUSTRALIA

gnb@bby.oz.au
