The Diva graph FAQ

1.0 Introduction

This is one view of the graph package documentation. It basically answers all questions with a sentence or two and points to sections in other documents or source files which give more complete explanations. The questions are divided into three sections corresponding to questions about the graph model, the graph layout, and the graph display. If you have a question that's not on here, send it our way, and we'll do our best to get it answered promptly.

2.0 Contents

• Model Questions
  1. How do I use my own data structure?
  2. Why can't I set the position/appearance of nodes in the model?
  3. What if I want to add ports to the node?
  4. How do I display a prepopulated graph model?
  5. How do I delete nodes and edges?
• Layout Questions
  1. How can I change the way the edges are routed?
  2. How can I change the layout of the graph?
• Display Questions
  1. How do I change the appearance of the nodes?
  2. How do I add labels/arrows/etc. to the edges?
• Interactive Editing Questions
  1. How do I restrict which edges can be attached between nodes?
  2. How do I restrict which nodes can be placed in other composite nodes?

3.0 Model questions

1. How do I use my own data structure?

   You write a wrapper class around your data structure that implements the GraphModel interface (or a subclass). This will be discussed in a future addition to the tutorial.

2. Why can't I set the position/appearance of nodes in the model?

   In Diva, the model is distinct from the view so that there can be multiple views on the same model. You can adjust the appearance of the node in the NodeRenderer class, which is discussed below. If you really want to modify the data structure in one place, you can probably annotate a node with its position and appearance using the get/setProperty() methods, and then write a simple NodeController which uses these properties to put the node in the right place.

3. What if I want to add ports to the node?

   Add ports to the node in one of two ways. If the ports are simply for the node appearance, build your own ConnectorTarget implementation (more on this in the diva.canvas.connector documentation). If the ports are actually semantic objects (such as in a visual programming language, where each port represents a variable), the ports should be nodes themselves, and the "ported nodes" should be composite nodes. For more information, see SchematicTutorial in the tutorial.

4. How do I display a pre-populated graph model?

   Note: pre-populated means that there are already nodes in the model before the model was placed in a GraphPane. There was a problem in the initial release which made this break. That problem has been fixed and it will just work now, except for one little gotcha, which is if you set the model while the window is closed, the GraphPane thinks its size is 0x0, so the nodes all get layed out in the upper-left corner of the canvas. The way to fix this is to either set the model once the window is open, or explicitly call a global layout once the window has been opened. Both examples are given in the tutorial file diva/graph/tutorial/PrepopulatedTutorial.java and described in the tutorial.

5. How do I remove nodes and edges.

   Use the methods in the GraphController. There is currently a small architectural problem in the canvas that figures (especially connectors) reference sites on other figures. When these figures are removed, the connector has a reference to a site that is no longer valid.  A similar problem comes when dealing with selection.  Figures must be removed from the SelectionModel before being removed from the canvas.  The code in GraphController is aware of all this, but it is fairly easy to circumvent it with nasty effects.

4.0 Layout questions

1. How can I change the way the edges are routed?

   Edges are routed in the view, using connectors. In your edge renderer, you can specify that it should render a different type of connector. So far straight, arc and manhattan-routed edges are supported

2. How can I change the layout of the graph?

   The easiest way to layout a graph is to explicitly call a global layout on the pane when you finish initializing your nodes.

5.0 Display questions

1. How do I change the appearance of the nodes?

   You do this by adding your own NodeRenderer to the appropriate NodeController. When a new node is added to the model, the NodeRenderer creates a visual representation of the node to add to the view. This is described in the design document, and a complete example is given in the tutorial file diva/graph/tutorial/NodeRendererTutorial.java.

2. Can I add labels/arrows/etc. to the edges?

   You do this by adding your own EdgeRenderer to the appropriate EdgeController. When a new edge is added to the model, the EdgeRenderer creates a visual representation of the edge to add to the view. This is described in the design document, and a complete example is given in the tutorial file diva/graph/tutorial/EdgeRendererTutorial.java. Edges are represented by connectors, and more info on how to make customized connectors is available in the diva.canvas.connector package. See the package documentation for details.

6.0 Interactive Editing questions

1. How do I restrict which edges can be attached between nodes?

   Implement your own ConnectorTarget and put it into the appropriate EdgeController.  You can also implement a GraphModel in such a way that an exception is thrown when the edge is set.

2. How do I restrict which nodes can be placed in other composite nodes?

   Don't have interactors which do that, or you can implement a GraphModel in such a way that an exception is thrown when a node is placed into an illegal container.