Overview of GEF v05

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: 5/30/97.

Section 0. Copyright

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.
Simple enough for college students to learn and use in 10 weeks.

I think it would be really interesting to organanize a "virtual software development team" over the internet so that: (1) I don't have to do all the coding myself, (2) the final framework is tempered by actual application, (3) we all get experience in distributed development, (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 of the GEF home page). 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 release the mouse button 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 a DiagramElement. 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 SelectionHandles and SelectionBox can be reused.

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 code does not consistantly follow all of these rules yet, but it will.

Each file starts with some header info: file, classes in this file, original author's email address, and version control info.

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 package-name-only style. (Note: This means that if you make a zip file for use in your CLASSPATH, you must use a version of the zip tool that includes directory entries.)

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 with "get" or "set" prepended. For example: _lineWidth, setLineWidth(), and getLineWidth().

In general, write short code when possible.

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.

Indicate places of future modifications with "// Needs-More-Work: reason"

Name all classes with an initial uppercase letter, and all variables and methods with a lowercase one. I use the allTogetherWithCaps naming style. Name static variables with an underscore and an inital capital letter, e.g., _PossibleLanguages. Name constants with all upper case and underscores, e.g., GRIP_MARGIN. The constants that are used to identify properties of DiagramElements are named with a leading "p", e.g., pLINE_WIDTH.

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).

The file uci/docs/features.html lists out all features that are supported by GEF. This is the closest thing that GEF has to a requirements document. Each feature is marked with an html anchor at names the feature. Javadoc comments on code that implements a given feature should include a hyperlink back to the proper anchor(s).
There is a list of bugs in uci/doc/bugs.html. Each bug is marked with an html archor that names the bug. Javadocs for code that contains a bug, fixes a bug, or works around a bug should have a hyperlink back to the proper anchor(s).
When in doubt, follow Sun java style conventions.

Section 5. Contact Information

Please direct any questions or comments to jrobbins@ics.uci.edu. The Graph Editing Framework home page is http://www.ics.uci.edu/~jrobbins/GraphEditingFramework.html. The mailing list gef-users is for people using GEF on their own projects. Typical messges are questions, suggestions, and announcements of new versions. Message volume on this list is quite low, and I never give out information about who is on the list. See the GEF home page for info on adding yourself to the mailing list.