Using nested graphers

Explains how to establish the coordinate system that applies to an intergraph link and how to compute the connection points.

Explains the appearance of intergraph links to a grapher when the grapher is collapsed and how to obtain the end nodes of such links.

As a subclass of a manager, a grapher (instance of IlvGrapher) inherits all the behavior of managers, including nesting.

A grapher can be nested in another grapher or in a manager. It can be collapsed or expanded, and a frame can be set on it.

In addition to having the features inherited from the IlvManager class, nested graphers allow you to create applications that define graphs containing subgraphs, with links crossing the graph boundaries (intergraph links).

An intergraph link is a link that crosses grapher boundaries. In other words, an intergraph link is a link whose origin and destination are in different graphers.

Some examples of intergraph links are shown in the following figure.

In this picture the red (darker) links are intergraph links and the yellow (light) links are regular links.

To be able to create intergraph links, you must have a hierarchy of nested graphers (IlvGrapher). The hierarchy should not contain a manager ( IlvManager); otherwise the library will not let you create an intergraph link.

Creating an intergraph link

Given that an intergraph link has an origin and a destination in different graphers, the question that arises is in which grapher the link is stored. The intergraph link between a node stored in grapher A and a node stored in grapher B must be stored in the first common ancestor of A and B, as shown in the following figure.

In this figure, the red intergraph link that connects an object of A and an object of B must be stored in grapher C, the first common ancestor of A and B.

The IlvGrapher class provides a static utility method that allows you to determine the first common grapher:

To create an intergraph link, the code will look like this (assuming that the origin and destination variables have been created and added in different graphers):

The IlvGrapher.addInterGraphLink static utility method allows you to add the link directly to the common parent grapher:

The code shown in the previous example is equivalent to:

Accessing an intergraph link

The IlvGrapher class also provides methods that let you access intergraph links stored in a grapher in an efficient way:

Since an intergraph link is stored in the same way as other links in the grapher, it is also part of the list of all objects contained in this grapher returned by the getObjects method of the class IlvManager:

Nevertheless, calling the getInterGraphLinks method is much more efficient than traversing all objects of the grapher.

To distinguish an intergraph link from other objects in the grapher, you can use the following method of the IlvGrapher class:

This method returns true if the specified graphic object is a link stored in the grapher instance with the origin or the destination stored somewhere else. That is, if the graphic object is an intergraph link.

The IlvGrapher class also gives you access to intergraph links that are leaving or entering a grapher. You can access such links using the methods:

The difference between the methods getInterGraphLinks and getExternalInterGraphLinks is:

The first method, getInterGraphLinks, returns the intergraph links stored in a grapher with an origin or destination in another grapher

The second method, getExternalInterGraphLinks, returns the intergraph links stored in another grapher but with the origin or destination in this grapher

If the grapher has no subgraphers, the external intergraph links obtained by getExternalInterGraphLinks() are all links that are leaving or entering the grapher.

If the grapher has subgraphers, the intergraph links that leave the grapher have one of the following characteristics:

Calling getExternalInterGraphLinks() on the grapher gives only the links with an end node in the grapher, not the links with an end node in a subgrapher of the grapher.

In this case, links that are leaving or entering the nesting hierarchy of the grapher can be obtained by examining all external intergraph links of the subgraphers recursively. To help in this task the following convenience methods are supplied: getTreeExternalInterGraphLinks and getTreeExternalInterGraphLinksCount.

When a grapher is moved, it is possible that the grapher and all its nested subgraphers appear at a new location on the screen. The grapher displacement causes the shape of the following links to change:

All links that are directly connected to the grapher. That is, have the grapher as origin or destination.

The following figure illustrates interlinked nested graphers:

Grapher A contains two graphers, B and D. Grapher B contains another grapher, C. The intergraph link from an object of C to an object of D is then stored in A.

This link is an intergraph link of A (returned in getInterGraphLinks called on A) and is also an external intergraph link of C and D (returned by getExternalInterGraphLinks called on C or D).

Neither the origin nor destination of the intergraph link ends in grapher B, and thus this link is not returned by calling getExternalInterGraphLinks on B. However, the link is returned by calling getTreeExternalInterGraphLinks on B, since its origin node is nested inside B.

Since an intergraph link has its origin and destination in different graphers, it may be difficult to determine the coordinate system in which the bend points of an intergraph link are defined.

The coordinate system of the link and its bend points is always the coordinate system of the grapher to which the link has been added. The only difference compared to regular links is the way an intergraph link computes its end points: the connection points of the link to its origin and destination. The link itself, in fact the base class of the IlvLinkImage class, computes its connection points by calling:

This method determines whether the link connector ( IlvLinkConnector) is installed on the destination or origin node, by calling:

The getConnectionPoints method stores the result in the src and dst parameters. If the link is an intergraph link, this method will compute the connection points in the coordinate system of the origin and destination nodes.

In this method the origin parameter is true for computing the connection point at the origin of the link and false for the destination of the link, and the t parameter is the transformer used to draw the link.

This method returns true if a link connector is installed. If no link connector is installed, a default connection point is computed. If a link connector is installed, the link connector then computes the connection point with the method:

When the link is a regular link, the t parameter is the transformer used to draw the link. This is the same as the transformer used to draw the origin and destination.

When the link is an intergraph link, then the t parameter is the transformer used to draw the origin or destination.

So when developing a new class of links or link connectors, there is no special work to be done to take into account the specific case of intergraph links.

When a grapher is collapsed, the graphic objects that it contains are no longer visible on the screen. The nodes that are the destination and origin of an intergraph link are not visible on the screen, and thus such intergraph links cannot visually point to their end nodes. These intergraph links will instead point to the collapsed representation of the grapher on the screen.

The following figures show an example of intergraph links to a grapher when it is expanded and then when it is collapsed.

Although the links point visually to the collapsed representation of the manager once the manager is collapsed, the real origin and destination of the links do not change. The methods getFrom and getTo of the link ( IlvLinkImage) still return the same object. Only the graphical representation changes. The link visually points to the first expanded parent manager.

You could consider that the methods getFrom and getTo of the link return the real end nodes of the link. The nodes that appear visually as end nodes on the screen can also be obtained by using the methods getVisibleFrom and getVisibleTo of the link. If there are no collapsed managers, the visible end nodes and the real end nodes are always the same

For a given node, all links that have the node as visible end node can be obtained by the methods:

The links that have it as real end node are obtained by the methods:

In Intergraph links to a collapsed grapher, two links have the visible destination node pay for supplies, but their real destination node is the inner node of pay for supplies, which is not visible in Intergraph links to a collapsed grapher, but can be seen in Intergraph links to an expanded Grapher.

If a manager is collapsed, the position of the connection point of the link is determined by the link connector installed on the collapsed manager and not by the ones installed on the real end nodes.

As well as creating an intergraph link by code, it is possible to create intergraph links (and also regular links) using the IlvMakeLinkInteractor.

When this interactor is installed, it allows you to interactively create a link from any graphic object to any other graphic object. This allows you to create intergraph links and also links to or from a nested grapher.