...

The options manager collects all available and applicable layout configurators and sorts them by priority. For every graph element, each configurator is asked to provide layout options, starting with the one with lowest priority and working through the priority chain. Hereby configurators with higher priority are able to override values set by those with lower priority.

A Few Details on Layout

...

Configurators

What we just learned is a bit of a simplification of what happens. Before we look at the details, let's take a look at the methods each layout configuration configurator provides:

public interface ILayoutConfig {
    int getPriority();
    voidObject enrichgetOptionValue(LayoutOptionData optionData, LayoutContext context);
    ObjectCollection<IProperty<?>> getValue(LayoutOptionData<?> optionData, getAffectedOptions(LayoutContext context);
    voidObject transferValuesgetContextValue(KLayoutDataIProperty<?> layoutDataproperty, LayoutContext context);
} 

It is not hard to guess what getPriority() does: it returns the priority a given layout configuration has. If two layout configurations set a layout option to different values on a given graph element, the value set by the configuration with higher priority wins. The other three methods look a bit more obscure, so we have to provide more details on what the options manager does, exactly.

ENRICHING (+ WHAT IS A LAYOUT CONTEXT)

The transferValues(...) method is the main workhorse of the interface. This is where a KGraph element, identified by the given layout context, is equipped with the layout option values a layout configuration deems necessary. It thus becomes the most important part of a layout configuration that you absolutely have to implement, no excuses. If for example every KNode should have its port constraints set to FIXED_POS, this is the place to do it.

With all these layout configurations active, it's by no means clear which layout option values KGraph elements will end up with during the layout process. Enter the getValue(...) method. For a given element and layout option, it returns the value it would set on the element if transferValues(...) was called. This method is mainly used by the Layout view to inform the user about the layout option values of whatever graph element he (or she) has clicked on. It is also the method you can safely neglect to implement if your final product won't include the layout view anyway.

Implementing a Layout Configuration

...

...

The interface discerns between option values and context values. Option values are what we have been talking about all the time, values assigned to layout options. Which particular values the configurator should apply depends on the given LayoutContext, which is a property holder with references to the diagram element currently in focus. For instance, the object representing an element in the diagram viewer is accessed with context.getProperty(LayoutContext.DIAGRAM_PART). Similarly, the corresponding KGraph element is mapped to the property LayoutContext.GRAPH_ELEM, and the domain model element is mapped to LayoutContext.DOMAIN_MODEL. Each configurator is free to put additional information into the context, caching it for faster access and enabling to communicate it to other configurators. getAffectedOptions(LayoutContext) should return a collection of layout options for which the configurator yields non-null values with respect to the given context. The options can be referenced either with LayoutOptionData instances obtained from the LayoutMetaDataService or with Property instances from the constants defined in LayoutOptions. The actual value for a layout option is queried with getOptionValue(LayoutOptionData, LayoutContext). The method getContextValue(IProperty, LayoutContext), in contrast, is used to obtain more detailed information on the given context. For instance, the context may contain a reference to an element of the diagram viewer; only a specialized configurator made for that diagram viewer knows how to extract a reference to the corresponding domain model element from the given diagram element, so it can encode this knowledge in getContextValue(…) by returning the domain model element when the given property corresponds to LayoutContext.DOMAIN_MODEL.

This may seem complicated, and it is, but the good news is that the vast majority of developers will not need to dig that deep into the layout configuration infrastructure. There are easier ways to specify configurations, as described in the following section.

Programmatically Setting Layout Options

So with all these layout configurations configurators available, how do you actually go about setting layout options programmatically? Well, as always: it depends.

...