This subproject deals with the automatic layout of graph-based models. The term meta layout relates to the idea of specifying the layout of a diagram on an abstract level, while concrete layout information is calculated by layout algorithms.

Getting Started

In order to use KIML with your own GMF-based editor, you need to do the following steps:

1. Install the "KIELER Layout for GMF" feature from our update site, see Downloads
   • It includes the Java-based layout algorithms developed in the KLay project.
2. Open a diagram and press the layout button  or use the shortcut Ctrl+R L.

For development with the KIML plug-ins, check out using team project sets:

•  Project set for KIML with GMF
•  Project set for KIML with Graphiti

Introduction

User Interface

The main user interface element of KIML is the command to layout the current diagram. This command is availabe in the main KIELER menu, in the toolbar (), or using the Ctrl+R L shortcut. Additionally, an entry in the context menu allows to layout only a selected part of the diagram.

Layout View

The Layout view allows flexible customization of layout options for the selected objects in the diagram. If no object is selected, the view shows the options for the top-level container of the diagram. Options are stored persistently in the notation model of the diagram, so that they are still available after the next Eclipse restart. Of course this requires the diagram to be saved after an option was changed.

The options are grouped according to the function of the selected objects. The group Nodes (respectively Edges, Ports, or Labels) contains options related to the object itself, such as its size or priority, while the groupParents contains options for the elements contained in the selected objects, such as the applied layout algorithm or the spacing between elements. Which layout options are displayed depends on the types of selected objects and the active layout algorithm, since such algorithms may not support all kinds of options. Furthermore, some options are only visible if the Show Advanced Properties button in the view toolbar is activated. The group types can be hidden using the Show Categories button.

An option can be changed by selecting or entering a new value in the corresponding cell of the Value column. The most important option is Layout Algorithm, which is used to determine the layout algorithm for the contents of the selected element. Here either a specific layout algorithm or a layout type can be chosen; in the latter case, the most suitable layout algorithm of the given type is taken. By changing the active layout algorithm, the content of the layout view is updated to display only those options that are supported by the new layout algorithm.

Selecting Restore Default Value in the context menu or the view toolbar removes any value for the currently selected option that is stored in the open model file, thus resetting the option to its default value. The view menu has an entry Remove all Layout Options which resets all options by removing persistent data in the model file.

The context menu for a specific layout option has different alternatives to set the current value as default value: Set as Default for this Diagram changes the open model file so that the same value is applied to all similar objects of that model. Set as Default for ... in this Context applies the value to all similar objects that are displayed with the same diagram editor (the option is linked to the edit part class of the selected object). Choosing Set as Default for all ... links the option value with the domain model element or diagram type of the selected object (see Figure context_menu ). These four alternatives have different priorities: if present, the default value for the current diagram is taken first, then the default value for the edit part is checked, then the default value for the domain model element, and then the default value for the diagram type.

The information button of the view toolbar can be used to display some useful details on the current selection, such as the edit part and domain model classes.

Preference Page

If Set routing style of all edges to oblique is active, all routing styles and smoothness settings of edges are removed when automatic layout is performed. Since most layouters compute the routing of edges as part of their algorithm, these styles usually do not yield the expected results.

The Default Layout Option Values table is used to manage the default setting for layout options, which can also be modified with the context menu of the layout view (see above). All user-defined settings are displayed here, and the buttons on the right of the table serve to create, edit, and remove entries. The Type column shows the type of element the option is linked with: either edit part,model element, or diagram type. The Element column shows the class name for options that relate to edit parts or domain model elements, and the diagram type name for options that relate to diagram types. Option is the name of the layout option, and Value is the currently set value of the option.

Creating a new entry requires the selection of the type of related element and entering its class name or identifier. Class names of edit parts and domain model elements can be explored using the information button of the layout view, while diagram type identifiers can be selected with the Browse button. After that, a layout option has to be selected from the list using the corresponding Browsebutton. Hitting OK creates an entry, and its value can then be set using the Edit button.

Internal Structure

The central concept of the KIML implementation is the DiagramLayoutManager, which is responsible for analyzing diagrams, creating a KGraph structure, creating a layout configuration, and writing new position information back to the diagram. Internally, GEF diagrams are composed of figures (responsible for drawing the diagram), edit parts (the controllers), notation model elements (holding concrete layout data), and domain model elements (holding semantic data). For each type of diagram, a specialized diagram layout manager implementation is needed, e.g. in de.cau.cs.kieler.kiml.gmf for  GMF and in de.cau.cs.kieler.kiml.graphiti for  Graphiti. Diagram layout managers provide IGraphicalFrameworkBridges to access features that are specific to the respective editing framework, andILayoutConfigs to access layout options that are stored in the diagram files. Layout configurations may take different sources for assigning specific values to layout options, such as the notation model, user preferences, the de.cau.cs.kieler.kiml.layoutInfo extension point, or default values of layout providers or layout options. These configurations can then be used to transfer all relevant options to the layout graph using the KLayoutData structure and to display options in the Layout view. The singleton class LayoutDataService is used to access the available layout algorithms, layout options, diagram types, layout types, and stored option values.

KIML makes extensive use of the IPropertyHolder interface; a property holder is an object that can give and receive values for specific properties. The key for specifying which property to access is IProperty, which is usually instanced exactly once for each property. The layout data classes KShapeLayout and KEdgeLayout are property holders, which means that they can store layout option values for the graph elements they are connected with. Furthermore, ILayoutConfigs are property holders, which means that they can store layout options values to be transferred to the layout graph or to be displayed in the Layout view. AbstractLayoutProviders are property holders for storage of default values that are specific to the layout provider.

Connecting Layout Algorithms

Layout algorithms must be connected by extending AbstractLayoutProvider and using the de.cau.cs.kieler.kiml.layoutProviders extension point. The input of AbstractLayoutProvider? is an instance of the KGraph, an  EMF based graph structure, together with a progress monitor (IKielerProgressMonitor). The KGraph instance already has attached KLayoutData, which is initially set to the original layout of the diagram. The layout provider should read layout options from the attached layout data, execute a layout algorithm, and write the results back to the layout data. See the documentation of connected layouters. A good example for a layout provider implementation is LayeredLayoutProvider.

The layoutProviders extension point is needed to register layout algorithms; one layout provider class may provide multiple layout algorithms by giving a parameter string in the extension point. Furthermore, the extension point can be used to specify which layout options are understood and which diagram types are supported by the layout algorithm, and to define new layout options, layout types, and categories of layout algorithms. The priority value given with a supported diagram type is used to determine the most suitable layout algorithm for that diagram type; see the documentation of pre-defined diagram types.

Each layout option that is registered in the extension point needs a corresponding constant in Java code, where the most relevant data is replicated with a Property constant for easy use in the implementation of layout providers. KIML comes with a large set of built-in layout options, which are all defined in LayoutOptions. If a layout provider wants to override the default value of a layout option, it must set the corresponding properties for itself (which is a property holder) either in the constructor or in the initialization method, and it must use its own instance of the corresponding property. See for example the Properties class for the KLay layered layouter, which defines its own copy of the OBJ_SPACING option using a specific default value. Layout providers can access the layout option values using the IPropertyHolderinterface:

KShapeLayout nodeLayout = parentNode.getData(KShapeLayout.class);
boolean isInteractive = nodeLayout.getProperty(LayoutOptions.INTERACTIVE);

The layout option that is used in this example has a default value, thus it is guaranteed that the option always returns a valid value. This and the fact that properties are type-safe allows us to implicitly cast and unbox the returned value to a boolean without checking forNullPointerExceptions or ClassCastExceptions.

Connecting Diagram Editors

The extension point de.cau.cs.kieler.kiml.layoutInfo is used to define diagram types and to assign default layout options to specific parts of a diagram. Layout options can be associated with elements of the domain model, where the qualified name of the model element interface must be given, or with edit parts of a specific diagram editor, where the qualified class name of the edit part must be given. The diagram type can be assigned by setting the predefined layout option de.cau.cs.kieler.layout.options.diagramType with the diagram type identifier as value. This helps KIML to find a suitable layout algorithm for a part of the diagram editor without the need of referencing a specific algorithm.

KIML provides DiagramLayoutManager implementations for GMF and Graphiti. For diagram editors that are not compatible with those layout managers, a new implementation must be made. This includes specialized implementations of IGraphicalFrameworkBridge and ofILayoutConfig. Diagram layout managers have to be registered using the de.cau.cs.kieler.kiml.ui.layoutManagers extension point.

Graph Analysis

KIML offers an interface for graph analysis, available with the  button. Here a selection of analyses can be made, which refer to the structure or the drawing of the graph. After performing the analyses, the results are shown in a dialog and in the Analysis view. New analyses, which must implement IAnalysis, can be registered using the de.cau.cs.kieler.kiml.grana.analysisProviders extension point.