# Using Eclipse Layout

Compared to the two more basic variants, using the Eclipse Layout Kernel within Eclipse introduces the largest amount of general magic to the process. This page explains the basics of how the layout kernel performs automatic layouts. Based on these information, sub-pages then describe how to integrate your tool with the layout kernel by filling in the details the overview decided to best leave out.

## How Layout Works in Eclipse

Layout in Eclipse revolves around the `DiagramLayoutEngine`, which in turn builds upon the `IGraphLayoutEngine` interface that layout in pure Java revolves around. It adds a whole layer that is mainly concerned with three things: extracting the graph data from a given diagram editor that automatic layout should be run on, configuring automatic layout, running automatic layout (yes, we are full of surprises), and applying the layout information back to the editor. The layer can be customized to taste through dependency injection. We will come back to that topic in a few minutes.

The `DiagramLayoutEngine` class provides a number of overloaded static `invokeLayout(...)` methods. Contrary to the entry points in `IGraphLayoutEngine`, these methods do not expect an ElkGraph ready to throw at layout algorithms, but instead expect either the editor layout should be run on (as an `IWorkbenchPart`) or a diagram element displayed in an editor (as a simple `Object`). Extracting a ElkGraph from this is what connecting your editor to the Eclipse Layout Kernel is all about: your main task is to implement the `IDiagramLayoutConnector` interface whose job is exactly that.

Let’s assume that one of the `invokeLayout(...)` methods is called. The layout engine now checks if it knows about a layout connector that can translate the content of the workbench part or the diagram object itself into an ElkGraph. Layout connectors are registered with the diagram layout engine through the `org.eclipse.elk.core.service.layoutConnectors` extension point. In fact, this is not quite right. It is not the layout connector itself which is registered, but a class that implements `ILayoutSetup`. This class knows which workbench parts and / or diagram parts it supports and how to supply the correct layout connector implementation. This is where we come back to dependency injection: the setup does not create an `IDiagramLayoutConnector` directly, but instead creates an injector that knows how to do so. By configuring the injector appropriately, a lot of details of how the layout process works can be customized by supplying custom implementations of the different components involved in the process.

By now, the diagram layout engine has an `ILayoutConnector` which it can use to get its hands at an ElkGraph it can work with. In the easy case, your layout connector will have already setup the layout options on your ElkGraph such that everything is ready to go. However, ELK does support advanced configuration mechanisms which are explained in one of the sub pages.

The diagram layout engine now has a properly configured ElkGraph that automatic layout can be run on. Incidentally, this is exactly what the `IGraphLayoutEngine` expects, so the diagram layout engine now simply calls the graph layout engine to do the heavy layout lifting. Once that call returns, the ElkGraph contains all the layout information just calculated.

The only thing that remains to be done is to apply the calculated layout information stored in the ElkGraph back to the diagram we originally wanted to invoke layout on. This again is the job of the `IDiagramLayoutConnector` implementation the diagram layout engine found at the beginning. Once that job is done, the layout run is complete and the call to `invokeLayout(...)` returns.

- Tool Developers
- Graph Data Structure
- Coordinate System
- Layout Options
- JSON Format
- ELK Text Format
- Using Algorithms Directly
- Using Plain Java Layout
- Using Eclipse Layout
- Connecting to ELK
- Advanced Configuration
- Layout View Support
- Dependency Injection
- Algorithm Developers
- Getting Eclipse Ready
- Creating a New Project
- ELK Metadata Language
- Automatic Builds
- Algorithm Implementation
- Structuring Algorithms
- Algorithm Debugging
- ELK Contributors
- Development Setup
- Development Workflow
- Installing With Oomph
- Building ELK