🚀 go-pugleaf

A few weeks ago I looked through the anonymous ftp account on 
interviews.stanford.edu, hoping to find some example programs that I could 
study, to help me as I try to learn InterViews.  I was pleased to find 

       "/pub/contrib/For_Neophytes/examples.tar.Z"

and further pleased when I found the small but non-trivial program,
cedit.c.  This program displays a colored patch, three scrollbars (one
for each of the primary colors), and three text fields.  Moving the
sliders changes the value of the related primary color constituent;
the current values are displayed in the text fields, and in the color
patch itself.  At 286 lines, it seemed an excellent candidate to study,
to learn from, and perhaps to enhance with new features.

I've spent about twenty hours on the program and, indeed, I've learned
a lot.  I've added a few things as well: a menu bar, and an object which
finds the best color name from Sun's /usr/openwin/lib/rgb.txt for any
particular value of the rgb triplet.  But I've been in turn confused,
outraged and depressed by the program.  It has no comments (none!) and
I think (though I may be dead wrong, novice that I am) that it has 
a fundamental design flaw.

So I'm posting this note to comp.windows.interviews with questions,
and a tenative offer of some volunteer labor from me.  I want to help
create a small library of carefully written, detailed and extravagantly
commented example programs that will make it easier for the neophyte to
learn InterViews.

Before proceeding, I wish to make clear that I have no axe to grind
with Dave Sternlicht or Mark Linton, who apparently wrote and advised
on (respectively) the cedit program.  I've received a lot from the
InterViews crowd, and these two in particular, and I've paid exactly
nothing.  I have no grounds to complain.  

But if I'm not off-base in my criticisms of this example program for
neophytes (and I hope the net will tell me if I am), and if there
*is* a general need for good tutorial programs for InterViews, then 
maybe others would like to join me in putting these together.

Down to specifics.   cedit defines three classes:

class Valuator: public Adjustable

	These objects don't appear on the screen, but they play
	a central role.  There's one for each primary color.  Their
	role seems to be to store the current value of a primary color
	and to provide a dispatch mechanism:  they receive messages
	from scrollbars, and they send messages to ValuatorView objects,
	and to the ColorViewer object.

class ValuatorView: public MonoGlyph, public Adjuster

	These objects, one for each color, are arranged in a left-to-right
	box just above the main window.  They display the current 
	numerical value of their primary color.

class ColorViewer: public Patch, public Adjuster

	There's only one of these objects, and it displays a rectangle
	whose color is determined by the values of the three Valuators.

Here -- to me -- is the rub.  The IV manual, section 7.5, says:

	"An adjustable is an object that handles requests to modify
	 its view.  An adjuster is an object that can make requests on
	 an adjustable."

When I first made and ran the program, and before I closely studied
the code, I reasoned that the large color patch would be an Adjustable
(or be a component of an Adjustable) and that the 3 scrollers would be
Adjustors. Upon receiving the adjust message, this object would
then update its view (the color patch) and the numerical readout.

But I was dumbfounded to see that the ColorViewer and the ValuatorView
were Adjusters, even though they don't "make requests on an adjustable"
as the manual says.

The best I can figure out is that the designer made them subclasses of
Adjuster in order to take advantage of the "update_all" message that
Adjustable::notify sends to all of its Adjusters.  So when a scrollbar is
moved, it sends a scroll_to message to the Valuator, which then informs
the ColorViewer and the ValuatorView (its "Adjusters") that it's changed.

But this requires that you abandon the commonsense view that an Adjustor
is an object that adjusts an Adjustable.

My question:  is this the best way to design this application?

If the answer is yes, then perhaps other neophytes may be interested
in my commented version of the original code.  This might save
them some of the confusion I've experienced.

If the answer is no, perhaps someone can give me some guidance about
a better design.  In turn, I'll be glad to work up the program according
to the suggestions I receive, and submit my work to comp.windows.interviews
when I'm done, again with the hope that the next neophyte will have an
easier time of it.  And if this seems generally useful, I'd be glad to
submit other tutorial-like programs in the coming months.  

I hope I haven't tread on any toes with what I've said.  I *do*
appreciate that the authors of contributed software are on tight
schedules, and have contributed a lot to the community.  They
certainly have contributed more than I have.  But I've long been
influenced by a comment made by Abelson and Sussman, in the Structure
and Interpretation of Computer Programs, that says (in paraphrase)
that a program should be written as much for the human reader as for
the computer.  Perhaps we can make InterViews more accessible by
developing example programs which read well?

 - Paul Shannon
   pshannon@nrao.edu