-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
-*-*-*- Announcing The Release Of Version 2.2 of Garnet -*-*-*-*-*-*-
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
The primary change for this release is BETTER PERFORMANCE. The lowest
level of Garnet is now about FIVE TIMES FASTER, and we expect that all
user applications will be at least TWO to THREE TIMES FASTER! You
should really notice this! We have also added a number of new
features.
FTP directions for the new version follow the list of changes.
In summary, the primary changes are:
* Better Performance (see above).
* Type-Checking - Type-checking is now performed on most user-settable
slots in the pre-defined Garnet objects. So if you accidently set the
:left of a rectangle to be something other than an integer, Garnet
will generate a continuable error, with a thorough description of the
offending slot and value. Users can impose type restrictions on their
own slots, using new KR functions.
* Multifont-Text - The multifont object has been enhanced with several
new features: automatic indentation when lisp code is used as the
string; support for color and marks; hypertext-like imbedding of other
Garnet objects in the string; many new editing commands (like
^-shift-B to toggle bold font) to make typing strings easier; support
for drag-through selection by the multifont-text-interactor; and a new
slot in the multifont interactors called :after-cursor-moves-func
which may contain a function to be executed whenever the mouse is
moved in a multifont object.
* New opal:text - The opal:text object has been reimplemented to
handle multiple lines and cursors. References to the old
opal:cursor-text, opal:multi-text, and opal:cursor-multi-text objects
should be converted to opal:text references.
* New Aggrelists - The strategy for laying out aggrelists has been
completely rewritten. Instead of relying on formulas for positioning,
aggrelist components are now layed out procedurally during update.
The opal:notice-items-changed method should need to be called much
less often, since the work that used to be done in that method is now
done automatically when you update the window containing the
aggrelist.
* Debugging Tool - There is a powerful new tool called the Inspector
which allows you to examine and change slot values of your objects
without typing into the lisp listener. This tool can be invoked by
hitting the HELP key while the mouse is positioned above the object to
be examined.
* Gilt - The Gilt Interface builder has been significantly rewritten,
and made more robust. The standard and Motif versions have been
unified, so that there is now only one Gilt that includes both sets of
gadgets. The new version includes all of the pop-up gadgets, like
menubars and option-buttons.
* More Support - Garnet now runs on LispWorks and CLISP platforms.
The secondary changes are:
GLOBAL:
* A standardized declaration syntax has been created for the
definition of special slots in Garnet schemas. Previously, various
syntaxes were used for values of the slots :constant, :maybe-constant,
:update-slots, :ignored-slots, :local-only-slots, and :sorted-slots.
Now these special slots (and several new ones) can be defined using
the new :DECLARE keyword in the create-instance call.
* All objects now contain a list of slots that are user-settable in
their :parameters slot. For example, the opal:rectangle's parameters
list includes :left, :top, and :line-style, along with other slots
that determine its graphical appearance. The parameters list is a
valuable data resource for objects like the gg:prop-sheet, which allow
the user to change the value of certain slots in an object.
* The functions garnet-load and garnet-compile now look up their
prefix parameters in an expandable association list. You can add your
own prefixes and pathnames to this alist, so that the functions can be
used for your own directories.
* There is a new variable in garnet-loader.lisp that sets the
optimization flags for lisp, so that your compiled Garnet binaries
will be as fast as possible.
KR:
* The macro gv can now be used at the top-level, where previously it
was only allowed inside of formulas. Gv at the top-level now acts
like g-value, so novice users only need to learn about gv. G-value
can still be used inside of formulas when the user does not want to
establish a dependency on a referenced slot.
* The macro s-value can now take multiple slots in its argument list,
like g-value and gv have always supported.
* You can now store "meta-information" in formulas. This new feature
allows formulas to be thought of more like schemas, with slots of the
formula holding information in slots. Meta-information could also be
thought of as different "views" of the formula, where the cached value
of the formula is one particular view. The lambda expression
associated with a formula is an example of meta-information.
* The function ps, used for printing the slots and values of schemas,
now supports the printing of slot types. Array values are now
abridged when they are printed with ps, so that very large arrays are
not printed in their entirety. Also, ps now returns the value of the
schema that it was given to print, instead of just returning NIL.
* A new reader macro for #k has been provided, so that lisp can read the
#k<...> syntax printed by some Garnet functions (like ps).
The new #f reader macro allows you to abbreviate calls to
(o-formula (...)) with #f(...).
* A variety of bugs in KR have been fixed in this version.
OPAL:
* All Opal prototypes have a new :parameters slot that indicates the
user-settable slots for the object.
* The PS module for generating PostScript files from Garnet windows
has been made more robust, and many limitations of the previous
version have been eliminated. The function opal:make-ps-file can now
put two types of simulated window-manager frames around your rendered
images, and can print pixmaps in full color.
* Several new features have been added concerning cursors of windows.
Normally the cursor, also called the pointer, is in the shape of an
arrow when it is over a Garnet window. Several new functions have
been provided that make it easier to change the cursor of Garnet
windows. One function temporarily makes the cursor into the shape of
an hourglass, which can be useful when an application is performing a
long computation.
* A "quarantine slot" now exists in Garnet windows. If there was a
crash during the last update, then the window will stop being updated
automatically along with the other Garnet windows, until you can fix
the problem and update the window successfully. This should alleviate
the problem of being thrown endlessly into the debugger while trying
to figure out what's going wrong.
* The window prototype is no longer exported from Opal, and should not
be referenced unless absolutely necessary. Creating instances of
opal::window instead of inter:interactor-window is strongly
discouraged. The inter:interactor-window should be the window
prototype referenced by user programs.
* Window reparenting has been made more flexible, so that the :parent of
a window can be changed after it has been created.
* The function opal:update-all, which calls opal:update on all
existing Garnet windows, has been given a new total-p parameter, so that
you can do a total update on all Garnet windows.
* Internal functions that use the :hit-threshold slot have been
reimplemented to conform to their documented specifications. Objects that
rely on the :hit-threshold and :select-outline-only slots may be
affected by this change.
* The new opal:cursor-font object is an instance of
opal:font-from-file. Regular text strings can be printed in this
font, but its primary use is for changing the cursors of Garnet
windows by indexing into the font. This is the font used by the
window manager for its own cursor shapes.
* Several lighter shades of the Motif colors have been added (e.g.,
opal:motif-light-blue) along with their corresponding filling-styles.
It should be easier to read text against these lighter backgrounds.
* Three utility functions have been added to Opal. Opal:shell-exec is
used to execute Unix commands in a shell from lisp. Opal:make-image is
used to save an image of the current lisp session. Opal:directory-p
takes a pathname and returns T if it is a valid directory.
* Update-slots of graphical objects can no longer be changed just by editing
the value of the :update-slots list. As a consequence of optimizing the
system, there is now a function that must be called to add or
remove update-slots from an object.
* Opal now properly handles the screen parameter of the DISPLAY
environment variable.
* You can now stack fast redraw objects of all three types --
:rectangle, :redraw, and T.
INTERACTORS:
* Keyboard "accelerators" are now provided that allow you to attach
functions to specific keyboard keys. Some default accelerators are
bound that will raise, lower, or destroy a window when the appropriate
key sequence is typed.
* Entering and leaving a window with the mouse can now be detected as
an event. You can turn this feature on and off for individual
windows.
* The Agate gesture trainer has been reimplemented, and has a new
format for gesture transcripts.
* The text editing interactors now automatically stop editing the
current string whenever the mouse is pressed OUTSIDE the string. One
implication of this feature is that you will typically not have to
type RETURN before hitting the OK button, since the down press on the
OK button will stop editing and still operate the OK button.
* Some new features have been provided with the standard Interactors
debugging functions that should make debugging Interactors easier.
* A new scheme for controling the priority of interactors has been
implemented, through the :sorted-interactors slot of priority levels.
Now you can assign your interactors numerical rankings, corresponding
to their precedence over other interactors using the same priority
level.
* The :final-feedback-obj slot of menu and button-interactors can
contain a formula. This is useful for computing a different feedback
object depending on the currently selected object.
* A new verbose key has been added to the parameter list of
inter:Transcript-Events-From-File.
GADGETS:
* All gadget prototypes have a new :parameters slot that contains a
list of all the user-settable slots in the gadgets.
* A collection of editing functions has been provided in the
standard-edit module (in the garnet-gadgets package). This module
works in conjunction with the gg:Multi-Graphics-Selection gadget to
implement many standard editing routines such as cut, copy, and paste.
Now users can share the same editing routines that are used by
GarnetDraw, Gilt, and Marquise.
* Two new gadgets called gg:MouseLine and gg:MouseLinePopup are used
to display help strings when the mouse is is held over a particular
object. They are analogous to the ``Mouse Documentation Line'' on
Symbolics Lisp machines, and the ``Balloon Help'' feature of the
Macintosh System 7.
* There have been extensive changes to the gg:Prop-Sheet-For-Obj
gadget that allow it to use the new :parameters and type information
in Garnet objects.
* A new gadget called gg:Motif-Prop-Sheet-For-Obj-With-Done is similar
to the gg:Motif-Prop-Sheet-For-Obj-With-OK gadget, but with a "Done"
button.
* A new gadget, called the gg:Popup-Menu-Button, is a combination of a
button and a popup menu. The menu appears when you press the button,
and the menu goes away when you select an item from it.
* The gg:motif-menu has been enhanced to allow variable-width fonts
for the menu items. Previously, the gadget could not underline the
correct accelerator character in a menu item when the font was
variable-width.
* The new gg:motif-menubar is a Motif version of the standard
gg:menubar gadget. The interface is similar to the old menubar,
though it is not identical.
* Menubars have been made more robust. Previous implementations were
rather fragile, and required strict adherence to the examples provided
in the manual. Users should find the new implementations to be less
fragile.
* The new gg:motif-trill-device gadget is a Motif version of the
standard gg:trill-device gadget. The interface is virtually identical
to the old gadget.
* The polyline-creator gadget now supports polyline EDITING. Calling
the new function gg:toggle-polyline-handles on a polyline will display
selection handles at all points of the polyline, allowing the user to
drag the points. Adding and removing points of the polyline are also
supported.
* The standard and Motif versions of the save- and load-gadget have
been made more robust, and several new features have been added.
* Four new functions are provided which check user input for errors,
and raise an error-gadget if an error is found. These functions are
analogous to the less portable ignore-errors function.
* An :item-to-string-function slot has been added to the gg:menu
gadget.
* The slots :format-string and :enum-format-string have been added to
the gg:gauge and gg:motif-gauge gadgets.
DEBUGGING:
* New functions will perform various actions (like printing
notification messages, or going into the debugger) whenever particular
slots are set. These functions are useful when you want to know who
is setting a particular slot.
* The function gd:look-inter has been fixed, and can be used to print
useful information about interactors, including all the interactors
that work on a particular Opal object.
GILT:
* A new extension of Gilt called the Value-Control module has been
written that makes it easy to define constraints among the :value
slots of the gadgets in the work-window. An analogous Enable-Control
module allows you to control when gadgets are enabled and disabled
(active or "grayed-out"). This should make the creation of dialog
boxes significantly easier.
* Output from the GarnetDraw application can now be read into Gilt.
DEMOS:
* The Demos-Controller application, which is a nice interface for
bringing up the other demos, now features the new gg:mouseline gadget.
When you keep the mouse still over one of the x-buttons for about 2
seconds, a window will pop up with a short description of the
corresponding demo.
* The old demo-calculator has been replaced by the new
garnet-calculator. While this module contains the standard do-go
routine, the garnet-calculator is designed to be a self-contained
interface tool that can be part of a larger Garnet interface.
* GarnetDraw uses the new Standard Edit module from garnet-gadgets,
and can share "cut" and "pasted" objects with Gilt. The new version
uses the new motif-menubar gadget with keyboard accelerators, and
supports the new polyline editing feature.
* Demo-Multifont uses the new motif-menubar gadget with accelerators,
and demonstrates the new, improved keyboard editing commands for
multifont-text. A menubar selection allows you to toggle the new
lisp-mode feature of multifont, for automatic indentation of lisp
code.
* The old Demo-Circle has been renamed Demo-Virtual-Agg, and still
shows a window full of overlapping circles created with an
opal:virtual-aggregate. Demo-Pixmap still shows an example of a
two-dimensional, non-overlapping virtual-aggregate.
LAPIDARY:
* Several new operations are supported in Lapidary, including the
ability to supply multiple feedback objects for interactors, and a
self-contained version of the Box and Line Constraint dialog boxes
that can be used outside of Lapidary. A full set of documentation for
Lapidary is pending.
* A new self-contained version of the Box and Line Constraint dialog boxes
can be used outside of Lapidary.
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
Instructions for Retrieving the Garnet Software
October 15, 1993
V2.2 RELEASE
These instructions are for the official release of version 2.2 of Garnet.
The following assumes you run Unix and can FTP from CMU. This is the README
file for retrieving and compiling Garnet. There is another README file
in the doc directory that explains how to print the Garnet manual.
The Garnet manual has been completely revised for version 2.2, and you can
retrieve it by following the instructions below. There is also a change
document that accompanies the manual, which describes all the changes that
have been put in since the 2.1 release. If you cannot print out the
documentation, we will mail you a hardcopy if you send a check for $25 (US)
made out to "Carnegie Mellon University" to:
Brad A. Myers
School of Computer Science
Carnegie Mellon University
5000 Forbes Avenue
Pittsburgh, PA 15213-3890
If you have trouble printing the manuals, some people have reported
that it works better to change the top line of each postscript file from
%!PS-Adobe-2.0
to be just
%!
Note: There is an internet bulletin board for discussing Garnet,
called comp.windows.garnet. If you cannot access that, then please
send mail to to ······@cs.cmu.edu or ··············@cs.cmu.edu to
be added to the mailing list (which contains the same messages as the
bboard). To send mail to the Garnet maintainers, send to
···········@cs.cmu.edu. Posting to the bboard or sending mail to
············@cs.cmu.edu will send the message to all garnet users all
over the world. All administrative questions about the mailing list should
be sent to ··············@cs.cmu.edu.
If you are running Garnet from CMU, or if you have access to AFS, you
can access Garnet directly on the afs servers. The official release of
Garnet is stored in
/afs/cs.cmu.edu/project/garnet/src
/afs/cs.cmu.edu/project/garnet/lib
We are keeping binaries of the official version. The binaries
are in different subdirectories, depending on what your machine type
you have. The new version of Garnet-Loader will try to choose the
correct binary format. If you are using a Sparc Station to run
Allegro, CMUCL, or Lucid, or you are using a DECstation to run
Allegro, or you are using an HP to run Lucid, then you can load garnet
with
(load "/afs/cs.cmu.edu/project/garnet/garnet-loader")
If it cannot find a binary to load, then it will let you know. Please
contact ······@cs.cmu.edu and we might maintain a binary for you.
For non-CMU users, or people with other types of machines and/or lisps, you
will need to FTP the software and compile it yourself. The Garnet software
and documentation takes about 23 megabytes of disk space:
Source code: 6 megabytes
Binaries (actual size depends on your lisp): about 10 megabytes
Lib: 0.5 megabytes
Documentation: 6 megabytes
Therefore, you first need to find a machine with enough room on the
disk, and then create a directory called garnet wherever you want the
system to be:
% mkdir garnet
(If you already have a copy of Garnet, you might want to move the old contents
of the garnet directory somewhere, in case you need to go back. Otherwise,
delete all the contents of the garnet directory.)
Then, cd to the garnet directory.
% cd garnet
Now, ftp to a.gp.cs.cmu.edu (128.2.242.7). When asked to log in,
use "anonymous", and your name as the password.
% ftp a.gp.cs.cmu.edu
Connected to A.GP.CS.CMU.EDU.
220 A.GP.CS.CMU.EDU FTP server (Version 4.105 of 10-Jul-90 12:07) ready.
Name (a.gp.cs.cmu.edu:bam): anonymous
331 Guest login ok, send ········@node as password.
Password:
230 Filenames can not have '/..' in them.
Then change to the garnet directory (note the double garnet's) and use
binary transfer mode:
ftp> cd /usr/garnet/garnet
ftp> bin
The files have all been combined into TAR format files for your convenience.
These will create the appropriate sub-directories automatically. We
have both compressed and uncompressed versions. For the regular
versions, do the following:
ftp> get src.tar
ftp> get lib.tar
ftp> get doc.tar
To get the compressed version, do the following:
ftp> get src.tar.Z
ftp> get lib.tar.Z
ftp> get doc.tar.Z
Now you can quit FTP:
ftp> quit
If you got the compressed versions, you will need to uncompress them:
% uncompress src.tar.Z
% uncompress lib.tar.Z
% uncompress doc.tar.Z
Now, for each tar file, you will need to "untar" it, to get all the original
files:
% tar -xvf src.tar
% tar -xvf lib.tar
% tar -xvf doc.tar
This will create subdirectories will all the sources in them. At this point
you can delete the original tar files, which will free up a lot of disk space:
% rm *.tar
Now, copy the files garnet-loader.lisp, garnet-compiler.lisp,
garnet-prepare-compile.lisp, and garnet-after-compile from the src directory
into the garnet directory:
% cp src/garnet-* .
The file garnet-loader.lisp contains path names for all the parts of garnet.
You will now need to edit garnet-loader.lisp in an editor, and define the
location of your top-level Garnet directory. Comments in the file will direct
you on how to do this. At the top of the file are two variables you will need
to set: Your-Garnet-Pathname and Your-CLX-Pathname. These are used for all
the :external branches of the loader.
% emacs garnet-loader.lisp (or whatever editor you use)
NOTE: Some people running Sun Common Lisp or Lucid Common Lisp V4.0.1 on
Sun OS version 4.0 have reported a problem with the multiple process
code in Garnet. This is due to a bug in the Lisp. Upgrading to
version 4.0.2 or 4.1 of Lucid will fix this problem. Or else, please edit
the line in Garnet-Loader that sets launch-process-p to make it be NIL if
you are using the older version of Lucid on Suns. As described in the
manual and tour, you will then need to run (inter:main-event-loop)
explicitly at various times (but not when running the demos since they
run it for you).
NOTE: Some people using CMUCL have reported that they have to click several
times in a Garnet window before the click events are processed. This is due
to a bug in the CMUCL implementation of CLX. To fix the bug, load CLX into
your CMUCL image and recompile the file code/serve-event.lisp which can be
found in your CMUCL source files. If your lisp image already includes CLX
(i.e., you do not load CLX explicitly at the beginning of a Garnet session),
then you will have to reload the compiled file each time you start CMUCL.
Alternatively, you could make a new core image of CMUCL after loading the
compiled file, so that the fix is included every time you start lisp.
Lisp requires very large address spaces. We have found on many Unix
systems, that you need to expand the area that it is willing to give
to a process. The following commands work in many systems. Type
these commands to the C shell (csh). You might want to also put these
commands into your .cshrc file.
% unlimit datasize
% unlimit stacksize
Note: If you are running OpenWindows from Sun, you will need to add
the following line to your .Xdefaults file to make text input work
correctly:
OpenWindows.FocusLenience: True
To compile or load Garnet, the Unix environment variable DISPLAY
must be set correctly. Typically, the variable will be set with
something like unix:0.0. If you are running on a remote machine
different from the one you want the windows to appear on, you can do
something like:
setenv DISPLAY mymachine.garnet.cs.cmu.edu:0.0
The setenv call might be put in your .login file. You can check the
value of the DISPLAY variable (note it must be in all capitals), using
echo $DISPLAY
There is more information on the DISPLAY variable in the V2.2 full manual on
page 207.
Now, you will need to compile the Garnet source to make your own binaries.
This is achieved by loading the compiler scripts. There is more information
on compiling in the full V2.2 reference manual on page 12:
lisp> (load "garnet-prepare-compile")
lisp> (load "garnet-loader")
lisp> (load "garnet-compiler")
Now Garnet is all compiled and loaded, so you can run Garnet code. To
set up for the next time, however, it is best to quit lisp now, and
run a shell script to move all the binaries to the correct places. If
your sources are not in a directory named garnet/src or your binaries
should not be in a directory named garnet/bin, then you will need to
edit garnet-after-compile to set the directories. Also, if your
compiler produces binary files that do not have one of the following
extensions, then you need to edit the variable CompilerExtension in
garnet-after-compile: ".fasl", ".lbin", ".sbin", ",hbin", or ".sparcf".
Otherwise, you can just execute the file as it is supplied (note: this is
run from the shell, not from Lisp). You should be in the garnet directory.
% csh garnet-after-compile
Now you can start lisp again, and load Garnet:
lisp> (load "garnet-loader")
Full instructions for how to load and then run Garnet are in the
Garnet 2.2 Reference Manual on page 12.
You might now want to read the introductory material in the manual,
and then run the "tour" and read the "tutorial".
Thanks again for your interest in Garnet, and we hope that it works
well for you.