Using graph layout in a diagram component

Controlling layout renderers by style sheets

A diagram component (an instance of IlvDiagrammer) contains various renderers that control the graphic display of SDM model objects. The following three renderers are relevant for graph layout:

The Graph Layout Renderer is also called the Node Layout Renderer because in some configurations, it only places the nodes without routing the links.
The Link Layout Renderer routes the links, unless the Graph Layout Renderer does this already.
The Label Layout Renderer places labels at nodes and links.

The renderers and the general CSS format are documented in Using CSS syntax in the style sheet

The style sheet controls all the renderers. For each renderer, there is a section in the style sheet.

See the following summary:

GraphLayout {
...//settings relevant for the Graph Layout Renderer...
}
LinkLayout {
...//settings relevant for the Link Layout Renderer...
}
LabelLayout {
...//settings relevant for the Label Layout Renderer...
}

You can also specify layout parameters for individual nodes and links by specifying a rule that selects the node or link. Here are a few examples:

#obj13 {
... //settings relevant for the application object with ID "obj13" ...
}
node.participant {
... //settings relevant for the node of type participant ...
}
node.selected {
... //settings relevant for all selected nodes ...
}
node.participant[abc="true"] {
... //settings relevant for the node of type participant whose property "abc" is true ...
}

Note

Layout parameter names in the GraphLayout, LinkLayout, and LabelLayout sections always start with a lowercase letter. Layout parameter names in the node or link rules always start with an uppercase letter.

Loading a style file

A CSS specification file becomes active when it is loaded into the SDM engine. At this point, the graph layout is performed.

Example of loading a style file

For example, if you have a diagram component of type IlvDiagrammer use the following code:

In Java™

try {
      diagrammer.setStyleSheet(new URL("file:styleSheet.css"));
} catch (Exception e) {
      ...
}

When the style sheet is loaded and the layout renderers are enabled, any change to the data model automatically updates the layout to reflect the changes.

Accessing the layout renderers

The layout renderers can be accessed from the diagram component either in Java or in CSS.

Example of accessing the layout renderers

In CSS

Use the following syntax:

GraphLayout {
    enabled:true;
    ...

In Java

The call

diagrammer.getEngine().getNodeLayoutRenderer()

returns the renderer controlled by the GraphLayout section of the style sheet.

The call

diagrammer.getEngine().getLinkLayoutRenderer()

returns the renderer controlled by the LinkLayout section of the style sheet.

diagrammer.getEngine().getLabelLayoutRenderer()

returns the renderer controlled by the LabelLayout section of the style sheet.

You can enable or disable each individual renderer. If the renderer is disabled, changes to the data model will have no effect on the renderer. For example, after the call

diagrammer.getEngine.getNodeLayoutRenderer().setEnabled(false);

a change to the data model will not trigger any new layout.

Performing layout explicitly

When a style sheet is loaded, you can also trigger a layout explicitly.

Node layout

The call

diagrammer.performNodeLayout();

performs a graph layout through the node layout renderer.

Important

Some layout algorithms place only nodes, while others place nodes and links at the same time. If the style sheet specifies a layout that places nodes and links at the same time, this call routes the links as well.

Link layout

The call

diagrammer.performLinkLayout();

performs a link layout through the link layout renderer. The link layout does not move any node, it only reshapes the links. Separating between node layout and link layout is useful for those layout algorithms that cannot do both tasks.

Label layout

The call

diagrammer.performLabelLayout();

performs a label layout through the label layout renderer. It positions the labels of graphic nodes and graphic links that are subclasses of IlvGeneralNode, IlvGeneralLink IlvSDMCompositeNode, and IlvSDMCompositeLink.

Accessing graph layout instances

Graph layout instances can be accessed from the layout renderers by the following methods:

nodeLayoutRenderer.getGraphLayout();

linkLayoutRenderer.getGraphLayout();

labelLayoutRenderer.getLabelLayout();

Writing a new layout renderer to clip links

This example shows how to implement and install a new layout renderer in order to perform link clipping. This involves combining Java code and style rules that fit together, as follows:

Create a new graph layout renderer in Java code.
Install the new graph layout renderer by adding style rules in the style sheet.

See <installdir>/jviews-diagrammer89/codefragments/graphlayout-diagrammer/graphlayout4.

In Java code

To implement the link clipping example, you need to write a subclass of IlvGraphLayoutRenderer called LinkClippingRenderer . The class declaration for the new renderer is as follows:

public class LinkClippingRenderer extends IlvGraphLayoutRenderer

The new renderer has a property called clipping which enables or disables link clipping.

The clipping property and its methods shows the property declaration and the methods to test it and set it.

The clipping property and its methods

  private boolean clipping = false;
  
  public boolean isClipping()
  {
    return clipping;
  }

  public void setClipping(boolean clipping)
  {
    this.clipping = clipping;
  }

To enable the link-clipping feature, call the method setLinkClipInterface. In the new renderer, this method is called in an overridden version of the method prepareRendering , which is called before the graph is rendered.

The new code for the prepareRendering method shows the code for the prepareRendering method in the LinkClippingRenderer class.

The new code for the prepareRendering method

public void prepareRendering(IlvSDMEngine engine)
  {
    super.prepareRendering(engine);
    if(clipping && getGraphLayout().supportsLinkClipping()){
      getGraphLayout().setLinkClipInterface(new ShapeLinkClipInterface(engine));
    }
  }

The link clip interface is set to an instance of a class called ShapeLinkClipInterface . This class computes the intersection point of the link on the node shape. Look at the source code of the example to see how the computation works.

The method removeAll is also overridden. This method is called after the graph is rendered (and after the graph layout is performed), to clean up the link clip interface.

The new code for the removeAll method shows the code for the removeAll method in the LinkClippingRenderer class.

The new code for the removeAll method

public void removeAll(IlvSDMEngine engine)
  {
    super.removeAll(engine);
    if(getGraphLayout().supportsLinkClipping()){
      getGraphLayout().setLinkClipInterface(null);
    }
  }

This method calls the superclass method and then clears the link clip interface.

The Enable/Disable Link Clipping button in the toolbar is bound to an action that calls the LinkClippingRenderer.setClipping() method to enable or disable link clipping.

You must re-create the graph after processing the action for the Enable/Disable Link Clipping button. Re-creating a graph shows the code line to add.

Re-creating a graph

diagrammer.getEngine().loadData();

Note that you could also use the IlvSDMMutableStyleSheet class to set the layout parameters dynamically.

In CSS

When you have written a new renderer, you need to configure your diagram to use this renderer instead of the supplied graph layout renderer.

Setting a new class to use instead of a supplied renderer shows the extra declaration in the SDM rule in the link-clipping style sheet.

Setting a new class to use instead of a supplied renderer

SDM {
  Renderers : "GraphLayout=LinkClippingRenderer";
  GraphLayout : true;
}

This declaration tells the SDM engine to use the new class instead of the IlvGraphLayoutRenderer class as the GraphLayout renderer.

Style rule that customizes graph layout with link clipping shows the GraphLayout rule with the extra declarations that are necessary for link clipping to work correctly.

Style rule that customizes graph layout with link clipping

GraphLayout {
  graphLayout : "Hierarchical";
  flowDirection : "Right";
  globalLinkStyle : "STRAIGHT_LINE_STYLE";
  connectingLinksToShape : "false";
  connectorStyle : "CLIPPED_PINS";
}

The GraphLayout rule contains the parameters for the graph layout renderer and for the graph layout algorithm. It contains three additional declarations for link clipping:

The first extra declaration tells the Hierarchical layout not to reshape links orthogonally, so that the effect of link clipping is more visible.
The second extra declaration tells the graph layout renderer to connect links to the center of the nodes, instead of connecting them to the border of the nodes. The link clipping algorithm then clips each link at the crossing point on the border.
The third extra declaration tells the Hierarchical layout to connect the links using clipped pins. This declaration overrides the connectorStyle declaration in the graph-layout style sheet.

Further information

You can find information on how to use the Graph Layout with Rogue Wave JViews Diagrammer in Getting started with graph layout.

Further information is in in The GraphLayout renderer in JViews Diagrammer SDK.

You can also find examples of specification in CSS for graph layout in: <installdir>/jviews-diagrammer89/codefragments/graphlayout/sample1/data/Sample.css;

More graph layout examples are supplied in: <installdir>/jviews-diagrammer89/codefragments/graphlayout-diagrammer.

A detailed description of the renderer API is available in the online Java API Reference Documentation: