Where to Find Up-to-date yFiles Information

This page is from the outdated yFiles for Java 2.13 documentation. You can find the most up-to-date documentation for all yFiles products on the yFiles documentation overview page.

Please see the following links for more information about the yFiles product family of diagramming programming libraries and corresponding yFiles products for modern web apps, for cross-platform Java(FX) applications, and for applications for the Microsoft .NET environment.

More about the yFiles product family Close X

Directed Orthogonal Layout

Class DirectedOrthogonalLayouter is an orthogonal layout provider that generates drawings with a strong focus on edge routing that satisfies sophisticated edge path-related constraints. It supports advanced edge path generation

The latter is also referred to as edge/port grouping, which is described in the section called “Edge/Port Grouping (Bus-Style Edge Routing)”.

Together these features enable high-quality graph layout which is a perfect match for UML-style class diagrams, for example. The layout algorithm is well suited for medium-sized graphs where a subset of edges should be routed with respect to the main layout direction. It produces compact drawings with no overlaps and few crossings.

Figure 5.70. Sample layout produced by class DirectedOrthogonalLayouter

Sample layout produced by class DirectedOrthogonalLayouter
A diagram with UML-style edge routing and edge groups.

Supplemental Layout Data

Class DirectedOrthogonalLayouter knows a number of data provider keys which are used to retrieve supplemental layout data for a graph's elements. The data is bound to the graph by means of a data provider, which is registered using a given look-up key. Table 5.51, “Data provider look-up keys” lists all look-up keys for DirectedOrthogonalLayouter.

Binding supplemental layout data to a graph is described in the section called “Providing Supplemental Layout Data”.

Table 5.51. Data provider look-up keys

Key Element Type Value Type Description
DIRECTED_EDGE_DPKEY Edge boolean For each edge a boolean value indicating whether it should be routed having main layout direction.
EDGE_LABEL_LAYOUT_KEY Edge LabelLayoutData[] For each edge an array of LabelLayoutData objects that encode size and preferred placement for all labels of the edge.
EDGE_LAYOUT_DESCRIPTOR_DPKEY Edge EdgeLayoutDescriptor For each edge an EdgeLayoutDescriptor object that configures edge-related options.
SOURCE_GROUPID_KEY Edge Object For each edge an arbitrary Object indicating the group its source end is affiliated with.
TARGET_GROUPID_KEY Edge Object For each edge an arbitrary Object indicating the group its target end is affiliated with.
NODE_HALO_DPKEY Node NodeHalo A NodeHalo object that specifies the halo sizes at each side of a node.
ABORT_HANDLER_DPKEY Graph AbortHandler An AbortHandler instance that will be queried by the layout algorithm to determine whether layout calculation shall be terminated.

Layout Options

Unlike the more general orthogonal layout algorithm this specialized layout algorithm provides only few options.

Grid
API
void setGrid(int gridSpacing)
Description Defines the virtual grid spacing used by the layouter. Each node will be placed in such a way that its center point lies on a grid point. Edges will be routed in such a way that their segments lie on grid lines, if the terminal nodes of the edges allow to place the ports accordingly.
Use Existing Drawing as Sketch
API
void setUseSketchDrawing(boolean useSketch)
Description If enabled, the layout algorithm will interpret the initial graph layout as a sketch of the resulting orthogonal layout. The layout algorithm tries to "orthogonalize" the given sketch without making too much modifications with respect to the original drawing.

Class EdgeLayoutDescriptor can be used to specify further edge-related layout options. An instance of this class is held by DirectedOrthogonalLayouter to store and retrieve default values for edges.

DirectedOrthogonalLayouter provides access to the default EdgeLayoutDescriptor instance through:

In addition to the instance held directly by DirectedOrthogonalLayouter, layout descriptors can also be associated with single edges in order to specify individual settings for them. Setting individual descriptors for edges is done through a data provider that is bound to the graph. See Related Classes.

Advanced Layout Concepts

Directed Edges

To specify the subset of so-called "directed" edges that should be routed with respect to the main layout direction, a data provider holding such supplemental layout data must be bound to the graph. The data provider is expected to be registered with the graph using key DIRECTED_EDGE_DPKEY.

The main layout direction can be configured using the services of class OrientationLayouter as outlined in Example 5.36, “Configuring the main layout direction” Note that the default layout direction is top-to-bottom.

Example 5.36. Configuring the main layout direction

// 'dol' is of type y.layout.orthogonal.DirectedOrthogonalLayouter. 

// Set the main layout direction using the OrientationLayouter provided by 
// CanonicMultiStageLayouter (the superclass of DirectedOrthogonalLayouter). 
OrientationLayouter ol = (OrientationLayouter)dol.getOrientationLayouter();
ol.setOrientation(OrientationLayouter.LEFT_TO_RIGHT);

// Invoke buffered layout. 
new BufferedLayouter(dol).doLayout(graph);

Edge/Port Grouping (Bus-style Edge Routing)

A special feature of the directed orthogonal layout algorithm is its ability to group multiple ports (edge end points) together to be anchored at the same location. This can be specified for both source ports and target ports.

Edges that belong to the same group at a specific end will additionally be routed in bus-style.

To specify source groups and/or target groups for sets of edges, data providers holding such supplemental layout data must be bound to the graph. The data providers are expected to be registered with the graph using keys SOURCE_GROUPID_KEY and TARGET_GROUPID_KEY, respectively. The setup of edge groups is described in the section called “Edge/Port Grouping (Bus-Style Edge Routing)”.

Integrated Labeling

Besides the generic labeling support as described in the section called “Generic Labeling”, which is available with all yFiles layout algorithms, directed orthogonal layout additionally supports integrated labeling.

Integrated labeling is available for edge labels. They are taken into consideration when determining both node placement and edge path generation. With this strategy it is guaranteed that no edge label will overlap other objects in the diagram.

Integrated labeling can be enabled or disabled using the following setter method:

boolean isIntegratedEdgeLabelingEnabled()
void setIntegratedEdgeLabelingEnabled(boolean enabled)
Description Determines whether integrated labeling is enabled.

See also the section called “Integrated Labeling”.

Tip

Optimal label placement with integrated labeling can be achieved using FreeEdgeLabelModel as the label model for the edges. As explained in the section called “Label Models”, this edge label model is ideally suited in combination with integrated labeling and yields the best match for a label location that is computed by DirectedOrthogonalLayouter.

Node Label Awareness

DirectedOrthogonalLayouter provides support for node label-aware orthogonal layout. Node labels do not need to be placed, but instead their size needs to be considered for the placement of adjacent graph elements. Taking node labels into consideration during layout calculation guarantees that they will not overlap nodes in the diagram.

Consider Node Labels
API
void setConsiderNodeLabelsEnabled(boolean enabled)
Description Enables node label-aware layout calculation.

Node Halos

DirectedOrthogonalLayouter supports node halos as soon as they are declared. During layout calculation, it takes any specified additional paddings around nodes into consideration and keeps the areas clear of other graph elements. The labels of a node and its adjacent edge segments are not affected and can still be placed inside or cross the node's halo.

The following table lists the data provider look-up keys that are recognized by DirectedOrthogonalLayouter in conjunction with node halo support.

Table 5.52. Data provider look-up keys

Key Element Type Value Type Description
NODE_HALO_DPKEY Node NodeHalo A NodeHalo object that specifies the halo sizes at each side of a node.

Related Classes

Class EdgeLayoutDescriptor can be used to configure edge-related layout options. The following options can be set for edges:

Minimum Length of First and Last Segment
API
void setMinimumFirstSegmentLength(double length)
void setMinimumLastSegmentLength(double length)
Description Determine the minimum length of the first (at the source) and last (at the target) edge segment.

An EdgeLayoutDescriptor instance can be specified individually for single edges by means of a data provider that is bound to the graph. The data provider is expected to be registered with the graph using key EDGE_LAYOUT_DESCRIPTOR_DPKEY. In the absence of an individual descriptor for an edge, the default EdgeLayoutDescriptor instance that is registered with DirectedOrthogonalLayouter will be used.

The following table lists the data provider look-up keys that are recognized by DirectedOrthogonalLayouter in conjunction with individual layout settings for edges.

Table 5.53. Data provider look-up keys

Key Element Type Value Type Description
EDGE_LAYOUT_DESCRIPTOR_DPKEY Edge EdgeLayoutDescriptor For each edge an EdgeLayoutDescriptor object that configures edge-related options.

In tutorial demo application EntityRelationshipDemo.java individual EdgeLayoutDescriptor instances are used to specify the minimum length of the first/last edge segment in relation to the length of the arrowhead at that end.

Applicable Layout Stages

Table 5.54, “Layout Stages” lists layout stages that can be used to enhance the layout process of class DirectedOrthogonalLayouter.

Table 5.54. Layout Stages

Classname Description
PolylineLayoutStage With class DirectedOrthogonalLayouter as the core layouter, this stage adds octilinear edge routing to the diagram that results from the orthogonal layout calculation.

Tutorial Demo Code

Layout module DirectedOrthogonalLayoutModule.java presents the setup of class DirectedOrthogonalLayouter in an application context. Tutorial demo application UMLClassDiagramLayouterDemo.java shows how the directed orthogonal layout algorithm can be used to generate UML class diagrams.

In tutorial demo application EntityRelationshipDemo.java individual EdgeLayoutDescriptor instances are used to specify the minimum length of the first/last edge segment in relation to the length of the arrowhead at that end.