Easily present graphical data with JGraph

It's often necessary to display data in a graphical form. The JGraph project streamlines the process of presenting graphical data when working with Java.

JGraph is a small but fully functional Java component that facilitates the development of graphical network representations using graph theory principles. With the aid of JGraph, you can accomplish projects ranging from a simple graph editor, a computer network map, or a shortest-path finder. To fully understand the concepts in this article, you should have a working knowledge of Graph Theory and Java Swing.

JGraph, which is derived from the Swing JComponent class, can be used to display a network of related objects using the well-known paradigm of a graph. JGraph is well suited for this task because it:
  • Creates small (about 150 KB) files.
  • Follows API standards.
  • Provides all essential functions.

Creating your first graph
For a simple example, Listing A includes the code to create a popup window containing a graph constructed with default settings of JGraph.

A JGraph object, as shown in Listing A, gets a data model from a GraphModel object and extends it to the JComponent object. Other important objects are GraphModel and GraphUI. The former stores graph data and the latter defines the graph appearance. Under the MVC model, the JGraph class is a controller, GraphModel is a model, and GraphUI is a view.

Also in Listing A, a DefaultGraphModel object, which stores data about the relationship diagram, is used as a GraphModel object by a JGraph object. The JGraph object uses a BasicGraphUI object for its appearance. Eventually, a JScrollpane object, which applies the JGraph object as its component, shows the relationship diagram in the popup window.

You can still perform some usual operations on the graph, although the graph likely aims to demonstrate JGraph only. The operations in Table A can be applied in any JGraph object if you haven't overridden some default JGraph object properties.

Table A
Click a vertex or an edge Select the vertex or the edge
Double-click a vertex or an edge Edit the text for the vertex or the edge
Drag a vertex Move the vertex as well as an edge connected
Drag the side of a vertex Resize the vertex
Drag the end of an edge Detach the edge from a vertex, which connects the edge at that end
Press [Alt] and click Force a marquee selection if over a cell
Press [Shift] or [Ctrl] and click Toggle selections
Press [Shift] and drag a selection Constrain an offset to one direction of dragging
Press [Ctrl] and drag a selection Clone objects inside the selection
Creating your first graph

Simple customized graph
Let's extend the example to create custom graphs. Listing B modifies the data in the DefaultGraphModel object so that you can create your own graph. Table B includes a list of available methods that may be used with JGraph objects.

Table B
SimpleGraph This is a constructor of SimpleGraph. This initializes a GraphModel object (i.e., myModel) and a JGraph object (i.e., myGraph). This also creates a hash table for storing attributes of edges and vertices.
setVertix This creates a DefaultGraphCell object as a vertex. This also sets attributes for the created vertex.
setEdge This creates a DefaultEdge object as an edge. This also sets the created edge’s attributes.
insertModel This inserts new data into the GraphModel object.
showFrame This configures and shows the popup window.
Main This is the main method of the program. This creates two vertices and an edge, connects them, sets a JGraph object and shows a diagram for the object.
Simple customized graph

Now I'll explain some important statements inside the SimpleGraph’s methods shown in Listing B, so you can understand how to create a simple graph. The following two statements create a JGraph object with the DefaultGraphModel model:
myModel = new DefaultGraphModel();
myGraph = new JGraph(myModel);

The following lines of code show the use of a different model for a JGraph object:
DefaultGraphCell myCell = new DefaultGraphCell(name);
Map cellAttribute = GraphConstants.createMap();
myAttribute.put(myCell, cellAttribute);

These statements construct a cell for a vertex as well as a Map object, cellAttribute. There is a String object, name, for creating a DefaultGraphCell object, myCell. The name object is a reference to myCell. Since myAttribute is used to store attributes of the whole JGraph, this has to link to myCell and cellAttribute. That is, myAttribute is an attribute table for the graph while cellAttribute is an attribute table for a cell inside the graph. The next code snippet sets special cell attributes:
GraphConstants.setBackground(cellAttribute, bgColor);

GraphConstants.setOpaque(cellAttribute, isOpaque);

GraphConstants.setBorder(cellAttribute, border);

GraphConstants.setBorderColor(cellAttribute, borderColor);

Since myCell and cellAttribute are linked, applying a value to cellAttribute applies the effect to myCell. The first statement sets the cell background color, the second determines if the cell is opaque, and the third applies the Border object, border, to the cell. The last line sets the cell border color.

The following two statements are used to construct a Port object port1 for the vertex cell1. A Port object is a connection point of a cell:
DefaultPort port1 = new DefaultPort();

An edge connects to a cell by touching that kind of point. The next statements construct a DefaultEdge object:
DefaultEdge myEdge = new DefaultEdge(name);
Map edgeAttribute = GraphConstants.createMap();
myAttribute.put(myEdge, edgeAttribute);
GraphConstants.setLineEnd(edgeAttribute, lineEnd);
GraphConstants.setEndFill(edgeAttribute, isEndFill);

The fourth statement sets an arrow at the end of the edge, and the fifth line sets the end of the edge to be filled with the color. You can use the following statement if you want to have a double arrow edge:
GraphConstants.setLineBegin(edgeAttribute, GraphConstants.ARROW_CLASSIC);

The previous line makes the edge end with a black arrow and begin with a white arrow. These next three statements insert the previously created vertices, edges, and ports into the data model to be displayed by JGraph:
ConnectionSet cs = new ConnectionSet(edge, source, target);
Object[] cells = new Object[]{edge, srcCell, tgtCell};
myModel.insert(cells, myAttribute, cs, pm, e);

The first statement creates an object to represent the connection involving an edge, the object edge, and two ports at both ends of the edge—source and target. A ConnectionSet object is a set of objects involving a connection. A connection consists of an edge, a point at which the edge begins, and a point at which the edge ends. The second line constructs an array to store all cells used. Cells include vertices and edges.

The third line is in sequence to insert the array of cells, the attribute table of the graph, the connection, a relationship between a child and a parent inside the graph, and an array of actions that has been done. After passing this statement, it notifies a model listener and an undo listener of this insert. This statement can be considered the conclusion of what has been done to the graph.

A picture is worth a thousand words
JGraph is a simple, flexible component for displaying information in a graph. The code included in this article is just the beginning of what you can do with JGraph. The JGraph Web site provides a tutorial. The tutorial assumes readers understand the basic operations covered in this article. So you should become familiar with the basic skills mentioned in this article, and then you can learn those advanced techniques, which include customizing a mouse event, changing the view of a graph, and converting a GXL file to a SVG file.


Editor's Picks