Notes on Picasso usage:

o Running demos
To run a few demos, try the following commands at the lisp prompt:

	(run-tool-named '("paper" "demo" . "tool"))
	(run-tool-named '("gallery" "tool"))

In the paper demo tool, you'll get an X error.  Use the command ``:el''
at the command line prompt to get things going again (see below for more
info on :el).

o Creating a new tool
To create a new tool, you must first create a directory for the tool.  Let's
suppose it's called ``amy-test''.

1) Make a directory called amy-test in ~picasso/lib/po:
	% mkdir  ~picasso/lib/po/amy-test
2) Copy tool, frame and form files from an existing tool.  It's a lot easier
   to edit existing code than create stuff from scratch.  I suggest you copy
   ~picasso/lib/po/gallery/{tool,frame,form} into ~picasso/lib/po/amy-test:
	% cp ~picasso/lib/po/gallery/{tool,frame,form} ~picasso/lib/po/amy-test

3) Edit the tool, frame and form.  Strip down the children in the form to
the minimum initially, and customize the menus.

o Debugging panels, dialogs and forms
Rarely are frames or forms bug-free when first created.  The picasso analog
to the compile-link-run debugging cycle of ordinary programming environments
is the clear-destroy-rerun cycle.  Suppose you create a tool as above.  To
run it, use the command:

<picasso> (run-po-named '("amy-test" "tool"))

When you find a bug, edit the tool file and write it.  Then use the command
``:ce'', followed by ``:da'', ``reset'' and finally ``run-po-named ...''
again.  The effect of the :ce command is to clear the picasso dictonary
out, which means your tool will be reloaded.  The effect of :da is to
destroy all the windows created by picasso on the screen.  The effect of
the :reset command is to reset lisp to the top level (this is documented
in Franz CL manual), and the effect of run-po-named is to reload an rerun
the tool.

Other commands that are useful in debugging:

	(setq tool (find-po-named '("amy-test" "tool")))

returns the CLOS object associated with the name passed.  In this example,
it returns the tool and sets the lisp symbol ``tool'' to this object.
Of course, it could be used to find the frame, or form, such as in

	(setq form (find-po-named '("amy-test" "form")))
	
Find-po-named will load in the definition if it is not already in memory.
The return value can then be used by a few inspection functions, such as:

	(pt tool)

Which prints out the window tree starting at the tool, and 

	(ppi form)

which ``pretty-prints'' the CLOS object ``form''.  Ppi can be used on
any CLOS object.  Finally, two other commands of interest are the :el
command and :prt commands.  A picasso application typically creates
all its windows, then enters a loop that waits for an event, then
figures out the window to handle the event, and sends a message to that
object describing the event.  This loop is called the ``event-loop''
in picasso, and the :el command starts up a new event-loop.  Finally,
:prt means ``pop-and-retry'' the last lisp form.  It, like :reset, is
described further in the Franz CL documentation.

For a large application, debugging can be a bit of a painful process.  This
is largely because a picasso application must be entirely reloaded before
it can be run, and this can take awhile.  In the early development stages,
therefore, we suggest that you comment out the declarations of panels and
dialogs so that they are not automatically loaded until the main tool, frame
and form is debugged to your satisfaction.  This prevents the panels and
dialogs from being loaded on startup, which can take some time.

When the form is satifactory, uncomment the dialogs and panels one at a
time, and debug them individually.  When debugging the dialogs and panels,
you can use ``call'' in combination with ``find-po-named'' to help
debug the panels.  For example, suppose I have a dialog called 
'("amy-test" "test" . "dialog"), and I have the tool, frame and form
that call this dialog loaded and mostly debugged.  Then to debug the dialog,
you could use the sequence:

	(setq d (find-po-named '("amy-test" "test" . "dialog")
			       :reload t :destroy-old t))
	(call d)

The :reload keyword forces the file to be reread, and the :destroy-old
keyword forces the old window to be destroyed.  This can be done as
many times as needed until the object looks right.  The same
procedure works well with panels.

o Exploration facilities
Since picasso is underdocumented at this time, the best way to find
out how something works is the ``RTFC'' method -- ``Read The Code''.
On the other hand, grovelling around the 30000 or so lines of code is
no picnic, even for the authors, so we created a few utilities to
aid this process.  First, in the ~picasso/src/toolkit and
~picasso/src/widgets directories, you can use two commands, ``refs'' and
``vit'' to look at the definitions of functions and methods.  For
example, the command

	% refs find-po-named

when run in the ~picasso/src/toolkit directory, prints out:

	find-po-named picasso/picasso-dict.cl

which indicates the function ``find-po-named'' is defined in the file
picasso/picasso-dict.cl.  The ``vit'' command enters vi positioned
at this point.  So, to view the code for find-po-named, cd to the
~picasso/src/toolkit directory and enter

	% vit find-po-named

If given a method name, such as ``clear'', these function list or
edit ALL the files where that method is defined.

A couple other pointers on documentation.  Geometry managers are not
documented at this point, so I suggest you look in the files
~picasso/src/toolkit/gm/*.cl for their usage.  The comments in these
files tell you how set the ``geom-spec'' slots of child windows to
get the layout correct.  Don't underestimate the importance of geometry
management;  if the geom-specs are set incorrectly, the child may not even
be displayed on the screen!  I suggest you start with rubber-gm, sinice
it's the easiest to understand, and then look at packed-gm and stacked-gm.

Finally, the ``widgets at an exhibition'' tool, defined in the files
~picasso/lib/po/gallery/*, contain bits of sample code to create
various widgets.  These can be used as starting points for making
other widgets.

