Configuring Automatic Layout

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:

4

5

* What are //layout options//?

6

* How do layout algorithms support layout options?

7

* How do layout options end up in KGraph elements?

8

* How can I set layout options on elements programmatically?

9

10

This page does not list the available layout options, and neither does it explain any of them. You can find a list of layout options provided by KIML [[over here>>doc:KIML Layout Options]].

**Contents**

= Layout Options and What They Are Good For =

21

22

Even the most basic layout algorithm provides some settings for you to play with. This might be something as simple as the space left between different nodes, or something as complex as changing how node labels are placed and how that influences the size of each node. Each such setting must be registered with KIML as a //layout option//, and each algorithm must specify exactly which of these options it supports. Registering a layout option is done through one of KIML's extension points and can look like this:

<layoutOption

id="de.cau.cs.kieler.nodeLabelPlacement"

28

name="Node Label Placement"

29

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>

(% style="line-height: 1.4285715;" %)Let's walk through the attributes available for layout options (not every available attribute appears in the example above):

40

41

* (% style="line-height: 1.4285715;" %){{code language="none"}}id{{/code}} – A unique identifier for this layout option. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness.(%%)\\

42

* {{code language="none"}}type{{/code}} – Defines the data type of this option; must be either {{code language="none"}}boolean{{/code}}, {{code language="none"}}string{{/code}}, {{code language="none"}}int{{/code}}, {{code language="none"}}float{{/code}}, {{code language="none"}}enum{{/code}}, {{code language="none"}}enumset{{/code}}, or {{code language="none"}}object{{/code}}. The types {{code language="none"}}enum{{/code}}, {{code language="none"}}enumset{{/code}}, and {{code language="none"}}object{{/code}} require the {{code language="none"}}class{{/code}} attribute to be set.

43

* (% style="line-height: 1.4285715;" %){{code language="none"}}name{{/code}} – A user friendly name of this layout option, to be displayed in the UI.

44

45

* (% style="line-height: 1.4285715;" %){{code language="none"}}description{{/code}} – 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.

46

47

* (% style="line-height: 1.4285715;" %){{code language="none"}}advanced{{/code}} – Whether the option should only be shown in advanced mode in the layout view; default is {{code language="none"}}false{{/code}}.

48

49

* {{code language="none"}}appliesTo{{/code}} – A comma separated list of targets on which the layout option can be applied; a target can be either {{code language="none"}}parents{{/code}} (for nodes that contain further nodes), {{code language="none"}}nodes{{/code}} (for all nodes regardless of whether they contain further nodes or not), {{code language="none"}}edges{{/code}}, {{code language="none"}}ports{{/code}}, or {{code language="none"}}labels{{/code}}. 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.\\

50

* (% style="line-height: 1.4285715;" %){{code language="none"}}class{{/code}} – An optional Java class giving more detail on the data type. For {{code language="none"}}enum{{/code}} and {{code language="none"}}enumset{{/code}} options this attribute must hold the Enum class of the option. For {{code language="none"}}object{{/code}} options it must hold the class name of an {{code language="none"}}IDataObject{{/code}} implementation.

51

52

* (% style="line-height: 1.4285715;" %){{code language="none"}}default{{/code}} – The default value to use when no other value can be determined for this option.

53

* (% style="line-height: 1.4285715;" %){{code language="none"}}lowerBound{{/code}} – An optional lower bound on the values of this layout option.

54

* (% style="line-height: 1.4285715;" %){{code language="none"}}upperBound{{/code}} – An optional upper bound on the values of this layout option.

55

* (% style="line-height: 1.4285715;" %){{code language="none"}}variance{{/code}} – An optional variance for values of this layout option. 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.

56

57

58

(% style="line-height: 1.4285715;" %)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.

59

60

(% style="line-height: 1.4285715;" %)If a layout algorithm supports a particular layout option, it must tell KIML so. Here's an example:

<knownOption

option="de.cau.cs.kieler.borderSpacing"

default="20">

</knownOption>

</layoutAlgorithm>

</extension>

(% style="line-height: 1.4285715;" %)This tells KIML that the defined layout algorithm supports the border spacing option. And even more, it overrides the default value declared by the layout option and sets it to 20.

74

75

= (% style="line-height: 1.4285715;" %)The Layout Options Manager(%%) =

76

77

(% style="line-height: 1.4285715;" %)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>>doc:KGraph Meta Model]] elements yet. This is where the [[{{code language="none"}}LayoutOptionsManager{{/code}}>>url:http://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml.ui/src/de/cau/cs/kieler/kiml/ui/service/LayoutOptionManager.java||shape="rect"]] comes in.

78

79

(% style="line-height: 1.4285715;" %)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 associated KGraph elements. Sounds easy enough.

80

81

(% style="line-height: 1.4285715;" %)The question remains how the layout options sources work. Each source is represented by a class that implements the [[{{code language="none"}}ILayoutConfig{{/code}}>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/ILayoutConfig.java||shape="rect"]] interface, called a //layout configurator//. KIML currently provides the following layout configurators, each representing a particular source of layout options, listed here in order of increasing priority:

82

83

* [[DefaultLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/DefaultLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} – Applies fixed default values defined 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.

84

* [[EclipseLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml.service/src/de/cau/cs/kieler/kiml/service/EclipseLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} – Users can define default layout options to be set on elements that meet certain criteria via the KIML preference page. This layout configurator takes these options and applies them. Furthermore, it also applies options configured through the extension point.

85

* [[SemanticLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/SemanticLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} – An abstract superclass for configurators that base their computation of layout option values on the //semantic// model, a.k.a. //domain// model.

86

* [[GmfLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml.gmf/src/de/cau/cs/kieler/kiml/gmf/GmfLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} / [[GraphitiLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml.graphiti/src/de/cau/cs/kieler/kiml/graphiti/GraphitiLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} – These configurators apply layout option values set by the user in the Layout View. The values are stored in the notational model file of a diagram.

87

* [[VolatileLayoutConfig>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/VolatileLayoutConfig.java||shape="rect"]]{{code language="none"}}{{/code}} – A configurator 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.

88

89

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.

90

91

== A Few Details on Layout Configurators ==

92

93

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 configurator provides:

94

95

96

public interface ILayoutConfig {

97

int getPriority();

98

Object getOptionValue(LayoutOptionData optionData, LayoutContext context);

99

Collection<IProperty<?>> getAffectedOptions(LayoutContext context);

100

Object getContextValue(IProperty<?> property, LayoutContext context);

}

It is not hard to guess what {{code language="none"}}getPriority(){{/code}} 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.

105

106

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>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/LayoutContext.java||shape="rect"]], 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 {{code language="none"}}context.getProperty(LayoutContext.DIAGRAM_PART){{/code}}. Similarly, the corresponding KGraph element is mapped to the property {{code language="none"}}LayoutContext.GRAPH_ELEM{{/code}}, and the domain model element is mapped to {{code language="none"}}LayoutContext.DOMAIN_MODEL{{/code}}. Each configurator is free to put additional information into the context, caching it for faster access and enabling to communicate it to other configurators. {{code language="none"}}getAffectedOptions(LayoutContext){{/code}} 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>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/LayoutOptionData.java||shape="rect"]] instances obtained from the [[LayoutMetaDataService>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/LayoutMetaDataService.java||shape="rect"]] or with [[Property>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.core/src/de/cau/cs/kieler/core/properties/Property.java||shape="rect"]] instances from the constants defined in [[LayoutOptions>>url:https://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/options/LayoutOptions.java||shape="rect"]]. The actual value for a layout option is queried with {{code language="none"}}getOptionValue(LayoutOptionData, LayoutContext){{/code}}. The method {{code language="none"}}getContextValue(IProperty, LayoutContext){{/code}}, 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 {{code language="none"}}getContextValue(…){{/code}} by returning the domain model element when the given property corresponds to LayoutContext.DOMAIN_MODEL.

107

108

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.

109

110

= (% style="line-height: 1.4285715;" %)Programmatically Setting Layout Options(%%) =

111

112

(% style="line-height: 1.4285715;" %)So with all these layout configurators available, how do you actually go about setting layout options programmatically? Well, as always: it depends.

113

114

115

(% style="line-height: 1.4285715;" %)

Write this section. This will be about when to use the different kinds of layout configurations, mainly {{code language="none"}}SemanticLayoutConfig{{/code}} and {{code language="none"}}VolatileLayoutConfig{{/code}}.

120

121

122

(% style="line-height: 1.4285715;" %)

Wiki source code of Configuring Automatic Layout

Navigation

Quick Links