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 10.60. 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 10.48, “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 10.48. Data provider look-up keys

Key Element Type Value Type Description
DirectedEdgeDpKey edge bool For each edge a boolean value indicating whether it should be routed having main layout direction.
EdgeLabelLayoutDpKey edge LabelLayoutData[] For each edge an array of LabelLayoutData objects that encode size and preferred placement for all labels of the edge.
EdgeLayoutDescriptorDpKey edge EdgeLayoutDescriptor For each edge an EdgeLayoutDescriptor object that configures edge-related options.
SourceGroupIdDpKey edge object For each edge an arbitrary object indicating the group its source end is affiliated with.
TargetGroupIdDpKey edge object For each edge an arbitrary object indicating the group its target end is affiliated with.
NodeHaloDpKey node NodeHalo A NodeHalo object that specifies the halo sizes at each side of a node.
AbortHandlerDpKey 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
int Grid { get; set; }
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
bool UseSketchDrawing { get; set; }
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:

Edge Layout Descriptor
API
EdgeLayoutDescriptor EdgeLayoutDescriptor { get; set; }
Description Edge-related layout options.

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 DirectedEdgeDpKey.

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

Example 10.29. Configuring the main layout direction

// 'dol' is of type yWorks.yFiles.Layout.Orthogonal.DirectedOrthogonalLayouter.

// Set the main layout direction using the OrientationLayouter provided by
// CanonicMultiStageLayouter (the superclass of DirectedOrthogonalLayouter).
OrientationLayouter ol = (OrientationLayouter)dol.OrientationLayouter;
ol.Orientation = LayoutOrientation.LeftToRight;

// Invoke the layouter.
graph.ApplyLayout(dol);

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 SourceGroupIdDpKey and TargetGroupIdDpKey, 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 property:

bool IntegratedEdgeLabeling { get; set; }
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
bool ConsiderNodeLabels { get; set; }
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 10.49. Data provider look-up keys

Key Element Type Value Type Description
NodeHaloDpKey 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
double MinimumFirstSegmentLength { get; set; }
double MinimumLastSegmentLength { get; set; }
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 EdgeLayoutDescriptorDpKey. 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 10.50. Data provider look-up keys

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

Applicable Layout Stages

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

Table 10.51. 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

The layout module class DirectedOrthogonalLayoutModule.cs from the LayoutModulesWindow demo application presents the setup of class DirectedOrthogonalLayouter in an application context.