ilog.views.sdm.renderer.graphlayout
Class IlvGraphLayoutRenderer

java.lang.Object
  ilog.views.sdm.renderer.IlvSDMRenderer
      ilog.views.sdm.renderer.IlvFilterSDMRenderer
          ilog.views.sdm.renderer.graphlayout.IlvGraphLayoutRenderer

All Implemented Interfaces:

ilog.views.graphlayout.IlvAutoLayoutHandler, Serializable

Direct Known Subclasses:

IlvLinkLayoutRenderer

public class IlvGraphLayoutRenderer
extends IlvFilterSDMRenderer
implements ilog.views.graphlayout.IlvAutoLayoutHandler

The class IlvGraphLayoutRenderer is a filtering renderer that applies a graph layout algorithm to the links and/or the nodes of the graph.

Layout Algorithm

You must specify the layout algorithm that you want to use by adding a declaration in the style sheet:

 SDM {
   GraphLayout : "Hierarchical";
 }
 

You can use any graph layout algorithm of the ILOG JViews library. You can specify an abbreviated graph layout name (for example "Hierarchical"), or a fully qualified class name (for example, "ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout").

Global Parameters

The properties of the IlvGraphLayout instance can be customized in the style sheet. For example:

 SDM {
   GraphLayout : "Hierarchical";
 }
 GraphLayout {
   globalLinkStyle : "ORTHOGONAL_STYLE";
   flowDirection : "Bottom";
 }
 

Per-Object Parameters

ILOG JViews layout algorithms (that is, subclasses of IlvGraphLayout) provide many parameters that control how a specific layout will be applied to a particular node or link. Starting with ILOG JViews 5.5, the graph layout renderer lets you set all these per-object parameters from the style sheet as in the following examples:

 node.tag1 {
   class : "...";
   ...
   Fixed : "true";
 }
 link.tag2 {
   class : "...";
   ...
   ToPortSide : "NORTH";
   FromPortSide : "SOUTH";
 }
 

The first rule will cause the method IlvGraphLayout.setFixed(java.lang.Object, boolean) to be called for all the nodes that match the rule. The second rule will cause the method IlvHierarchicalLayout.setToPortSide(java.lang.Object, int) to be called for all the links that match the rule.

The general mechanism is the following. A parameter property is created for each method of the IlvGraphLayout subclass that matches the following criteria:

• The name of the method begins with "set".
• The first argument of the method is an Object (this first argument is assumed to be a graphic object).
• The method has at least two arguments.

The name of the parameter property is the name of the method, without the "set" prefix. The initial capital letter is preserved; this is consistent with the naming of SDM rendering properties, and avoids ambiguities with the Bean properties of graphic objects.

The right-hand-side value of the CSS declaration contains the parameters of the method, not including the first argument (the graphic object). If the method expects more than two arguments, the declaration must be a comma-separated list. For example, the following declaration:

 node.tag1 {
   class : "...";
   ...
   NumberOfPorts : "EAST,5";
 }
 

will cause the method IlvHierarchicalLayout.setNumberOfPorts(java.lang.Object, int, int) to be called as follows: layout.setNumberOfPorts(graphic, EAST, 5).

The values in the CSS declaration will be converted automatically to the type expected by the corresponding method. For example, "EAST" will be converted to the value of the field IlvHierarchicalLayout.EAST. You can also use a fully qualified field name, for example "ilog.views.graphlayout.hierarchical.IlvHierarchicalLayout.EAST".

It is also possible to call the same method several times as follows:

 node.tag1 {
   NumberOfPorts : "WEST,3;EAST,5";
 }
 

This will call layout.setNumberOfPorts(graphic, WEST, 3) and layout.setNumberOfPorts(graphic, EAST, 5). Note that the parameters of the different calls are separated by semi-colons.

The default introspection mechanism for setting per-object parameters can be overridden if needed. You can provide an explicit piece of Java code to set a parameter, using the method addParameterSetter(ilog.views.sdm.renderer.graphlayout.IlvGraphLayoutRenderer.ParameterSetter) and the class IlvGraphLayoutRenderer.ParameterSetter.

In addition, the following two properties are handled directly by the renderer:

• LayoutIgnored - If this property is set to true, the object will be completely ignored by the graph model (using an IlvLayoutGraphicFilter).
• LayoutGroup - This property is used to apply the layout algorithm successively to different groups of objects. For each different value of the property, the layout algorithm is applied only to the objects whose LayoutGroup property is set to the same value.

If the layout algorithm is an IlvHierarchicalLayout, the property MarkedForIncremental can be used. When this property is set to true for an object, the method IlvHierarchicalLayout.markForIncremental(java.lang.Object) is called for this object, which means that the position of the object will be recomputed during the next incremental layout. This property has an effect only if the incrementalMode of the layout itself was set to true. For example:

 GraphLayout {
   incrementalMode: "true";
 }
 node:selected {
   MarkedForIncremental : "true";
 }
 

If the layout algorithm is an IlvCircularLayout, you can add a node to several clusters by setting the ClusterId property several times:

 node[name="foo"] {
   ClusterId : "cluster1;cluster2;cluster3";
 }
 

You can optionally specify an index inside each cluster:

   ClusterId : "cluster1,5;cluster2,1;cluster3,4";
 

Note: Starting with JViews 6.5, if you are not using any node or link parameters, you can disable this mechanism using setUsePerObjectParameters(false). This will remove the overhead of testing the parameters, which can speed up the SDM rendering process significantly.

Specifying a Different Layout for Each Subgraph

The property GraphLayout can be set on a subgraph node. This lets you use a different layout algorithm for each subgraph. For example, the following rule says that subgraph nodes of tag group must be laid out using an IlvGridLayout algorithm:

 node.group {
   GraphLayout : "Grid";
 }
 

You can also use an "@#" construct, which lets you customize the parameters of the subgraph's layout:

 node.group {
   GraphLayout : "@#grid";
 }
 Subobject#grid {
   class : "ilog.views.graphlayout.grid.IlvGridLayout";
   layoutMode : "TILE_TO_ROWS";
 }
 

Compatibility with ILOG JViews 5.0

The following rendering properties were used in ILOG JViews 5.0 and previous versions. They are now superseded by the new method introspection mechanism, but can still be used for compatibility:

• LayoutFixed - Equivalent to Fixed, calls IlvGraphLayout.setFixed(java.lang.Object, boolean).
• LayoutCluster - Equivalent to ClusterId, calls IlvCircularLayout.setClusterId(java.lang.Object, ilog.views.graphlayout.circular.IlvClusterId).
• LayoutStarCenter - Equivalent to StarCenter, calls IlvCircularLayout.setStarCenter(java.lang.Object, boolean).

Conflicts Between Node and Link Layout Properties

If an IlvGraphLayoutRenderer and an IlvLinkLayoutRenderer are used at the same time, you may sometimes encounter conflicts between node or link properties that have the same name in the two layout algorithms.

A common example of this is the linkStyle property:

 SDM {
   GraphLayout : "Hierarchical";
   LinkLayout : "true";
 }
 link {
   linkStyle : "POLYLINE_STYLE";
 }
 

With these rules, since both IlvHierarchicalLayout and IlvLinkLayout classes define a setLinkStyle method, the declaration will call the method for the two layout objects. Unfortunately, the value POLYLINE_STYLE is valid only for the hierarchical layout, not for the link layout, so an exception will be thrown.

To solve this problem, you have to specify that the declaration must be applied only to the hierarchical layout. This is done using the pseudoclass graphLayoutRenderer:

 link:graphLayoutRenderer {
   linkStyle : "POLYLINE_STYLE";
 }
 

Similarly, you could use the pseudo-class linkLayoutRenderer to specify that a declaration applies only to the link layout object.

Furthermore, you can specify rules for nodes and links that are only applied for a given layout style, by using the layout name as pseudo-class:

 link:graphLayoutRenderer:hierarchical {
   linkStyle : "POLYLINE_STYLE";
 } 
 

Hierarchical Constraints

If the graph layout algorithm is an instance of IlvHierarchicalLayout, you can define constraints (see IlvHierarchicalConstraint) between the nodes of the graph by setting special properties in the style sheet.

Examples

The examples in this section illustrate the most usual cases.

The following rule says that all participant nodes should be placed on the "east" side of the hierarchy (that is, on the right for a top-bottom layout):

 node.participant {
   ExtremityConstraint : "EAST";
 }
 

The following rule says that the source node and the destination node of a link of tag application_link should be placed at the same level in the hierarchy:

 link.application_link {
   GroupSpreadConstraint : "true";
 }
 

In addition, you could use the SideBySideConstraint property to say that the two nodes should be kept "side by side," that is, without any node between them:

 node.application_link {
   GroupSpreadConstraint : "true";
   SideBySideConstraint : "true";
 }
 

The following rule separates the graph into two "swim lanes," one the activity nodes and one for the participant nodes:

 node.activity {
   SwimLaneConstraint : "Activities";
 }
 node.participant {
   SwimLaneConstraint : "Participants";
 }
 

The following rule says that all selected nodes should be placed at a higher level in the hierarchy than unselected nodes:

 node:selected {
   HigherRelativeLevelConstraint : "selection";
 }
 node {
   LowerRelativeLevelConstraint : "selection";
 }
 

Note that the "higher" and "lower" groups are associated by setting the two properties to the same value. The value is arbitrary. You can use different values to define several "relative level" constraints.

The following rule says that all selected nodes should be placed at a higher position in each level than unselected nodes:

 node:selected {
   HigherRelativePositionConstraint : "selection";
 }
 node {
   LowerRelativePositionConstraint : "selection";
 }
 

The next sections explain the mechanism in more detail, but the examples should generally be sufficient.

Node Groups

Most constraints are defined between groups of nodes. For example, an IlvGroupSpreadConstraint can be used to keep a group of nodes at the same level in the hierarchy.

Node groups are built according to the values of the constraint properties. Two nodes belong to the same node group if the values of a constraint property for these two nodes are equal. Here is an example:

 node.activity {
   GroupSpreadConstraint : "@participant_id";
 }
 node.participant {
   GroupSpreadConstraint : "@__ID";
 }
 

The activity nodes are assumed to have a property participant_id that holds the ID of the participant assigned to the activity. So, the value of the GroupSpreadConstraint property in both rules is the same (the ID of the participant), and thus the two nodes form a node group. Note that node groups are not limited to two nodes; if the GroupSpreadConstraint of a third node had the same value, it would have been included in the node group as well.

When two nodes are connected by a link, you can use a simpler syntax to define a node group containing these two nodes. Assuming the activity and the participant were connected by a link of tag participant_link, you could have written:

 participant_link {
   GroupSpreadConstraint : "true";
 }
 

This would create a constraint between the two extremities of the link.

Additional Parameters

Some constraints accept additional parameters, for example the "spread size" for a GroupSpread constraint. These additional parameters can be specified after the node group identifier, separated by commas. For example:

 participant_link {
   GroupSpreadConstraint : "true,1"; // spread size = 1
 }
 

Constraint Properties

The properties that you can use to define constraints are named after the names of the corresponding subclasses of IlvHierarchicalConstraint.

• ExtremityConstraint: Defines one or more IlvExtremityConstraint instances. The value of the property is the side where the node should be placed; it must be one of "NORTH", "SOUTH", "EAST", "WEST". Note that this constraint does not act on node groups. Instead, a new constraint is created for each node that has the property.
• GroupSpreadConstraint: Defines one or more IlvGroupSpreadConstraint instances. All the nodes that have the same value for this property will be kept at the same level in the hierarchy. This constraint accepts one additional integer parameter: the "spread size", that is, the number of levels on which the nodes are allowed to be spread. The spread size is optional; by default it is 0 (all nodes strictly at the same level). If the property is set on a link, the constraint is defined between the source and the destination of the link.
• LevelRangeConstraint: Defines one or more IlvLevelRangeConstraint instances. All the nodes that have the same value for this property will be kept in a specified range of levels in the hierarchy. This constraint needs two additional parameters: a minimum and a maximum level. If the property is set on a link, the constraint is defined for the source and the destination of the link.
• LowerRelativeLevelConstraint, HigherRelativeLevelConstraint: These two properties are used together to define one or more IlvRelativeLevelConstraint instances. The value of the properties identify two groups of nodes: a "lower" group and a "higher" group. The nodes of the "lower" group will be placed at a lower level in the hierarchy (that is, nearer to the top for a top-bottom layout). The values of the matching "lower" and "higher" properties must be the same. This constraint accepts one additional floating-point parameter, which is the priority of the constraint. The priority is optional; by default it is 0f.
• LowerRelativePositionConstraint, HigherRelativePositionConstraint: These two properties are used together to define one or more IlvRelativePositionConstraint instances. The values of the properties identify two groups of nodes: a "lower" group and a "higher" group. The nodes of the "lower" group will be placed at a lower position in a given level of the hierarchy (that is, nearer to the left for a top-bottom layout). The values of the matching "lower" and "higher" properties must be the same. This constraint accepts one additional floating-point parameter, which is the priority of the constraint. The priority is optional; by default it is 0f.
• SideBySideConstraint: Defines one or several IlvSideBySideConstraint instances. All the nodes that have the same value for this property will be kept side by side, that is, no other nodes will be placed between any two nodes of the group in the same level of the hierarchy. This constraint accepts one additional floating-point parameter, which is the priority of the constraint. The priority is optional; by default it is 0f. If the property is set on a link, the constraint is defined between the source and the destination of the link.
• SwimLaneConstraint: Defines one or several IlvSwimLaneConstraint instances. All the nodes that have the same value for this property will be placed in the same swim lane. This constraint accepts three additional floating-point parameters: the relative size of the swim lane, the position index, and the minimum margin. By default, the relative size is -1f, the position index is -1, and the margin is 20. See IlvSwimLaneConstraint for more explanation of swim lanes. See also the class IlvSwimLanesRenderer which is responsible for displaying the swim lanes graphically.

Note: Starting with JViews 6.5, if you are not using any hierarchical constraints, nor any node or link parameters, you can disable this mechanism using setUsePerObjectParameters(false). This will remove the overhead of testing the presence of constraints, which can speed up the SDM rendering process significantly.

Since:

JViews 4.0

See Also:

IlvGraphLayout, Serialized Form

Nested Class Summary

static class	IlvGraphLayoutRenderer.GraphLayoutParametersBean This auxiliary class is internally used to encapsulate graph layout parameters as Java Beans.
static class	IlvGraphLayoutRenderer.ParameterSetter This inner class is used to register custom graph layout parameters with the IlvGraphLayoutRenderer.

Field Summary

Fields inherited from class ilog.views.sdm.renderer.IlvFilterSDMRenderer

_renderer

Constructor Summary

IlvGraphLayoutRenderer()
Creates a new layout renderer with a null filtered renderer.

IlvGraphLayoutRenderer(IlvSDMRenderer renderer)
Creates a new layout renderer for a specified filtered renderer.

Method Summary

void	addGraphLayoutRendererListener(SDMGraphLayoutRendererListener listener) Adds the specified listener to receive events from the renderer when its layout is performed.
static void	addParameterSetter(IlvGraphLayoutRenderer.ParameterSetter setter) Registers a custom parameter setter.
protected void	addViewListeners(IlvManagerView view) Adds the listeners that recompute the link layout when the view is zoomed or unzoomed.
void	customize(IlvSDMEngine engine, Object object, IlvGraphic g, String[] pseudoClasses) Sets the layout parameters for the customized object.
Object[]	getAuxiliaryBeans() Returns an array containing the IlvGraphLayout object returned by getGraphLayout().
URL	getConstraintsURL() Returns the URL of the file that specifies the layout constraints.
ilog.views.graphlayout.IlvGraphLayout	getGraphLayout() Returns the graph layout algorithm that this renderer will apply to the grapher.
ilog.views.graphlayout.IlvGraphLayout	getGraphLayout(IlvSDMEngine engine, IlvGrapher grapher) Returns the IlvGraphLayout instance attached to the specified IlvGrapher.
ilog.views.graphlayout.IlvGraphLayout	getGraphLayout(IlvSDMEngine engine, IlvGraphic graphic) Returns the IlvGraphLayout instance attached to the IlvGrapher containing a graphic object.
ilog.views.graphlayout.IlvLayoutProvider	getLayoutProvider() Returns the layout provider that is responsible for creating the sublayouts when the SDM engine's grapher contains subgraphers.
Enumeration	getLayouts(IlvSDMEngine engine, boolean preOrder) Returns the graph layout objects associated with the top-level grapher and all its subgraphs.
String	getParameter() This method calls getGraphLayout().
int	getParametersMode() This method is part of the JViews implementation, do not use it.
boolean	isConnectingLinksToShape() Returns the flag that specifies whether the graph layout algorithm should connect the links to the shape of the nodes or to the global bounding box of the nodes.
boolean	isEnabled() Returns a Boolean specifying whether the graph layout algorithm is enabled or disabled.
boolean	isEnsureAppropriateLinks() Returns true if the renderer automatically makes sure that appropriate links and link connectors are used when needed.
boolean	isGraphLayoutExceptionPassedOn() Returns true if the graph layout exception is passed on.
boolean	isIncrementalLayout() Returns true when the incremental mode is enabled.
boolean	isPartialLayout() Returns true when the partial mode is enabled.
boolean	isPerformingLayoutOnZoom() Returns a boolean specifying whether the layout algorithm should be applied every time the transformer of the reference view changes, or only when the data is initially rendered.
boolean	isSavingNodePositions() Returns a Boolean specifying whether the positions of the nodes, as computed by the graph layout algorithm, will be saved to the data model, or if the data model will be left unchanged.
boolean	isUsePerObjectParameters() Returns true if per-object layout parameters are enabled (the default), or false otherwise.
void	linkGraphicAdded(IlvSDMEngine engine, Object object, IlvGraphic graphic, boolean redraw) Sets the layout parameters for the new object.
protected boolean	needsViewListeners() Returns true, because this renderer needs to install listeners on all the views.
void	nodeGraphicAdded(IlvSDMEngine engine, Object object, IlvGraphic graphic, boolean redraw) Sets the layout parameters for the new object.
void	nodeGraphicBBoxChanged(IlvSDMEngine engine, Object node, IlvGraphic graphic, IlvRect oldBBox, IlvRect newBBox, String[] pseudoClasses) Performs the layout algorithm whenever a node is moved.
void	performAutoLayout(Object layout, Vector objects) Implementation of the IlvAutoLayoutHandler interface.
void	performLayout(IlvSDMEngine engine) Performs the layout algorithm.
void	prepareRendering(IlvSDMEngine engine) Attaches the graph layout algorithm to the grapher of the SDM engine.
void	propertyChanged(IlvSDMEngine engine, Object object, String propertyName, Object oldValue, Object newValue, IlvGraphic graphic) Sets the layout parameters for the modified object.
void	readConstraints(Reader reader) Reads the layout constraints.
void	reloadConstraintsURL() Reloads the URL that specifies the layout constraints.
void	removeAll(IlvSDMEngine engine) Detaches the graph layout algorithm from the grapher.
void	removeGraphLayoutRendererListener(SDMGraphLayoutRendererListener listener) Removes the specified listener so that it no longer receives events from the renderer when its layout is performed.
static void	removeParameterSetter(IlvGraphLayoutRenderer.ParameterSetter setter) Deregisters a custom parameter setter.
protected void	removeViewListeners(IlvManagerView view) Removes the listeners that recompute the link layout when the view is zoomed or unzoomed.
void	renderingDone(IlvSDMEngine engine) This is where the graph layout algorithm is performed.
void	setConnectingLinksToShape(boolean yes) Specifies whether the graph layout algorithm should connect the links to the shape of the nodes or to the global bounding box of the nodes.
void	setConstraintsURL(URL url) Sets the URL that specifies the layout constraints.
void	setEnabled(boolean enabled) Enables or disables the graph layout algorithm.
void	setEnsureAppropriateLinks(boolean ensure) Sets whether the renderer automatically makes sure that appropriate links and link connectors are used when needed.
void	setGraphLayout(ilog.views.graphlayout.IlvGraphLayout layout) Sets the graph layout algorithm that this renderer will apply to the grapher.
void	setGraphLayoutExceptionPassedOn(boolean passOn) Sets whether the graph layout exception is passed on.
void	setIncrementalLayout(boolean incremental) Enables or disables the incremental mode of the hierarchical layout.
void	setParameter(String parameter) This method calls setGraphLayout(ilog.views.graphlayout.IlvGraphLayout) with the name of the graph layout (the parameter) converted to its Java class (for example, "tree" becomes an instance of ilog.views.graphlayout.tree.IlvTreeLayout).
void	setParametersMode(int mode) This method is part of the JViews implementation, do not use it.
void	setPartialLayout(boolean partial) Enables or disables the partial layout mode of the layout.
void	setPerformingLayoutOnZoom(boolean b) Specifies whether the layout algorithm should be applied every time the transformer of the reference view changes, or only when the data is initially rendered.
void	setSavingNodePositions(boolean saving) Specifies whether the positions of the nodes, as computed by the graph layout algorithm, will be saved to the data model, or if the data model will be left unchanged.
void	setUsePerObjectParameters(boolean use) Enables or disables per-object layout parameters.
void	writeConstraints(PrintWriter writer) Writes the layout constraints.

Methods inherited from class ilog.views.sdm.renderer.IlvFilterSDMRenderer

addLinkGraphic, addNodeGraphic, computeBBox, createLinkGraphic, createNodeGraphic, getEncapsulatedGraphic, getFilteredRenderer, getGraphicProperty, getLinkConnectionRectangle, moveResizeNodeGraphic, processServerAction, removeLinkGraphic, removeNodeGraphic, setFilteredRenderer, updateObjectProperties

Methods inherited from class ilog.views.sdm.renderer.IlvSDMRenderer

callMoveResizeNodeGraphic, convert, convert, getAlias, getAuxiliaryBean, getEngine, getLocation, setAlias, setEngine, setLayerName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IlvGraphLayoutRenderer

public IlvGraphLayoutRenderer(IlvSDMRenderer renderer)

Creates a new layout renderer for a specified filtered renderer.

Parameters:

renderer - The filtered renderer.

IlvGraphLayoutRenderer

public IlvGraphLayoutRenderer()

Creates a new layout renderer with a null filtered renderer.

Method Detail

setGraphLayout

public void setGraphLayout(ilog.views.graphlayout.IlvGraphLayout layout)

Sets the graph layout algorithm that this renderer will apply to the grapher.

Parameters:

layout - The graph layout object.

getGraphLayout

public ilog.views.graphlayout.IlvGraphLayout getGraphLayout()

Returns the graph layout algorithm that this renderer will apply to the grapher.

getAuxiliaryBeans

public Object[] getAuxiliaryBeans()

Returns an array containing the IlvGraphLayout object returned by getGraphLayout().

Overrides:

getAuxiliaryBeans in class IlvSDMRenderer

Since:

JViews 5.5

setParameter

public void setParameter(String parameter)

This method calls setGraphLayout(ilog.views.graphlayout.IlvGraphLayout) with the name of the graph layout (the parameter) converted to its Java class (for example, "tree" becomes an instance of ilog.views.graphlayout.tree.IlvTreeLayout).

Overrides:

setParameter in class IlvSDMRenderer

Parameters:

parameter - The value of the parameter.

getParameter

public String getParameter()

This method calls getGraphLayout().

Overrides:

getParameter in class IlvSDMRenderer

See Also:

IlvSDMRenderer.setParameter(java.lang.String)

setEnabled

public void setEnabled(boolean enabled)

Enables or disables the graph layout algorithm.

Parameters:

enabled - If true, this renderer will perform the graph layout algorithm every time a data model is loaded or a node is added to the model. If false, the graph layout is disabled, and the renderer does nothing.

isEnabled

public boolean isEnabled()

Returns a Boolean specifying whether the graph layout algorithm is enabled or disabled.

setSavingNodePositions

public void setSavingNodePositions(boolean saving)

Specifies whether the positions of the nodes, as computed by the graph layout algorithm, will be saved to the data model, or if the data model will be left unchanged.

Parameters:

saving - If true, this renderer will attempt to save the positions computed by the graph layout algorithm in the data model. This is done by calling the method IlvSDMEngine.updateNodePositions(), and will succeed only if the model is editable. If false, the data model will be left unchanged. The default value is true.

See Also:

IlvSDMEngine.updateNodePositions()

isSavingNodePositions

public boolean isSavingNodePositions()

Returns a Boolean specifying whether the positions of the nodes, as computed by the graph layout algorithm, will be saved to the data model, or if the data model will be left unchanged.

setEnsureAppropriateLinks

public void setEnsureAppropriateLinks(boolean ensure)

Sets whether the renderer automatically makes sure that appropriate links and link connectors are used when needed. Some layout algorithms require specific types of links and link connectors. Typically, subclasses of IlvPolylineLinkImage and subclasses of IlvFreeLinkConnector are suitable for all layout algorithms.

If layout cannot be performed because an inappropriate link or link connector is detected, then the following happens:

• If graph layout exceptions are passed on, a corresponding graph layout exception of type IlvInappropriateLinkException is thrown.
• Otherwise, if ensuring appropriate links is enabled, the inappropriate links are replaced by instances of IlvPolylineLinkImage, and the inappropriate link connectors are replaced by instances of IlvSDMFreeLinkConnector. Then layout is performed.
• Otherwise, layout is performed on the inappropriate links and connectors and the result is undefined. Typically, the layout result is faulty in this case, for example, the link shape is not as specified in the graph layout parameters.

Parameters:

ensure - If true, makes sure that appropriate links are used.

Since:

JViews 6.0

See Also:

isEnsureAppropriateLinks(), setGraphLayoutExceptionPassedOn(boolean)

isEnsureAppropriateLinks

public boolean isEnsureAppropriateLinks()

Returns true if the renderer automatically makes sure that appropriate links and link connectors are used when needed.

Since:

JViews 6.0

See Also:

setEnsureAppropriateLinks(boolean)

setGraphLayoutExceptionPassedOn

public void setGraphLayoutExceptionPassedOn(boolean passOn)

Sets whether the graph layout exception is passed on. If enabled, all exceptions of type IlvGraphLayoutException are passed to the outside as runtime exceptions. If disabled, the exceptions are caught and handled internally. This option is disabled by default. It is useful only for debugging purpose to pass on the graph layout exception. Independently of whether the exception is passed on or not, the exception is logged at the logger "ilog.views.sdm.renderer.graphlayout".

Parameters:

passOn - If true, the exception is passed on.

Since:

JViews 6.0

See Also:

isGraphLayoutExceptionPassedOn()

isGraphLayoutExceptionPassedOn

public boolean isGraphLayoutExceptionPassedOn()

Returns true if the graph layout exception is passed on. Otherwise, exceptions during graph layout are caught and handled internally.

Since:

JViews 6.0

See Also:

setGraphLayoutExceptionPassedOn(boolean)

setConnectingLinksToShape

public void setConnectingLinksToShape(boolean yes)

Specifies whether the graph layout algorithm should connect the links to the shape of the nodes or to the global bounding box of the nodes.

Some nodes (for example, the IlvGeneralNode) have a basic shape and a label that may be outside the shape. If this method is called with a true parameter, the links will be connected to the shape, and the label will not be considered part of the node. If the method is called with a false parameter, the links will be connected to the global bounding rectangle of the node, that is, the union of the shape's bounding rectangle and the label's bounding rectangle.

The bounding rectangle of the shape is the rectangle returned by the IlvSDMRenderer.getLinkConnectionRectangle(ilog.views.sdm.IlvSDMEngine, ilog.views.IlvGraphic, ilog.views.IlvTransformer). The global bounding rectangle of the node is the rectangle returned by the IlvGraphic.boundingBox(ilog.views.IlvTransformer).

Parameters:

yes - If true, the links will be connected to the bounding rectangle of the shape only. If false, the links will be connected to the bounding rectangle of the shape and the label.

Since:

JViews 5.5

isConnectingLinksToShape

public boolean isConnectingLinksToShape()

Returns the flag that specifies whether the graph layout algorithm should connect the links to the shape of the nodes or to the global bounding box of the nodes.

Since:

JViews 5.5

See Also:

setConnectingLinksToShape(boolean)

prepareRendering

public void prepareRendering(IlvSDMEngine engine)

Attaches the graph layout algorithm to the grapher of the SDM engine.

Overrides:

prepareRendering in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

nodeGraphicAdded

public void nodeGraphicAdded(IlvSDMEngine engine,
                             Object object,
                             IlvGraphic graphic,
                             boolean redraw)

Sets the layout parameters for the new object.

Overrides:

nodeGraphicAdded in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher to which the graphic object has been added.

object - The object that is being translated into an IlvGraphic.

graphic - The graphic object that has just been added to the grapher.

redraw - If true, the region covered by the new graphic object must be redrawn.

Since:

JViews 5.0

See Also:

IlvSDMRenderer.addNodeGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)

linkGraphicAdded

public void linkGraphicAdded(IlvSDMEngine engine,
                             Object object,
                             IlvGraphic graphic,
                             boolean redraw)

Sets the layout parameters for the new object.

Overrides:

linkGraphicAdded in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher to which the graphic object has been added.

object - The object that is being translated into an IlvGraphic.

graphic - The graphic object that has just been added to the grapher.

redraw - If true, the region covered by the new graphic object must be redrawn.

Since:

JViews 5.0

See Also:

IlvSDMRenderer.addLinkGraphic(ilog.views.sdm.IlvSDMEngine, java.lang.Object, ilog.views.IlvGraphic, boolean)

propertyChanged

public void propertyChanged(IlvSDMEngine engine,
                            Object object,
                            String propertyName,
                            Object oldValue,
                            Object newValue,
                            IlvGraphic graphic)

Sets the layout parameters for the modified object.

Overrides:

propertyChanged in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object is displayed.

object - The data object whose property has changed.

propertyName - The name of the property that has been modified.

oldValue - The old value of the property.

newValue - The new value of the property.

graphic - The graphic object associated with object.

nodeGraphicBBoxChanged

public void nodeGraphicBBoxChanged(IlvSDMEngine engine,
                                   Object node,
                                   IlvGraphic graphic,
                                   IlvRect oldBBox,
                                   IlvRect newBBox,
                                   String[] pseudoClasses)

Performs the layout algorithm whenever a node is moved.

Overrides:

nodeGraphicBBoxChanged in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

node - The data node that the graphic object represents.

graphic - The graphic object that has been moved and/or resized.

oldBBox - The bounding box of the graphic object before the change.

newBBox - The bounding box of the graphic object after the change.

pseudoClasses - The pseudo-classes of the object. This parameter can be null.

Since:

JViews 6.0

customize

public void customize(IlvSDMEngine engine,
                      Object object,
                      IlvGraphic g,
                      String[] pseudoClasses)

Sets the layout parameters for the customized object.

Overrides:

customize in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

object - The data object that the graphic object represents.

g - The graphic object to customize.

pseudoClasses - The pseudo-classes of the object. This parameter can be null.

Since:

JViews 5.5

removeAll

public void removeAll(IlvSDMEngine engine)

Detaches the graph layout algorithm from the grapher.

Overrides:

removeAll in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

renderingDone

public void renderingDone(IlvSDMEngine engine)

This is where the graph layout algorithm is performed.

Overrides:

renderingDone in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

performLayout

public void performLayout(IlvSDMEngine engine)

Performs the layout algorithm. This method is called from renderingDone(ilog.views.sdm.IlvSDMEngine).

Parameters:

engine - The SDM engine.

performAutoLayout

public void performAutoLayout(Object layout,
                              Vector objects)

Implementation of the IlvAutoLayoutHandler interface. Performs an automatic layout that was caused by a structural or geometric change of some graphic objects.

Specified by:

performAutoLayout in interface ilog.views.graphlayout.IlvAutoLayoutHandler

Parameters:

layout - The graph layout to be performed.

objects - The vector of graphic objects that caused the need for layout. These objects were added, removed or have moved. If null is passed, the need for layout has no specific reason (e.g., when all nodes and links have moved).

Since:

JViews 6.0

getGraphLayout

public ilog.views.graphlayout.IlvGraphLayout getGraphLayout(IlvSDMEngine engine,
                                                            IlvGraphic graphic)

Returns the IlvGraphLayout instance attached to the IlvGrapher containing a graphic object.

Parameters:

engine - The SDM engine.

graphic - The graphic object.

Since:

JViews 5.5

getGraphLayout

public ilog.views.graphlayout.IlvGraphLayout getGraphLayout(IlvSDMEngine engine,
                                                            IlvGrapher grapher)

Returns the IlvGraphLayout instance attached to the specified IlvGrapher.

Parameters:

engine - The SDM engine.

grapher - The grapher.

Since:

JViews 5.5

getLayoutProvider

public ilog.views.graphlayout.IlvLayoutProvider getLayoutProvider()

Returns the layout provider that is responsible for creating the sublayouts when the SDM engine's grapher contains subgraphers.

Since:

JViews 5.5

getLayouts

public Enumeration getLayouts(IlvSDMEngine engine,
                              boolean preOrder)

Returns the graph layout objects associated with the top-level grapher and all its subgraphs.

Parameters:

engine - The SDM engine to which this renderer is attached.

preOrder - Determines the order in which the layout objects are returned.

Returns:

An enumeration of IlvGraphLayout objects.

Since:

JViews 5.5

See Also:

IlvGraphModel.getLayouts(ilog.views.graphlayout.IlvLayoutProvider, boolean)

setUsePerObjectParameters

public void setUsePerObjectParameters(boolean use)

Enables or disables per-object layout parameters.

This method can be used to disable or re-enable the mechanism that sets per-node or per-link parameters, as explained in the class description.

By default, per-object parameters are enabled. You can disable them if you are sure that your style sheet does not use any per-object layout parameters. Disabling per-object parameters speeds up the SDM rendering process.

Parameters:

use - If this parameter is true, per-object layout parameters can be set in the style sheet, as explained in the class description. If this parameter is false, per-object layout parameters are ignored.

Since:

JViews 6.5

isUsePerObjectParameters

public boolean isUsePerObjectParameters()

Returns true if per-object layout parameters are enabled (the default), or false otherwise.

Since:

JViews 6.5

See Also:

setUsePerObjectParameters(boolean)

setParametersMode

public void setParametersMode(int mode)

This method is part of the JViews implementation, do not use it.

Since:

JViews 5.5

getParametersMode

public int getParametersMode()

This method is part of the JViews implementation, do not use it.

Since:

JViews 5.5

addParameterSetter

public static void addParameterSetter(IlvGraphLayoutRenderer.ParameterSetter setter)

Registers a custom parameter setter.

Most per-object layout parameters are handled automatically by the IlvGraphLayoutRenderer. For example, if you want to have the hierarchical layout algorithm connect links to the left of nodes, you can add the the following declaration in the SDM style sheet:

 link {
   ToPortSide : "EAST";
 }
 

The IlvGraphLayoutRenderer will automatically call (through the Java introspection mechanism) the method IlvHierarchicalLayout.setToPortSide(java.lang.Object, int) with a parameter equal to IlvHierarchicalLayout.EAST.

In some cases, though, it may be necessary to bypass this automatic introspection mechanism. This method lets you specify an explicit piece of Java code that you want executed when a layout parameter is set for an object.

Parameters:

setter - A new parameter setter that will be used instead of the automatic introspection mechanism to set a specified graph layout parameter.

Since:

JViews 5.5

See Also:

IlvGraphLayoutRenderer.ParameterSetter

removeParameterSetter

public static void removeParameterSetter(IlvGraphLayoutRenderer.ParameterSetter setter)

Deregisters a custom parameter setter.

Parameters:

setter - The parameter setter to remove.

Since:

JViews 5.5

See Also:

addParameterSetter(ilog.views.sdm.renderer.graphlayout.IlvGraphLayoutRenderer.ParameterSetter), IlvGraphLayoutRenderer.ParameterSetter

addGraphLayoutRendererListener

public void addGraphLayoutRendererListener(SDMGraphLayoutRendererListener listener)

Adds the specified listener to receive events from the renderer when its layout is performed.

Parameters:

listener - The listener to add.

Since:

JViews 5.0

removeGraphLayoutRendererListener

public void removeGraphLayoutRendererListener(SDMGraphLayoutRendererListener listener)

Removes the specified listener so that it no longer receives events from the renderer when its layout is performed.

Parameters:

listener - The listener to remove.

Since:

JViews 5.0

setPartialLayout

public void setPartialLayout(boolean partial)

Enables or disables the partial layout mode of the layout. If this property is true, and objects are selected, all the nodes except the selected nodes are marked as fixed, so that the layout is applied only on the selected nodes.

Parameters:

partial - If true, and if there are selected objects, only those objects will be laid out by subsequent node layout operations. If false, all the objects will be laid out regardless of the selection.

Since:

JViews 5.5

isPartialLayout

public boolean isPartialLayout()

Returns true when the partial mode is enabled.

Since:

JViews 5.5

See Also:

setPartialLayout(boolean)

setIncrementalLayout

public void setIncrementalLayout(boolean incremental)

Enables or disables the incremental mode of the hierarchical layout. If this property is true, objects are selected, and the graph layout supports incremental mode, then the layout is performed using the incremental mode. The default value is false.

Parameters:

incremental - The new value.

Since:

JViews 5.5

See Also:

isIncrementalLayout()

isIncrementalLayout

public boolean isIncrementalLayout()

Returns true when the incremental mode is enabled.

Since:

JViews 5.5

See Also:

setIncrementalLayout(boolean)

setConstraintsURL

public void setConstraintsURL(URL url)

Sets the URL that specifies the layout constraints. Currently, only the hierarchical layout supports layout constraints.

Since:

JViews 6.0

getConstraintsURL

public URL getConstraintsURL()

Returns the URL of the file that specifies the layout constraints. Currently, only the hierarchical layout supports layout constraints.

Since:

JViews 6.0

reloadConstraintsURL

public void reloadConstraintsURL()

Reloads the URL that specifies the layout constraints. This method can be called if the URL of the constraints file has not changed, but the contents have changed. It causes the renderer to reload the constraint file from the URL.

Since:

JViews 6.0

writeConstraints

public void writeConstraints(PrintWriter writer)

Writes the layout constraints. Currently, only the hierarchical layout supports layout constraints. This method does nothing if the current layout is not the hierarchical layout.

The method should be called after rendering is done; otherwise, the constraints are not yet known to the renderer. For the hierarchical layout, it writes out all constraints that are currently known to the renderer, including those that were explicitly specified in the style sheet and those that were loaded from an URL.

Parameters:

writer - The writer.

Since:

JViews 6.0

See Also:

setConstraintsURL(java.net.URL)

readConstraints

public void readConstraints(Reader reader)
                     throws IOException

Reads the layout constraints. Currently, only the hierarchical layout supports layout constraints. This method does nothing if the current layout is not the hierarchical layout.

The method should be called after prepareRendering(ilog.views.sdm.IlvSDMEngine) or after setGraphLayout(ilog.views.graphlayout.IlvGraphLayout); otherwise, the graph layout instance is not yet attached and the method does nothing. This method is called if the constraint URL has changed, just before layout starts. If you call this method explicitly, you replace the constraints loaded from the URL by those specified by the reader.

Parameters:

reader - The reader.

Throws:

IOException

Since:

JViews 6.0

See Also:

setConstraintsURL(java.net.URL)

setPerformingLayoutOnZoom

public void setPerformingLayoutOnZoom(boolean b)

Specifies whether the layout algorithm should be applied every time the transformer of the reference view changes, or only when the data is initially rendered.

Parameters:

b - If true, the link layout will be performed every time the zoom factor of the view changes. Otherwise, the link layout is performed only when the data model is loaded or when new objects are added.

Since:

JViews 8.1

isPerformingLayoutOnZoom

public boolean isPerformingLayoutOnZoom()

Returns a boolean specifying whether the layout algorithm should be applied every time the transformer of the reference view changes, or only when the data is initially rendered.

Returns:

true if performing layout on zoom

Since:

JViews 8.1

needsViewListeners

protected boolean needsViewListeners()

Returns true, because this renderer needs to install listeners on all the views.

Overrides:

needsViewListeners in class IlvSDMRenderer

Since:

JViews 5.5

See Also:

IlvSDMRenderer.addViewListeners(ilog.views.IlvManagerView), IlvSDMRenderer.removeViewListeners(ilog.views.IlvManagerView)

addViewListeners

protected void addViewListeners(IlvManagerView view)

Adds the listeners that recompute the link layout when the view is zoomed or unzoomed.

Overrides:

addViewListeners in class IlvSDMRenderer

Parameters:

view - The manager view.

Since:

JViews 5.5

See Also:

IlvSDMRenderer.needsViewListeners()

removeViewListeners

protected void removeViewListeners(IlvManagerView view)

Removes the listeners that recompute the link layout when the view is zoomed or unzoomed.

Overrides:

removeViewListeners in class IlvSDMRenderer

Parameters:

view - The manager view.

Since:

JViews 5.5

See Also:

IlvSDMRenderer.needsViewListeners()