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!