This file gives a brief overview of the structure and style of the
code in the UCI Graph Editing Framework.

This file was prepared on: 7/29/96.

CONTENTS:
	S0. Copyright
	S1. Vision.
	S2. Overall Architecture.
	S3. Class clusters and their relationships.
	S4. Coding Style
	S5. Next expected release date 8/19/96
	S6. History
	S7. Contact info

Section 0. COPYRIGHT

Copyright (c) 1995, 1996 Regents of the University of California.
All rights reserved.

This software was developed by the Arcadia project
at the University of California, Irvine.

Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are
duplicated in all such forms and that any documentation,
advertising materials, and other materials related to such
distribution and use acknowledge that the software was developed
by the University of California, Irvine.  The name of the
University may not be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.




Section 1. VISION

Basically, I want to have a nice, stable graph editing and
MacDraw-style graphics editing framework. I need that as a starting
point for a tool I am building for my Ph.D. research, and I think that
others need a framework like that as well.

Some of the goals of the framework are to support these features:
+ Full editing of unstructured graphics, so that it is possible to
  make nice looking diagrams.
+ Ease of use, so that people who are browsing the web can figure out
  what to do with my demos without having to read a lot of
  documentation.
+ Connected graph editing, because that is needed in my application.
+ Multiple, coordinated views, so that complex connected graphs can be
  visualized in different ways.
+ Easy integration with application specific code, so that people can
  put a graphical front end on their applications without rewriting
  everything around my framework.

I think it would be really interesting to organanize a "virtual
software development team" over the internet so that: (1) I dont have
to do all the coding myself, (2) the final framework is tempered by
actual application, (3) I get feedback from various people, (4) I get
in contact with professional developers for future collaboration, user
testing, and even job offers. As virtual team leader I promise to
integrate changes, run the project web page, suggest projects, and
avoid duplication of effort. I am especially interested in instructors
at universities who want to use this software as material for project
classes (see the history section). I have not yet worked out exactly
what the copyright terms will be for sumbitted code. I just don't want
to get anyone in trouble or discourage contributions.

The framework should promote the creation of good demos for the
www. That means that they should download quickly, look nice, have
enough features to look perfesional, and let the user get to the point
of the demo without fighting with a difficult interface.

More importantly, the framework should promote the creation of good
applications. It should have a rich set of basic features. It should
be easily customized to a given application. It should look nice and
be easy to use (or at least be like other applications).



Section 2. OVERALL ARCHITECTURE.

There are two main levels in the Graph Editing Framework (GEF)
representation: (1) the net level, and (2) the diagram level. The net
level holds nodes which are logical objects that may have application
specific data and behavior. The diagram level made up of
DiagramElements for structured and unstructured graphics that
visually depict the net and various annotations.

I expect that people will use the framework by extending it by adding
new classes. In Java the class is the most important unit of syntax,
version control, code distribution, and dynamic loading. I have tried
design the framework so that people never have to modify existing
code. I don't know if that is not the case yet, but hopefully it will
be.

The graph editor (in class Editor) is just a shell that dispatches
control to various other objects that do the actual drawing and
processing of input events. The supporting classes are in several
clusters described below.



Section 3. CLASS CLUSTERS.

+ Actions are classes that define a doIt()
method that performs some action in the editor. For example
ActionReorder handles the menu items 'Send to back', 'Bring to front',
etc.

+ Modes are modes of operation for the editor. They can potentially be
long term modes, for example preview mode vs. ray tracing mode. But so
far I have only done short term modes for selection, modification, and
creation of new objects. For example, when you drag an object around
the editor is in ModeModify, but when you let go the editor returns to
ModeSelect.

+ DiagramElements are drawable objects that can be shown and
manipulated in the editor. Figs (short for Figures) are basic drawing
elements such as lines and rectangles. Perspectives are more complex
objects that represent objects in the underlying net level
representation. 

+ Layers serve both to group DiagramElements into transparent overlays
(as in many high end drawing packages) and to manage redraw order and
find the objects under a given mouse point.

+ Selections are objects used by the editor when the user selects an
object. Selections are responsible for drawing handles and handling
dragging on handles. In the worst case a new kind of DiagramElement
will need a new kind of Selection, but usually there will be some
reuse. needs-more-work: I might introduce Handle objects for
individual handles, I am not sure.



Section 4. CODING STYLE.

I am including this section (1) so that anyone who modifies this code
can work toward the same style that I am tring to achieve throughout
the source code, (2) as a form of documentation so that you know what
you are reading. Unfortuantly, the does not consistantly follow all of
these rules yet, but it will.

1. Each file starts with some header info: file, classes in this file,
original authors name and email address, version control info.

2. I am using the import ...*; command to keep the code short. I
perfer to let name conflicts arrise so that I can catch them, rather
than always use explicit package.class names and end up with code that
cannot be changed to the class-name-only style.

3. All instance variables are private and their names begin with an
underscore. If the variable should be accessible then add public or
protected accessor methods with the same name as the variable without
the underscore (no "get" or "set" prefix).

4. In general, write short code when possible.

5. Use javadoc for each class, instance variable, and method. In
general do not put comments in the body of a method. If you are doing
something complex enough to need a comment, consider breaking it out
into its own commented method.

6. Indicate places of future modifications with
"// needs-more-work: reason"

7. Name all classes wuth an initial uppercase letter, and all
variables and methods with a lowercase one. I use the
allTogetherWithCaps naming style.

8. To emphasize clusters of classes I am using what I call the
binomial naming style (I am sure others have thought of this also):
The root class of the cluster has a short name (e.g., Layer), other
members of the cluster use that name as a prefix (e.g.,
LayerGrid). This makes many of the class name longer than they might
be normally (e.g., Grid would be shorter). But this provides a lot of
context without having to look at a class inheritance diagram. It is
also very nice when you have to look at an alphabetical list of
classes. I try to name class clusters so that they are not
lexigraphically close others (e.g., the Net cluster used to be named
Model, but that lexigraphically overlapped the Mode cluster).

9. When in doubt, follow sun java style conventions.



Section 5. NEXT EXPECTED RELEASE DATE.

I expect to release the second early experience version of this
software before 8/19/96. There will be several changes to the code
overall, including new features and a large number of global name
changes and change to the coding style. Also, I plan to write a lot of
documentation...

Since the release is fairly close and I expect to make major
changes. I am recomending that potential users of this framework only
examine the current version and perform small experiments. If you
start doing a lot of development using this version you will (at the
least) have to do many global search and replace operations on your
source code.

What I am really hoping users will do with this version is look at it,
think about what features they want or might implement themselves, and
give me feedback.


Section 6. HISTORY.

+ Spring 1996.

Jason Robbins suggests the contruction of a graph editing framework as
a project for teams in the ics125b software engineering project class
at UC Irvine. Jason acts as a customer for one team. That team
produces an intital working version and documentation. Features
include: connected graphs, unstructured graphics, commmand objects,
perspective editor, some load and save capabilities, multiple views,
rectilinear arcs.

+ Summer 1996.

Jason accepts the final version of the code and begins to reorganize
and improve its style and stucture. many bugs are fixed. Added
features include: layers, class preloader, mode and action objects,
flicker free redraw, text alignment. Jason uses thegraph editing
framework for its first application in his design environment
research. The UCI Graph Editing framework is announced. Over 20 people
from around teh globe request access to the source.

+ July 1996.

The first early experience version of the GEF is made availible on the
internet.



Section 7. CONTACT INFORMATION.

Please direct any questions or comments to jrobbins@ics.uci.edu.  You
might also check my home page http://www.ics.uci.edu/~jrobbins/ for
information about the (future) Graph Editing Framework home page,
mailing list, and updates.

jason!
