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:KIELER.Discontinued Projects.Infrastructure for Meta Layout (KIML).KIML Layout Options.WebHome]].

**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;" %)Such declarations are provided by layout algorithm developers, but not by tool developers who merely want to connect the layout infrastructure to their diagram viewers. 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

(% 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.

58

59

(% 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.

73

74

(% style="line-height: 1.4285715;" %)The meta data gathered from the extension point are made available through [[LayoutMetaDataService>>url:http://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"]]. For direct programmatic access, some of that information is duplicated with constants in the class [[LayoutOptions>>url:http://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 layout option declared above, for example, is available as {{code language="none"}}LayoutOptions.{{/code}}(% style="line-height: 1.4286; color: rgb(0, 0, 0)" %){{code language="none"}}NODE_LABEL_PLACEMENT{{/code}}.

75

76

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

77

78

(% 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:KIELER.Discontinued Projects.Infrastructure for Meta Layout (KIML).KGraph Meta Model.WebHome]] elements yet. This is where the [[{{code language="none"}}LayoutOptionManager{{/code}}>>url:http://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/LayoutOptionManager.java||shape="rect"]] comes in. If you are not interested in the internal details, but want to configure automatic layout for your diagram viewer or editor, you may skip this section and proceed to [[programmatically setting layout options>>doc:||anchor="programmatic-config"]].

79

80

(% style="line-height: 1.4285715;" %)After a diagram layout manager has finished turning a given diagram into its KGraph representation, the layout option 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.

81

82

(% style="line-height: 1.4285715;" %)The question remains how the layout options sources work. Each source is represented by a class that implements the [[ILayoutConfig>>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:

83

84

* [[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.

85

* [[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.

86

* [[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.

87

* [[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.

88

* [[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.

89

90

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.

91

92

== A Few Details on Layout Configurators ==

93

94

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:

95

96

97

public interface ILayoutConfig {

98

int getPriority();

99

Object getOptionValue(LayoutOptionData optionData, LayoutContext context);

100

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

101

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.

106

107

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.

108

109

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.

110

111

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

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

116

117

== (% style="line-height: 1.4285715;" %)Using the Extension Point(%%) ==

118

119

(% style="line-height: 1.4285715;" %)The recommended way to configure your layout is to use the {{code language="none"}}layoutConfigs{{/code}} extension point. It offers three different kinds of configurations, explained in the following.

120

121

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

122

123

(% style="line-height: 1.4285715;" %)A {{code language="none"}}staticConfig{{/code}} element can set one value for one layout option in the context of a particular diagram element type. Let's see an example:

<staticConfig

class="org.eclipse.emf.ecore.EReference"

128

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

value="ASSOCIATION">

</staticConfig>

(% style="line-height: 1.4285715;" %)Here {{code language="none"}}class{{/code}} refers to a domain model class, in this case the {{code language="none"}}EReference{{/code}} class from the Ecore meta model defined by EMF, and {{code language="none"}}option{{/code}} refers to a layout option through its identifier. The meaning of this declaration is that whenever automatic layout is requested for an Ecore class diagram, the {{code language="none"}}edgeType{{/code}} option is set to {{code language="none"}}ASSOCIATION{{/code}}(%%) for all edges linked to instances of {{code language="none"}}EReference{{/code}}. Since the domain model (//abstract syntax//) is independent of the specific diagram viewer (//concrete syntax//), this configuration is applied to all diagram viewers that use the Ecore meta model.

134

135

Alternatively to domain model elements, {{code language="none"}}staticConfig{{/code}} may also reference concrete syntax elements:

<staticConfig

class="org.eclipse.emf.ecoretools.diagram.edit.parts.EClassESuperTypesEditPart"

140

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

141

value="GENERALIZATION">

</staticConfig>

This layout option value is applied only to edges linked to instances of {{code language="none"}}EClassESuperTypesEditPart{{/code}}, which is a concrete syntax element of the Ecore Tools class diagram editor. Other Ecore meta model editors are not affected by this declaration. This distinction is particularly useful for meta models that are accessed with multiple different editors, as is often the case for UML tools.

146

147

A third variant is the use of //diagram types//, as in this example:

<diagramType

id="de.cau.cs.kieler.layout.diagrams.classDiagram"

152

name="Class Diagram">

153

</diagramType>

154

<staticConfig

155

class="org.eclipse.emf.ecore.EPackage"

156

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

157

value="de.cau.cs.kieler.layout.diagrams.classDiagram">

158

</staticConfig>

159

<staticConfig

160

class="de.cau.cs.kieler.layout.diagrams.classDiagram"

161

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

value="SPLINES">

</staticConfig>

A diagram type can be declared with a {{code language="none"}}diagramType{{/code}} element and can be associated with an abstract syntax or concrete syntax class using the {{code language="none"}}diagramType{{/code}} option, as shown in the first {{code language="none"}}staticConfig{{/code}} declaration in the example above. The second {{code language="none"}}staticConfig{{/code}} sets an option for the declared diagram type by using its identifier in the {{code language="none"}}class{{/code}} attribute. This kind of indirection is very useful when you have //n// model classes and you want to set //m// layout options for each of those classes. Instead of writing //n// × //m// static declarations, you assign a diagram type //t// to each of the //n// classes and then declare the //m// layout options for //t//, resulting in //n// + //m// option declarations (in many cases //n// + //m// < //n// × //m//).

167

168

A further use of diagram types is for the selection of layout algorithms: a layout algorithm may declare that is is especially suited to process diagrams of certain type //t//. If the diagram type //t// is assigned to a diagram viewer, the most suitable layout algorithm is chosen automatically for that viewer.

169

170

The following diagram types are predefined in KIML:

171

172

* de.cau.cs.kieler.layout.diagrams.stateMachine – All kinds of state machines, statecharts, etc.

173

* de.cau.cs.kieler.layout.diagrams.dataFlow – All kinds of data flow diagrams, e.g. actor diagrams, block diagrams, certain component diagrams, etc.

174

* de.cau.cs.kieler.layout.diagrams.classDiagram – Class diagrams as defined by the UML, but also meta model diagrams such as the Ecore format.

175

* de.cau.cs.kieler.layout.diagrams.usecaseDiagram – UML use case diagrams.

176

* de.cau.cs.kieler.layout.diagrams.boxes – Unconnected boxes (graphs with no edges), e.g. parallel regions in statecharts.

177

178

=== semanticConfig ===

179

180

A {{code language="none"}}semanticConfig{{/code}} element registers a subclass of [[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"]]:

<semanticOption

class="de.cau.cs.kieler.synccharts.Scope"

185

config="de.cau.cs.kieler.synccharts.diagram.custom.AnnotationsLayoutConfig">

</semanticOption>

Similarly to {{code language="none"}}staticConfig{{/code}} entries, the {{code language="none"}}class{{/code}} attribute refers to which model elements the configuration is applied. However, only domain model (a.k.a. //semantic// model) classes may be referenced. The {{code language="none"}}config{{/code}} attribute names a concrete implementation of the semantic layout configurator.

190

191

The advantage of this kind of configuration compared to {{code language="none"}}staticConfig{{/code}} declarations is that it may perform arbitrary analyses of the domain model. For instance, different option values may be computed depending on certain properties of the domain model elements. This approach can be used to enable annotations of domain model elements. When the domain model is stored with a textual format, e.g. defined with [[Xtext>>url:http://www.eclipse.org/Xtext/||shape="rect"]], such annotations can be written in the source file that specifies the model:

192

193

194

@portConstraints FIXED_SIDE

@minWidth 20.0

@minHeight 15.0

entity IdentityActor

{

@portSide WEST

port Input;

@portSide EAST

port Output;

}

The source file annotations can be translated to KIML layout options with a semantic layout configurator, which is registered to each domain model class where annotations can occur.

=== customConfig ===

This extension element can be used to register arbitrary implementations of [[ILayoutConfig>>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"]]. However, this is required only for some experimental configurators used in research. Tool developers normally do not need to use this kind of extension element.

212

213

== Using Volatile Configurators ==

214

215

The class [[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"]] is meant for programmatic layout configuration. It stores layout option values in a hash map. Values are either set globally, that means they are applied to all graph elements, or with a specific context. Global values are easy to configure:

216

217

218

DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,

219

new VolatileLayoutConfig()

220

.setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.klay.layered")

221

.setValue(LayoutOptions.SPACING, 30.0f)

222

.setValue(LayoutOptions.ANIMATE, true));

223

224

225

If multiple configurators are passed to the [[DiagramLayoutEngine>>url:http://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/DiagramLayoutEngine.java||shape="rect"]], the layout is computed multiple times: once for each configurator. This behavior can be used to apply different layout algorithms one after another, e.g. first a node placer algorithm and then an edge router algorithm, as in this example:

226

227

228

DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,

229

new VolatileLayoutConfig()

230

.setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.klay.force"),

231

new VolatileLayoutConfig()

232

.setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.kiml.libavoid"));

233

234

235

If you want to use multiple configurators in the same layout computation, use a [[CompoundLayoutConfig>>url:http://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/CompoundLayoutConfig.java||shape="rect"]]:

236

237

238

DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,

239

CompoundLayoutConfig.of(config1, config2, ...));

240

241

242

Setting layout option values with a specific context is done with this method of [[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"]]:

243

244

245

public <T, C> VolatileLayoutConfig setValue(final IProperty<? super T> option, final C contextObj,

246

final IProperty<? super C> contextKey, final T value)

247

248

249

Don't be scared by the rather cryptic declaration. The arguments {{code language="none"}}contextKey{{/code}} and {{code language="none"}}contextObj{{/code}} determine in which context the option value is to be applied. For instance, using {{code language="none"}}LayoutContext.DOMAIN_MODEL{{/code}} as context key and a specific domain model element as context object, the value is applied exactly to the graph element that is linked to that model element. If you want to refer to an element of the diagram viewer, i.e. the concrete syntax, use {{code language="none"}}LayoutContext.DIAGRAM_PART{{/code}} as context key. The return value is the volatile layout configurator itself, allowing for a builder pattern.

250

251

=== Configuration During Layout Graph Construction ===

252

253

Volatile configurators are also useful for the implementation of diagram layout managers ([[IDiagramLayoutManager>>url:http://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/IDiagramLayoutManager.java||shape="rect"]]). These implementations are responsible for creating layout graphs following the KGraph meta model from a given diagram viewer (method {{code language="none"}}buildLayoutGraph({{/code}}…{{code language="none"}}){{/code}}). For some layout options it is reasonable to determine concrete values while the layout graph is built, e.g. for the minimal width and height of nodes:

254

255

256

KNode childLayoutNode = KimlUtil.createInitializedNode();

257

KShapeLayout nodeLayout = childLayoutNode.getData(KShapeLayout.class);

258

Dimension minSize = nodeEditPart.getFigure().getMinimumSize();

259

nodeLayout.setProperty(LayoutOptions.MIN_WIDTH, (float) minSize.width);

260

nodeLayout.setProperty(LayoutOptions.MIN_HEIGHT, (float) minSize.height);

261

262

263

The problem is that the layout option manager that applies all configurators to the layout graph removes any option values that have been set directly on the graph elements, hence the configuration done in the previous example has no effect on the layout process. But do not fear, for salvation is near:

264

265

266

mapping.getLayoutConfigs().add(VolatileLayoutConfig.fromProperties(mapping.getLayoutGraph(), PRIORITY));

267

268

269

The variable {{code language="none"}}mapping{{/code}} refers to the [[LayoutMapping>>url:http://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/LayoutMapping.java||shape="rect"]] instance created in buildLayoutGraph({{code language="none"}}{{/code}}…){{code language="none"}}{{/code}}. The static method {{code language="none"}}fromProperties({{/code}}…{{code language="none"}}){{/code}} offered by [[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"]] creates a configuration that contains all the layout option values that have previously been seen directly on the graph elements. By adding this configuration to the layout mapping, we make sure it is considered by the layout option manager and the options are applied to the graph elements exactly as we have specified. Happy end.

270

271

If you are uncertain about which value to use for {{code language="none"}}PRIORITY{{/code}}, take something like 25.

272

273

== Adding Support for the Layout View ==

274

275

The Layout View empowers users to directly modify the layout configuration for the currently viewed diagram. This power, however, comes with a price. Tool developers implementing a [[IDiagramLayoutManager>>url:http://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/IDiagramLayoutManager.java||shape="rect"]] additionally have to provide an implementation of [[IMutableLayoutConfig>>url:http://git.rtsys.informatik.uni-kiel.de/projects/KIELER/repos/pragmatics/browse/plugins/de.cau.cs.kieler.kiml/src/de/cau/cs/kieler/kiml/config/IMutableLayoutConfig.java||shape="rect"]] that loads and saves layout option values in a way that they can be stored persistently with the respective diagram. Good examples of such configurators are [[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"]] and [[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"]] for GMF and Graphiti diagrams, respectively. The GMF implementation stores option values as //styles// in the GMF //Notation// model, while the Graphiti implementation stores the values as //properties// in the Graphiti //Pictogram// model. If you are developing an editor based on GMF or Graphiti, simply reuse these implementations and you're fine. Otherwise, read this section to learn how to implement a suitable configurator.

276

277

A //mutable// layout configurator is one that can not only read option values, but also write them. Most interface methods are rather self-explanatory, therefore we will consider only the {{code language="none"}}getContextValue(IProperty, LayoutContext){{/code}} method here. This method receives a [[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"]] and should return a value that corresponds to the given property, if possible, and {{code language="none"}}null{{/code}} otherwise. The starting point is usually the current value of {{code language="none"}}LayoutContext.DIAGRAM_PART{{/code}} in the given context, called the //diagram part//, which refers to the currently selected diagram element in the viewer (the abstract syntax element). From this the method should extract more information considering the following other context properties:

278

279

* {{code language="none"}}LayoutContext.DOMAIN_MODEL{{/code}} – The domain model element linked to the current diagram part.

280

* {{code language="none"}}LayoutContext.CONTAINER_DIAGRAM_PART{{/code}} – The diagram part that corresponds to the graph or subgraph that contains the current diagram part. This is called the //container//. If The current diagram part is already the top-level element of the diagram, then there is no container and {{code language="none"}}null{{/code}} should be returned.

281

* {{code language="none"}}LayoutContext.CONTAINER_DOMAIN_MODEL{{/code}} – The domain model element linked to the container.

282

* {{code language="none"}}LayoutContext.OPT_TARGETS{{/code}} – A set containing the kind of graph element that corresponds to the current diagram part, referenced with the enumeration [[LayoutOptionData.Target>>url:http://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"]]. If the diagram part is a node, for example, the set should contain the value {{code language="none"}}NODES{{/code}}. If the node is also a container for a subgraph, the set should additionally contain the value {{code language="none"}}PARENTS{{/code}}.

283

* {{code language="none"}}DefaultLayoutConfig.HAS_PORTS{{/code}} – If the current diagram part is a node, the returned value for this property should be {{code language="none"}}true{{/code}} or {{code language="none"}}false{{/code}} depending on whether the node has any ports or not. Ports are explicit connection points for edges; they occur frequently in data flow diagrams.

284

* {{code language="none"}}DefaultLayoutConfig.CONTENT_HINT{{/code}} – If the diagram contains an annotation about which layout algorithm to use for the content of the current diagram part, the returned value for this property should be the identifier of that algorithm. This is the same kind of annotation that is accessed through {{code language="none"}}getOptionValue({{/code}}…{{code language="none"}}){{/code}}, i.e. a value set by the user with the Layout View.

285

* {{code language="none"}}DefaultLayoutConfig.CONTAINER_HINT{{/code}} – The same as for CONTENT_HINT{{code language="none"}}{{/code}}, but referring to the container.

286

* {{code language="none"}}EclipseLayoutConfig.EDITING_DOMAIN{{/code}} – If your diagram editor needs an EMF editing domain in order to modify annotations of layout options, then such an editing domain should be returned for this property.

287

288

An instance of your self-made configurator should be returned by the {{code language="none"}}getDiagramConfig(){{/code}} method of your diagram layout manager.

Wiki source code of Configuring Automatic Layout

Navigation

Quick Links