Features of GEF v05

This file prepared on 5/30/97.

This file lists features of GEF. This is useful in seeing what is there, and can be a good place to start before diving into the code. Also this feature list is useful for informal regression testing: if you add something new, check to make sure that all the old features still work.

Each feature is named with a unique string (e.g., "drag_object_constrained"). For most features there are comments in the source code that indicate where the feature manifests itself. Also there are references in the feature list to bugs in the bug list. You can follow the references by using a multi-file search command (e.g., grep) or you can use tags if you use emacs. A tag file with entries for bugs and features can be downloaded from the GEF web site.

Some features are planned but not implmented. These are left as projects for students or other users of this framework. These features are marked with "Needs-More-Work" here and in the code (if there is a marked place where something should be added).

Most of these features are user-visible, meaning that they are something that the user can see and use. Some of them are programmer features that only the programmer can see and use. Most of the programmer features are in section 7, and most of them are pervasive throughout the code, so there are not very many comments in the code that refer back to these features.

My intent was mainly to list features, and to describe them only a little bit. A detailed description of each feature would be useful for on-line help, but it would take a very long time to write and it would need to be updated as GEF changes. I have given brief comments only where the names of features are not enough to describe them.

Feature list overview:

  1. Basic Features
  2. Drawing Features
  3. Connected Graph Features
  4. Viewing Features
  5. Editing Features
  6. Other Features
  7. Programmer Features

Basic Features

FEATURE: editor_frame
The drawing editor can be placed in a Frame, and it will open its own Frame if needed.

FEATURE: editor_in_browser
The drawing editor can be placed in the browser window, or any place an AWT component can be placed.

FEATURE: cross_platform Needs-More-Work
GEF will compile and run under a wide range of operating systems and development tools. The main development tool used for GEF's development has been Sun's JDK on a Sparc and PC. It has also been compiled and tested on PC's under Windows95 with Symantec Cafe and VisualCafe, Microsoft J++, and Asymetrix Superceed. The current distrubition contains only source files and unix Makefiles, I should include project files for various IDEs.

2. Drawing Features

FEATURE: diagram_elements
A GEF diagram consists of DiagramElements that are contained and ordered within a Layer. DiagramElements can be individually manipulated.

FEATURE: basic_shapes
GEF provides DiagramElements for a wide range of graphics primitives.

FEATURE: basic_shapes_rect
FEATURE: basic_shapes_circle
FEATURE: basic_shapes_rounded_rect
FEATURE: basic_shapes_line
FEATURE: basic_shapes_text
FEATURE: basic_shapes_polygon
FEATURE: basic_shapes_ink
FEATURE: basic_shapes_image
FEATURE: basic_shapes_group Needs-More-Work
FigList implements groups of basic shapes, including other groups. Currently groups do not define properties that are shared by their elements, in the future I would like to be able to, e.g., resize a group and have its contents resize.

FEATURE: graphical_properties
Each DiagramElement has certain graphical properties such as location, size, colors, fonts, line widths, etc. These properties affect the appearance of the object and can be edited with a property sheet (see below). New subclasses can add their own properties.

FEATURE: graph_visualization
A GEF diagram can be used to display a connected graph. Nodes and arcs in the connected graph representation are associated with Perspectives and ArcPerspectives in the diagram. LayerPerspective point to a NetList that represents the connected graph, and it can filter it to display only those parts that are desired in a given context.

FEATURE: graph_visualization_nodes
Perspectives in the diagram visualize NetNodes in the NetList. Perspectives are basically a list of basic shapes that together define the look of a node. A single NetNode may be visualized by multiple Perspectives and multiple types of Perspectives.

FEATURE: graph_visualization_arcs
ArcPerspectives in the diagram visualize NetArcs in the NetList.

FEATURE: graph_visualization_ports
Some of the shapes in a Perspective may be used to visualize NetPorts.

3. Connected Graph Features

FEATURE: graph_representation Needs-More-Work
GEF supports a representation of connected graphs that consists of nodes, ports, and arcs. Ports are the connection points on nodes where arcs can be connected. Nodes, ports, and arcs can be defined in subclasses that add their own attributes and behavior. Currently I use one implementation of graphs, in the future I would like to define a set of interfaces and allow multiple representations (e.g., adjacency matrix). Also in the future I would like to support a node/arc representation of graphs, because ports are not useful for all applications.

FEATURE: graph_representation_nets Needs-More-Work
A NetList contains a collection of nodes. Ports and arcs are implicitly in the NetList because they are referenced from the nodes. In the future I would like to provide more graph-level operations such as finding the transitive closure of a graph or querying the graph to find elements based on their properties.

FEATURE: graph_representation_nodes
A NetNode represents a node in a graph. It contains a collection of ports.

FEATURE: graph_representation_ports
A NetPort represents a port on a node. It maintains a list of the arcs that are connected to that port.

FEATURE: graph_representation_arcs
A NetArc represents a relationship between two ports (possibly on the same node). I currently do no support multi-edges (e.g., three-way arcs).

4. Viewing Features

FEATURE: visual_updates
When the state of the graph or DiagramElement properties change, those changes will be reflected in the display(s). Redraws are not directly forced by changes, instead a RedrawManager accumulates damaged regions and then redraws them when convinent (e.g., when there are no input events pending) and when the time is right to achieve a specified frame-rate (number of screen updates per second).

FEATURE: layers
A diagram can consist of multiple layers with each layer containing part of the diagram. Layers can also be used to show non-editiable backgrounds (e.g., a grid) or user-interface feedback (e.g., a selection layer, although that is not the way selections are actually drawn now). (for related work see "Using the Multi-Layer Model for Bulding Interactive Graphical Applications", Fekete et. al. in Proc. of the User Interface Systems and Technologies Conference 1996, pg. 109 - 117.)

FEATURE: layers_menu Needs-More-Work
There should be a menu or list somewhere that lists all the layers in the current diagram and allows the user to focus input on one layer. This is not done yet.

FEATURE: layers_hidden Needs-More-Work
It should be possible to hide layers to help the user focus on certain aspects of the diagram. This is not done yet.

FEATURE: layers_dimmed Needs-More-Work
It should be possible to dim or gray-out layers to help the user focus on certain aspects of the diagram. This is not done yet.

FEATURE: layers_locked Needs-More-Work
It should be possible to lock layers to prevent the user from (acidentily modifing) certain aspects of the diagram. This is not done yet.

FEATURE: multiple_views
A given diagram can be viewed in multiple editors at the same time and changes made in one editor will be reflected in all editors. Each view is identical to the others, except for editor characteristics such as the current selection and zoom level.

FEATURE: multiple_perspectives
A given connected graph can be visualized in more than one diagram. Unlike views, graph perspectives are not all alike, each graph perspective selects a subgraph of the underlying graph to show.

FEATURE: redraw_minimal
Only areas of the screen that need to be redrawn are actually redrawn. When one DiagramElement changes state, only the area it occupies is redrawn. Actually it can be faster to redraw a somewhat larger area, but GEF does not redraw the whole diagram very often.

FEATURE: redraw_off_screen
Screen updates may optionally be done using an offscreen Image to produce flicker-free screen updates. This is the default behavior on most platforms.

FEATURE: adaptive_redraw Needs-More-Work
Different java platforms have very different performace characteristics. GEF dynamically adjusts is redraw policy and frame-rate to match the capability of a given java VM and the complexity of a given diagram. Currently, only the on-screen vs. off-screen policy decision is made automatically, adjusting the frame-rate is done through the preferences window. In the future I would like to introduce degraded drawing modes that draw DiagramElements very fast at lower quality, and then they can be redrawn when there is time to make them look nice. (for related work see http://www.cs.unm.edu/pad++).

FEATURE: zooming_panning Needs-More-Work
FEATURE: visual_grids
LayerGrid and LayerPolar are two examples of background layers that help people make nice looking diagrams. LayerPageBreaks gives a visual indication of where the drawing space will be divided into pages when printed.

FEATURE: viewable_properties
The properties of a DiagramElement can be viewed in a property sheet.

FEATURE: show_document Needs-More-Work
When GEF is run from an applet it can cause the browser to switch to another web page to show on-line help, etc. In the future I would also like to do this for java applications.

FEATURE: view_action_documentation
From the ExecuteActionWindow users can browse on-line help for actions listed in that window.

5. Editing Features

FEATURE: editing_modes
The GEF Editor can be in one of several input modes. Each mode interperts user input events and instanciates Actions for the Editor to execute. Modes can be combined on a ModeStack.

FEATURE: editing_modes_select
ModeSelect is the default mode to start in and to come back to when another mode finishes. It is near the bottom of the mode stack and is never popped off.

a. FEATURE: select_by_click Needs-More-Work
Clicking on a DiagramElement selects it. Shift-click is buggy.

b. FEATURE: select_by_area
Starting on the drawing background and dragging out an area with the mouse will select all DiagramElements in the rectangle.

c. FEATURE: select_by_tab_key
Pressing the tab key when zero or one DiagramElements are selected will select the first or next DiagramElement. Shift-tab selects the last/previous element. The ordering of DiagramElements is their back-to-front ordering.

d. FEATURE: select_all
A menu comand allows users to select all DiagramElements in the diagram.

e. FEATURE: select_inversion
A menu command allows users to select all DiagramElements that are not currently selected.

f. FEATURE: select_none
Clicking in the background area deselects all DiagramElements.

g. FEATURE: select_by_predicate Needs-More-Work
In the future I would like to define a dialog box that allows users to select all DiagramElements that fit certain criteria: e.g., select all rectangles that have line width of zero.

FEATURE: editing_modes_modify
When the user drags starting from a DiagramElement, the DiagramElement is continously modified until the user lets go.

a. FEATURE: drag_object
The user can move DiagramElements around by dragging them.

b. FEATURE: drag_object_constrained
Holding down the control key keeps the DiagramElements moving only vertically or only horizontally.

c. FEATURE: drag_handle
Dragging on a handle of a selected DiagramElement will change the state of the DiagramElement, e.g., resizing it.

d. FEATURE: drag_handle_constrained Needs-More-Work
In the future control-drag on a handle will resize DiagramElements in a constrained way.

e. FEATURE: minimum_modify_delta
Users sometimes accidentily mode DiagramElements a little bit when they try to select them. GEF defines a minimum movement delta, if the user moves less than this distance then the DiagramElement will not be modified. Once the mouse has moved more than this distance, all subsequent mouse movement modifies the DiagramElement.

FEATURE: editing_actions Needs-More-Work
Modifications to the diagram and DiagramElements are not performed directly by the Editor or by editor Modes. Instead Action objects are instanciated to represent what is to be done. Then the Editor executes those Actions and stores them for later undo/redo. Currently the intent is for all modifications to go through Actions, but there are several modifications that do not use actions.
FEATURE: undo_and_redo Needs-More-Work
In the future the Editor will store all Action instances in a stack so that they may be undone or redone.

FEATURE: macros Needs-More-Work
In the future users will be able to record a sequence of actions that can later be replayed, perhaps parameterized.

FEATURE: execute_action_window
The ExecuteActionWindow lists out several Actions that the user can execute by clicking on the action name. This allows programmers to add new Actions without having to work out where exactly in the interface to put it, and allows users to execute actions without having to know the right keystrokes or get into the proper mode. Users can also see on-line help for each Action from this list.
FEATURE: removing_objects
DiagramElements can be removed from a diagram by pressing delete, or backaspace, or by using a menu item.
FEATURE: removing_objects_delete
Deleting a DiagramElement just removes it from the diagram, it does not affect other DiagramElements in other diagrams.

FEATURE: removing_objects_dispose
Disposing a DiagramElement removes it from its diagram and also disposes of any underlying connected graph objects which may, in turn, delete other Perspectives or ArcPerspectives in other views. Currently the user always does ActionDispose, and ActionDelete is only listed in the ExecuteActionWindow as an example.
FEATURE: selections
DiagramElements can be selected to identify them as targets for menu commands and keystrokes that create and execute Actions.
FEATURE: selections_handles
Some selections have handles that can be dragged to change the state of a DiagramElement, e.g., resize it.

FEATURE: selections_box
Some selections do not have handles, they just indicate what is selected.
FEATURE: pick_objects
The user can click on any object to select it. Some objects can be hard to click on if they are small or consist only of thin lines. Picking an object actually determies if the mouse click was "near" a given object. When multiple DiagramElements exist at the point of a mouse click, the highest one in the back-to-front ordering is picked.

FEATURE: palettes
A GEF palette is an array of buttons that each perform an Action. This feature will probably be dropped in a future version.
FEATURE: palettes_sticky_buttons
Some palette buttons can be made to "stick down" so that the same action can be performed multiple times. This feature will be dropped when palettes are dropped.
FEATURE: snap_to_guide
A Guide is an object that changes points so that they line up better to make a nice looking diagram. For example, GuideGrid snaps points to a grid.

FEATURE: align_objects
DiagramElements can be aligned with each other or to the grid in various ways: tops, bottoms, lefts, rights, centers, horizontal centers, vertical centers, to grid.

FEATURE: reorder_objects needs-more-work
The back to front ordering of DiagramElements cn be changed in various ways: send to back, bring to front, send backward, send forward. In the future I would like to add Actions to reorder an object backward or forward such that it always causes a visible change, this means that it must continue to move forward or backward until it exchanges places with one/all DiagramElements that overlap it.

FEATURE: event_skipping
Not all user input events are equally important. For example, one mouse move is not very important if it is followed immeadiately by another mouse move. The GEF Editor speeds up event processing by skipping unimportant events.

FEATURE: editable_properties
The properties of a DiagramElement can be edited in a property sheet.

FEATURE: property_sheet Needs-More-Work
GEF provides a property sheet window to display and edit the properties of the currently selected DiagramElement. In the future I would like to handle multiple selections
FEATURE: property_sheet_editors
Each row in the property sheet window displays one property in a way that is appropriate for that type of property. For example, boolean properties are shown/edited with a checkbox.
a.
FEATURE: rectangle_editor Needs-More-Work
b.
FEATURE: color_picker
FEATURE: property_sheet_auto_apply
When the auto-apply checkbox is set, each change to the property sheet fields immeadiatly effects the selected DiagramElement. If auto-apply is not set, then changes accumulate and are all applied when the user clicks the Apply button.

FEATURE: property_sheet_revert
When auto-apply is not set and there are pending changes, the Revert button cancels all pending changes.

FEATURE: property_sheet_universe
When DiagramElements are added to a diagram they are also added to a list of all DiagramElements that is used for a pop-up menu in the property sheet. Selecting an item in the property sheet's universe menu will show/edit the properties of that object (without selecting it in the editor). This is useful when some objects are hard to select with the mouse.
FEATURE: locked_objects
DiagramElements can be locked which means that they cannot be edited in the editor, although they can still be modified via the property sheet.

FEATURE: replicate_objects Needs-More-Work
In the future I would like to implement a replicate command that makes many copies of a DiagramElement with each copy transfomed a little bit.

FEATURE: nudge_objects
Sometimes users want objects to almost (but not quite) line up with each other, or they want to position an object at a specific place regardless of the Guide. By using the arrow keys users can move objects just a little bit.

FEATURE: default_initial_size
When creating new basic shapes users sometimes make very small shapes by accidentilly clicking the mouse. Also, it is common for users to want to create several shapes of the same size. In GEF a single click when creating a Fig will give it the same size as the last Fig that was created.

6. Other Features

FEATURE: load_and_save Needs-More-Work
Diagrams can be saved and loaded using Sun's ObjectSerialization library, which is part of JDK1.1. In the future I would like to support other file formats.

FEATURE: printing Needs-More-Work
Diagrams can be printed under JDK1.1. In the furture I would like to support multi-page printing, currently I only print the page nearest the origin.

FEATURE: printing_config
There are several configuration options that can be set via the Preferences dialog box, e.g., should background layers like LayerGrid be printed?

FEATURE: preferences
GEF provides a preferences dialog box that allows users to specify various preferences.

7. Programmer Features

FEATURE: few_basic_concepts
GEF is implemented with only a few basic concepts that are implemented in clusters of classes. The basic concepts are: Editor, DiagramElement, Layer, Mode, Action, and Selection.

FEATURE: standard_naming_conventions
I have tried to use naming conventions that are like that used in java books and the Sun java code. For example, access methods are named getXXX and setXXX.

FEATURE: well_documented_code Needs-More-Work
I have tried to write javadoc comments for every class and most variables and functions. This takes a lot of time and is always incomplete. In the future I would like to see more invative uses of comments such as javadoc comments that include images, animated GIFs, or even applets. Also I would like to define better links between the requirements (basically this feature list) and the code. Also I would liket to document (and possibly publish) the design patterns that are used in this framework.

FEATURE: ten_week_learn_and_use Needs-More-Work
I would like GEF to be small enough and simple enough for college undergraduates to use in a 10 week course (including learning the java language and doing something useful with GEF). This has not been well tested or measureed, although I know of severak university students who have used GEF for class projects. In the future I may decide to split GEF into "GEF Lite" and "GEF Pro".

FEATURE: adaptive_performance Needs-More-Work
Java platforms vary in speed. I would like GEF to be useable on the slowest platforms and make use of the additional power of faster platforms.

FEATURE: extensible_framework
I have tired to design GEF so that new features can be added by adding new code in subclasses, rather than having to modify the source code that I distribute. People who are extending GEF should try to put their code in their own package, and try to minimize modifications to classes in uci.graphedit.

FEATURE: integration_with_exising_code
GEF can be used to build a new application starting from scratch, or it can be used to add a graphical interface to an existing application. Using GEF is easiest if you add attributes to subclasses of GEF classes, but if you already have classes in your own class hierarchy, they you must use delegation instead of subclassing. There are places in GEF that are intended for delegation, e.g., the _owner attribute of DiagramElements.

FEATURE: scalable_to_large_documents Needs-More-Work
Ideally GEF will handle large diagrams well. Currently most of the algorithms for picking, drawing, etc. are linear in the size of the diagram. I know this can be improved by using a spacial data structure (e.g., a quad-tree), but I don't know when I'll get to it. Loading and saving can take a long time. I think customization is key to scalability, and end-user customization is very limited right now.

FEATURE: easy_to_navigate_code
I have tried to make the GEF source code easy to browse by following careful naming conventions, providing cross-references, and examples.

FEATURE: robust_code Needs-More-Work
Error handling in GEF is generally inadequit and needs to be improved. However there are specific areas where exceptions are caught, e.g., when an Action is executed in the editor. Framework support for robust code is key to allowing contributions from a wide range of people. Security is also important, GEF may evolve to take on more browser-like features and run Actions, Modes, etc under different security managers.

FEATURE: integrated_debugging_support Needs-More-Work
Ideally the framework would help people debug code that they are adding to the framework. There is some support for that in the form of exception handling that prints out diagnostics, code to draw visual indications of how and when redraws are being done, and debugging println's that are guarded by checks for command line args (via the -D option to java).

FEATURE: consistent_style Needs-More-Work
Consistent coding style makes the code easier to read, work with, and make global changes to. GEF's coding style has changed over the last few releases and is still not entirely consistent.

FEATURE: cross_development_environments
GEF compiles and runs under JDK 1.0.2 and JDK 1.1 on Solaris and Windows95. I compiled it under a few different compilers on the PC. Different Java VM's behaive a little differently, and I have put in some logic to try to work around variations in some cases (e.g., flicker free redraws don't work under JDK 1.0.2 on a PC, so that option is turned off by default when you run on that platform). Also, some Java 1.1 constructs will not even compile under JDK 1.0.2, so I have made limited use of the unix m4 utility to do conditional compilation. I am distributing two versions of the source, one preprocessed for JDK1.0.2, and one preprocessed for JDK1.1. Each version can generate the other if you have access to the m4 utility.