Layout

JViews TGO makes use of the Rogue Wave® JViews graph layout algorithms. Each IlpEquipmentView can be connected to several node algorithms and one link algorithm.

The node layout algorithms are:
The link layout algorithms can be:
- IlvLinkLayout
- IlvShortLinkLayout
- IlvLongLinkLayout
- IltLinkLayout
- IltShortLinkLayout
- IltLocalLinkLayout
- IltStraightLinkLayout
  
  Note
  
  The difference between Ilv... and Ilt... link layout algorithms is that Ilt... algorithms support connection ports whereas Ilv... algorithms do not.

The detailed description of all the graph layout algorithms can be found in the Rogue Wave JViews Diagrammer Using Graph Layout Algorithms documentation.

In case of multiple layouts, one layout can be set to be applied automatically whenever the contents of the view changes, while the others can be applied on demand.

To configure the layouts, it is recommended to use CSS (see Configuring an equipment component through CSS). Using CSS, you can also configure per-object layout parameters.

If a layout takes too much time to execute, or if you want to add toolbar buttons to execute a layout, you can configure the layout for the view, then execute it on demand by using the API method performAttachedLayout. The advantage of this method over the method performLayoutOnce is that the layout remains attached to the view, therefore storing any previously-defined configuration.

The class IlpEquipmentView provides the following methods to handle the layout operation:

void setNodeLayout ( IlvGraphLayout layout, boolean perform). This method sets the given layout as the default for this IlpEquipmentView . If the perform parameter is set to true , the layout is applied to the objects immediately. With this method the layout is executed every time the equipment content changes.
void setLinkLayout (IlvGraphLayout layout, boolean perform) . This method sets the given layout as the default link layout for this instance of IlpEquipmentView . If the perform parameter is set to true , the layout is applied to the links immediately. With this method the layout is executed every time the equipment content changes.
public void performLayoutOnce(IlvGraphLayout layout) . This method executes the layout algorithm once on the manager content.
void startDelayingUpdates() . This method suspends temporarily the layout operations. This mechanism avoids unnecessary computation when you intend to perform a sequence of operations that affect the equipment layout.
void endDelayingUpdates() . This method resumes the layout operations suspended by a call to the method startDelayingUpdates . Any operation that requests a layout recalculation is suspended when it is executed between startDelayingUpdates and endDelayingUpdates calls.
void setGraphLayouts(IlvGraphLayout[] layouts) . This method sets the given graph layouts for this IlpEquipmentView. Several graph layouts can be set to position nodes in the view. One of them can be configured to be executed every time the equipment contents changes. This method does not apply the layout to the nodes immediately. All the graph layouts given as argument to the method are attached to the view.
void setGraphLayouts(int index, IlvGraphLayout layout) . This method sets a new graph layout for the IlpEquipmentView or replaces an existing graph layout. This method does not apply the layout to the nodes immediately.
IlvGraphLayout[] getGraphLayouts() . This method returns the graph layouts that have been configured for the view.
IlvGraphLayout getGraphLayouts(int index) . This method returns the graph layout that is configured for the view at the given index.
void setAutoLayoutIndex (int index) . This method indicates, from the list of graph layouts that have been configured using method setGraphLayouts , which one is executed automatically when the contents of the view changes.
int getAutoLayoutIndex() . This method returns the index of the graph layout that is executed automatically when the contents of the view changes.
void performAttachedLayout(int index) . This method executes the layout that has been configured for the given index, recursively in the object tree. The layout has been already attached to the view and keeps the configuration whenever it is performed.
IlvGraphic getLayoutProxy(IlpRepresentationObject) . This method returns the graphic object corresponding to the given representation object for layout purposes. This method should be used if you need to set per-object layout properties to configure the layout algorithms.

Note

Graphical parameters, such as the layout region, that are passed to the graph layout are expressed in view coordinates. Therefore, if you have expressed these parameters in stationary coordinates, you must transform them to view coordinates (by applying

equipment.getView().getCompositeGrapher().getZoomTransformer()
							equipment.getManagerView().getTransformer()

) before passing them to the graph layout.

How to use hierarchical node layout in the equipment component

In CSS, use the following rules:

Equipment {
  graphLayout: true;
}
  
GraphLayout {
  class: 'ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout';
  flowDirection: Bottom;
  levelJustification: Top;
  globalLinkStyle: 
'ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout.POLYLINE_STYLE';
  connectorStyle: 
'ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout.EVENLY_SPACED_PINS';
}

The full class path is required for the properties globalLinkStyle and connectorStyle for the type converter to locate and convert the constants.

For an example of a CSS link layout, refer to The LinkLayout rule .

In the API, use the following code:

IlvHierarchicalLayout layout = new IlvHierarchicalLayout();
layout.setFlowDirection (IlvDirection.Bottom);
layout.setLevelJustification (IlvDirection.Top);
layout.setGlobalLinkStyle (IlvHierarchicalLayout.POLYLINE_STYLE);
layout.setConnectorStyle (IlvHierarchicalLayout.EVENLY_SPACED_PINS);

equipment.setNodeLayout(layout);

Note

All layouts to be used with JViews TGO must be set in view coordinate mode. This mode is automatically set when you install layouts through setNodeLayout, setLinkLayout, or performLayoutOnce. If you call the method performLayout directly, you must first set the mode: layout.setCoordinatesMode(IlvGraphLayout.VIEW_COORDINATES);

Even when you decide to use a certain node or link layout, you may want some links or nodes to be pinned; that is, you may want to keep a certain element in a specified position that is not affected when the layout is executed on an equipment.

You can achieve this effect by using the following methods defined in IlvGraphLayout :

setPreserveFixedLinks (boolean preserve) . This method determines whether or not the layout will preserve the position of the registered links.
setPreserveFixedNodes (boolean preserve) . This method determines whether or not the layout will preserve the position of the registered nodes.
void setFixed (Object obj /* link or node */, boolean fix) . This method determines whether or not the given object will be fixed in the equipment view.
boolean isFixed (Object obj) . The return value indicates whether or not the given object is marked to be fixed. The object to be passed is an IlvGraphic belonging to the IlpGraphic that represents the object and not the IlpGraphic or IlpRepresentationObject itself.
void unfixAllLinks()
void unfixAllNodes()

How to set a link to fixed shape and a node to fixed position in the equipment view

The following code illustrates how you can set a given link to have a fixed shape and a given node to have a fixed position in the equipment view.

In CSS, use the following rules:

Equipment {
  graphLayout: true;
  linkLayout: true;
}

LinkLayout {
  class: 'ilog.views.graphlayout.link.IlvLinkLayout';
}

GraphLayout {
  layouts[0]: @+treeLayout;
}

Subobject#treeLayout {
  class: 'ilog.views.graphlayout.tree.IlvTreeLayout';
}

#Link:linkLayoutRenderer {
  fixed: true;
}

#NE1:graphLayoutRenderer:tree {
  fixed: true;
}

In the API, use the following code:

IlvGraphLayout layout = equipmentView.getLinkLayout();
layout.setPreserveFixedLinks (true);
IlpRepresentationObject linkRO = 
equipmentAdapter.getRepresentationObject(link);
layout.setFixed(equipmentView.getLayoutProxy(linkRO)); 

layout = equipmentView.getNodeLayout();
layout.setPreserveFixedNodes (true);
IlpRepresentationObject neRO = equipmentAdapter.getRepresentationObject(ne);
layout.setFixed(equipmentView.getLayoutProxy(neRO));

When the position or shape of an object is not handled by the layout, you must set it by calling the method setPosition (or view.setPosition ).

JViews TGO provides a default layout which uses IlvShortLinkLayout to shape and position links. This default layout sets all objects without an attached position to (0,0) .

How to use multiple node layouts in an equipment view

In this scenario, two node layouts are configured for the equipment view. The first one is configured to be executed automatically.

In CSS, use the following rules:

Equipment {
  graphLayout: true;
}

GraphLayout {
  layouts[0]: @+hierarchicalLayout;
  layouts[1]: @+treeLayout;
  autoLayoutIndex: 0;
}

Subobject#hierarchicalLayout {
  class: 'ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout';
  flowDirection: Bottom;  
  levelJustification: Top;  
  globalLinkStyle: POLYLINE_STYLE;
  connectorStyle: EVENLY_SPACED_PINS;
}

Subobject#treeLayout {
  class: 'ilog.views.graphlayout.tree.IlvTreeLayout';
  flowDirection: Bottom;
}

To execute the tree layout in the view, use the method performAttachedLayout , where the index is the one defined in the CSS configuration, as follows:

equipment.getView().performAttachedLayout(1);

How to configure per-object layout properties in the equipment component

Some layout algorithms require a specific configuration in order to be properly executed. For example, the bus layout needs to have a bus object specified; or the tree layout, for which you may want to specify the root node prior to the layout execution. Starting from JViews TGO 7.5, you can configure these properties using CSS as follows:

Equipment {
  graphLayout: true;
}

GraphLayout {
  layouts[0]: @+busLayout
}

Subobject#busLayout {
  class: 'ilog.views.graphlayout.bus.IlvBusLayout';
  horizontalOffset: 50;
  verticalOffsetToLevel: 50;
  verticalOffsetToPreviousLevel: 40;
  margin: 30;
  marginOnBus: 50;
}

// Configure the bus object as the bus in the layout
// All layout configuration uses the 'graphLayoutRenderer'
// and the graph layout name pseudoclasses
#BUS:graphLayoutRenderer:bus { 
  bus: true;
}

// Configure the bus to route the links that connect the 
// bus to the nodes
#BUS { 
  linksConnectToBase: true;
}

Alternatively, you can configure these properties using the API as follows:

IlvBusLayout busLayout = new IlvBusLayout();
equipment.setGraphLayouts(new IlvGraphLayout[] { busLayout });

IlpRepresentationObject ro = 
equipment.getAdapter().getRepresentationObject("BUS");
IlvGraphic layoutProxy = equipment.getView().getLayoutProxy(ro);
busLayout.setBus((IlvPolyPointsInterface)layoutProxy);

How to disable the per-object layout properties configuration in the equipment view

By default, per-object layout parameters can be configured using CSS. However, if you are not interested in this feature, you can disable it by setting the property usePerObjectParamenters in the graph layout renderer and link layout renderer. Disabling the per-object layout properties configuration speeds up significantly the rendering process.

Equipment {
  graphLayout: true;
  linkLayout: true;
}

LinkLayout {
  class: 'ilog.views.graphlayout.link.IlvLinkLayout';
  usePerObjectParameters: false;
}

GraphLayout {
  layouts[0]: @+treeLayout;
  usePerObjectParameters: false;
}

Current section

Equipment component services