Eclipse Layout Kernel Documentation

Using Plain Java Layout

While layout algorithms can be called directly, it is usually a better idea not to do so except in the simplest of cases. There are several reasons for that:

  1. When calling a layout algorithm directly, your code is hardwired to that implementation and looses a bit of flexibility.

  2. Most importantly, as graphs get more complex there are more and more details to be aware of when executing layout. This is especially true for compound graphs: graphs with nodes that contain further graphs themselves.

The best way to invoke automatic layout is through a fully-fledged implementation of IGraphLayoutEngine. ELK provides a convenient implementation: the RecursiveGraphLayoutEngine. But before we can explain that, we need to provide a big of background regarding the LayoutMetaDataService.

The Layout Meta Data Service

To know about which layout algorithms and layout options are available, ELK keeps a central registry of layout meta data: the LayoutMetaDataService. The recursive graph layout engine looks at which layout algorithm should layout a given part of the layout graph and uses the meta data service to obtain an instance of that algorithm.

When running in an Eclipse context, the meta data service is magically populated. In a plain Java application, you will have to populate the service yourself. Layout meta data are provided by ILayoutMetaDataProviders. What you need to do is to obtain an instance of each relevant meta data provider and register it with the meta data service.

One such meta data provider is always automatically registered: CoreOptions. This will give you access to our most basic layout algorithms: Fixed Layout, Box Layout, and Random Layout (at the time of writing). To use more layout algorithms, you will have to find the algorithm’s implementation of ILayoutMetaDataProvider and register that. For example, using ELK Layered requires the following registration:

LayoutMetaDataService service = LayoutMetaDataService.getInstance();
service.registerLayoutMetaDataProvider(new LayeredOptions());

Using the Recursive Graph Layout Engines

When using the recursive graph layout engine, there is exactly one important method to be aware of:

void layout(KNode layoutGraph, IElkProgressMonitor progressMonitor);

This method provides the entry point to automatic layout and applies the layout algorithms as configured in the layout graph (more details below). To get everything working, follow these steps after you have populated the layout meta data service:

  1. Create a KGraph to be laid out (see our graph documentation for how to do so). The KGraph will be based on the diagram you want your application to display.

  2. Configure which layout algorithm should be used to layout your graph and how the layout algorithm should layout your graph by setting layout options on the graph’s elements. Check the documentation of the layout algorithm you want to use for which layout properties it supports and what they do, exactly.

  3. Obtain an instance of RecursiveGraphLayoutEngine and call its layout(...) method. Pass it the graph to be laid out as well as a progress monitor to track progress. The progress monitor will allow users to see how long layout will take and to cancel the operation. If you do not care to provide your own progress monitor, simply use BasicProgressMonitor, which is our default implementation. Once the layout(...) method returns, the result will be stored in the layout-related fields of the graph.

  4. Either keep the graph layout engine around to be used again or throw it away.