Contact points
Describes how to use hyperedge connectors and calculate contact points, and discusses visible and invisible hyperedge connectors, hyperedge pin connectors, and other predefined types of hyperedge connectors.
Provides an overview of hyperedge connectors and their contact points.
Describes the class used to define hyperedge connectors.
Defines the methods used to create or manipulate hyperedges and shows how to implement a new hyperedge connector and retrieve the end points of a hyperedge.
Discusses the distinctions between visible and invisible hyperedge connectors, and the different methods used to work with them.
Describes the subclass and methods used to define hyperedge pin connectors.
Lists additional predefined hyperedge connectors available in Rogue Wave® JViews Diagrammer.
Overview
A hyperedge connects the nodes at the point retrieved by the method
getPosition. The default implementation
IlvDefaultHyperEdgeEnd stores the connection in the end itself, relative to the node position. If the node is moved, the hyperedge end will follow the node. The stored connection point can be moved freely by a call to
setPosition.
The effect is similar to that of
IlvFreeLinkConnector on
IlvLinkImage.
There is a facility for restricting the connection point to certain predefined points by using the hyperedge connector. For example, you can restrict the connection to pin points on the node border or to the center of the node. When a hyperedge connector is used, the connection point is no longer freely movable. It is controlled by the hyperedge connector, which decides whether and how the connection point can be changed.
Using hyperedge connectors
The purpose of the class
IlvHyperEdgeConnector is comparable to that of the class
IlvLinkConnector for links. The class
IlvHyperEdgeConnector is the base class of all hyperedge connectors. It computes the connection points of
IlvHyperEdge objects at nodes. Subclasses of the abstract base class
IlvHyperEdgeConnector can be implemented to obtain different contact points.
A hyperedge connector can be attached to a hyperedge or to a node.
If it is attached to a hyperedge, it will control all connection points of this hyperedge at the nodes.
If it is attached to a node, it will control all connection points of hyperedges at the node, except for those hyperedges that do not have their own connector.
To specify that a hyperedge connector is to be used:
1. Allocate the connector.
2. Attach it to the node (see the following code example).
Example 11 – Attaching a hyperedge connector to a node
IlvHyperEdgeConnector connector = new IlvHyperEdgeCenterConnector();
connector.attach(node, redraw);
-- or --
Attach it to the hyperedge (see the following code example).
Example 12 – Attaching a hyperedge connector to a hyperedge
IlvHyperEdgeConnector connector = new IlvHyperEdgeCenterConnector();
connector.attach(hyperedge, redraw);
The same hyperedge connector cannot be shared between several nodes or hyperedges. You need to allocate a new connector for each node or each hyperedge.
If you want to stop using a hyperedge connector, detach it:
connector.detach(redraw);
When you attach or detach a hyperedge connector, the end points of the hyperedges can change. Therefore, you must specify by using the redraw flag whether the hyperedges are to be redrawn.
To access a hyperedge connector that is responsible for a specific hyperedge end:
Use the call shown in the following code example:
Example 13 – Accessing the hyperedge connector for a specific hyperedge end
IlvHyperEdgeEnd hyperEdgeEnd = ...
IlvHyperEdgeConnector connector = IlvHyperEdgeConnector.Get(hyperEdgeEnd);
The call to this method returns the connector of the hyperedge that has the specified end or, if the edge has no connector, it will return the connector of the node connected to that end. If it returns null, no connector at all is used.
To access the connector attached to a specific node or hyperedge:
Use the call shown in the following code example:
Example 14 – Accessing the hyperedge connector for a specific node or hyperedge
IlvHyperEdgeConnector connector =
IlvHyperEdgeConnector.GetAttached(nodeOrHyperEdge);
The call to this method returns the hyperedge connector of the node or of the hyperedge, even if this hyperedge connector is not currently responsible for the calculation of the end points of any hyperedge.
Calculating contact points
Interactors that allow you to create or manipulate hyperedges typically call the following methods of
IlvHyperEdgeConnector to connect a hyperedge end to or disconnect it from a node:
To implement a new hyperedge connector:
Call the methods:
This method is called when a hyperedge end needs to be connected to a node at position p. This position might be unsuitable for the connector. Therefore, the method getClosestConnectionPoint can return the closest suitable connection point. It can be useful to store this connection point internally in the connector, so that it can be retrieved quickly.
-- or --
This method is called when a hyperedge end is already connected. It returns the connection point for the hyperedge end. This can be the connection point that was previously stored. If no connection point was previously stored, the method must calculate an appropriate connection point for the end.
When the disconnect method is called, the storage of the connection point can finally be cleared to avoid memory leaks.
NOTE The class
IlvHyperEdgeConnectorWithCache implements hyperedge connectors with a cache storage for connection points that handles the storing and cleaning up of the cache automatically.
To retrieve the end points of a hyperedge:
Call the method:
If the flag checkConnector is true, this method asks the connector for the position by calling getConnectionPoint at IlvHyperEdgeConnector.
If the flag checkConnector is false, the method does not ask the connector for the position.
Usually, when a hyperedge is drawn or manipulated, the value true is always passed for the parameter checkConnector. Therefore, the hyperedge ends at the point returned by getConnectionPoint from the connector.
Visible and invisible hyperedge connectors
In contrast to
IlvLinkConnector, the class
IlvHyperEdgeConnector is a subclass of
IlvGraphic and can display the contact points in the hypergraph. For example, it is useful to display the pins of a pin connector permanently at the nodes that represent electrical circuits in a signal diagram.
Not all subclasses of IlvHyperEdgeConnector use this facility. Like IlvGraphic, some connector classes need to display visible parts. Like IlvLinkConnector, other connector classes are only a logical computation facility for the contact points. Thus, the class IlvHyperEdgeConnector is a mix of a graphic object and a connection calculation algorithm.
Visible hyperedge connectors need to implement the method
isGraphic to return true. They also need to implement all the usual methods of
IlvGraphic, namely
draw,
boundingBox, and
contains.
Invisible hyperedge connectors need to implement the method isGraphic() to return false. They do not need to implement the usual methods of IlvGraphic, because when isGraphic() returns false these connectors will not be used as graphic objects.
Visible hyperedge connectors can only be attached to nodes, not to hyperedges. The position of a visible hyperedge connector is always the same position as the node. When the node is moved, the hyperedge connector is automatically moved with the node. When the node is removed or inserted into a different hypergraph, the hyperedge connector is automatically removed and inserted into the same hypergraph as the node; that is, you need only to attach the connector to the node and the entire handling of the hyperedge connector as a graphic object is done automatically.
The only predefined visible hyperedge connector is
IlvHyperEdgePinConnector. All other predefined hyperedge connectors are invisible connectors. See
IlvHyperEdgeConnector for additional information.
Hyperedge pin connectors
The subclass
IlvHyperEdgeConnector allows hyperedges to connect to pins at the node. (See the following figure.) Optionally, the pins can be visible. Thus, the pin connector is a visible connector, that is,
isGraphic returns true. The pin connector contains a set of pins.
Pin connector
A pin is implemented by the class
IlvHyperGrapherPin or its subclasses. Before a pin can be used, it must be added to the corresponding pin connector. The API of
IlvHyperEdgePinConnector includes the methods listed in the following table.
Methods of IlvHyperEdgePinConnector
Method | Description |
| Adds the pin to the hyperedge pin connector. If the redraw flag is true and the pin is visible, it will be redrawn. |
| Removes the pin from the hyperedge pin connector. If the redraw flag is true and the pin was visible, the area of the pin will be redrawn. |
| Returns all pins of the hyperedge pin connector. |
| Returns the number of pins in the hyperedge pin connector. |
| Returns the closest pin that is suitable for the hyperedge end at the input point p. |
| Connects the hyperedge end to the input pin. The pin must belong to the hyperedge pin connector. The connector must be attached to a node and the hyperedge end must point to this node. |
The class IlvHyperGrapherPin is a concrete class that is ready to use. It displays a pin as a small rectangle at the border of the node.
You can also create subclasses of
IlvHyperGrapherPin. You can specify whether it is possible to connect only one or several hyperedge ends to the same pin. You can restrict even more tightly which hyperedge ends can connect to a pin by overriding the method
allow.
The API of IlvHyperGrapherPin includes the methods listed in.
Methods of IlvHyperGrapherPin
Method | Description |
| Returns the hyperedge ends that are currently connected to the pin. |
| Tests whether the input hyperedge end is connected to this pin. |
| Returns whether the hyperedge end is allowed to be connect to the pin. |
| Returns the position of the pin in transformed view coordinates. |
| Sets the position of the pin in transformed view coordinates. |
| Sets whether the pin is currently selected. A selected pin is drawn in a different color from unselected pins. Usually, pins get selected during interactions that manipulate pins. |
| Sets whether the pin is movable interactively. Interactors check whether pins are movable before calling setPosition on the pin. |
| Sets whether multiple hyperedge ends can be connected to the same pin. If false is passed, a different pin must be used for each hyperedge end. |
The position of the pin is the position where the pin is drawn. It is the center point of the pin, since pins can have a size.
To create a pin, use the constructor:
IlvHyperGrapherPin(IlvPoint proportionalLocation,
IlvPoint absoluteLocation,
float size,
int direction)
The position of the pin is specified by a proportional part and by an absolute part. The proportional part is a position relative to the bounding box of the node. If the proportional location is (0,0), it will be the upper left corner of the node. If the proportional location is (1,1), it will be the lower right of the node. The real position is calculated in the following way:
pin.position = node.position + proportionalLocation * node.size + absoluteLocation
Hyperedges can connect to the pin position (the center point of the pin). Since pins have a size, it is sometimes useful to connect the hyperedges to a different point. If the pin is on the left side of the node, it is better to connect the hyperedge to the left side of the pin. If the pin is on the right side of the node, it is better to connect the hyperedge to the right side of the pin.
This behavior can be controlled by a direction parameter passed to the constructor of the pin. If you pass the direction 0, the pin will decide heuristically which is the best point of the pin to connect a hyperedge to.
Other predefined hyperedge connectors
Other hyperedge connectors are available as shown in the following table.
These hyperedge connectors are invisible connectors, that is,
isGraphic returns false.They can be attached to nodes and hyperedges.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
