Page History

This page describes how automatic layout can be configured for a given application. This includes how layout options can be set on graph elements, and how they are applied by KIML during the layout process. After having read this, you should be able to answer the following questions:

...

<extension point="de.cau.cs.kieler.kiml.layoutProviders">
    <layoutOption
        id="de.cau.cs.kieler.nodeLabelPlacement"
        name="Node Label Placement"
        description="Hints for where node labels are to be placed; if empty, the node label's position is not modified."
        advanced="true"
        appliesTo="nodes"
        type="enumset"
        class="de.cau.cs.kieler.kiml.options.NodeLabelPlacement"
        default="">
    </layoutOption>
</extension>

Let's walk through the parameters attributes available for layout options (not every available parameter attribute appears in the example above):

• id – A unique identifier for this layout option. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness.
  
• type – Defines the data type of this option; must be either boolean, string, int, float, enum, enumset, or object. The types enum, enumset, and object require the class attribute to be set.
• name – A user friendly name of this layout option, to be displayed in the UI.
  
• description – A user friendly description of this layout option, to be displayed in the UI. The description should contain all information needed to understand what this option does.
  
• advanced – Whether the option should only be shown in advanced mode in the layout view; default is false.
  
• appliesTo – A comma separated list of targets on which the layout option can be applied; a target can be either parents (for nodes that contain further nodes), nodes (for all nodes regardless of whether they contain further nodes or not), edges, ports, or labels. If omitted, the layout option is not shown to the user in the layout view, which is a good thing for options that will be set programmatically anyway.
  
• class – An optional Java class giving more detail on the data type. For enum and enumset options this attribute must hold the Enum class of the option. For object options it must hold the class name of an IDataObject implementation.
  
• default – The default value to use when no other value can be determined for this option.
• lowerBound – An optional lower bound on the values of this layout option. This is used when a layout configuration is determined automatically.
• upperBound – An optional upper bound on the values of this layout option. This is used when a layout configuration is determined automatically.
• variance – An optional variance for values of this layout option. This is used when a layout configuration is determined automatically. The variance is taken as multiplier for Gaussian distributions when new values are determined. Options with uniform distibution, such as Boolean or enumeration types, do not need a variance value, since all values have equal probability. A variance of 0 implies that the option shall not be used in automatic configuration, regardless of its type.
  

...

...

The latter three attributes are used when a layout configuration is determined automatically, e.g. with an evolutionary algorithm. They are mainly meant for scientific experiments and can be ignored in most applications.

If a layout algorithm supports a particular layout option, it must tell KIML so. Here's an example:

...

By now, we have an idea of what layout options do and why they are important in the first place. However, we haven't looked at how layout options end up on KGraph elements yet. This is where the LayoutOptionsManager comes in.

...

.

After a diagram layout manager has finished turning a given diagram into its KGraph representation, the layout options manager is asked to enrich the KGraph elements with layout options. The option values can come from different sources: the user might have set some using the layout view; there might be some defaults for certain kinds of diagrams; or the programmer might have decided to attach some layout options to certain elements for just this one layout run. Whatever the source, the options manager is in charge of collecting all these layout option values and making sure they find their way to the correct KGraph element. To start off with a clean plate, it first makes sure there are no layout options attached to the KGraph elements. It then does two things: collect every eligible source of layout options, and transfer values of layout options to the correct associated KGraph elements. Sounds easy enough.

...

.

The question remains how the layout options sources work. Each source is represented by a class that implements the ILayoutConfig interface, called a layout configurationconfigurator. KIML currently provides the following layout configurationsconfigurators, each representing a particular source of layout options, listed here in order of increasing priority:

• DefaultLayoutConfig – Sets Applies fixed default values defined for in the meta data of layout options. This is important for the Layout View, which displays the default values if nothing else has been specified.
• EclipseLayoutConfig – Users can define default layout options to be set on elements that meet certain criteria via the KIML preference page. This layout configuration configurator takes these options and applies them. Furthermore, it also applies options configured through the extension point.
• SemanticLayoutConfig – A configuration that bases its An abstract superclass for configurators that base their computation of layout option values on the semantic objects represented by the KGraph elements model, a.k.a. domain model.
• GmfLayoutConfig / GraphitiLayoutConfig – These configurations configurators apply layout options option values set by the user in the layout view or Layout View. The values are stored in the notation notational model file of a diagram.
• VolatileLayoutConfig – A configuration whose only purpose it is to make sure certain layout options are set on certain diagram elements in a particular layout runconfigurator for setting certain layout option values in one particular layout run. As the name says it, the values are volatile and thus they are not persisted.

The options manager collects all available and applicable layout configurations configurators and sorts them by priority (incidentally, the configurations were sorted by increasing priority just now). For every graph element, each configuration configurator is asked to provide layout options, starting with the default layout configuration 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 Configurations

...