Last modified by Alexander Schulz-Rosengarten on 2023/07/11 10:33
<
From version < 18.1 >
edited by msp
on 2014/03/06 12:07
To version < 20.1 >
edited by msp
on 2014/03/06 15:12
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -72,6 +72,8 @@
72 72  
73 73  (% 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 74  
75 +(% 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}}.
76 +
75 75  = (% style="line-height: 1.4285715;" %)The Layout Option Manager(%%) =
76 76  
77 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"}}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"]].
... ... @@ -78,7 +78,7 @@
78 78  
79 79  (% 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.
80 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:
83 +(% 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:
82 82  
83 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 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.
... ... @@ -109,10 +109,8 @@
109 109  
110 110  = (% style="line-height: 1.4285715;" %)Programmatically Setting Layout Options(%%) =
111 111  
114 +{{id name="programmatic-config"/}}
112 112  
113 -
114 -{{id name="programmatic-config"/}}\\
115 -
116 116  (% 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.
117 117  
118 118  == (% style="line-height: 1.4285715;" %)Using the Extension Point(%%) ==
... ... @@ -168,4 +168,99 @@
168 168  
169 169  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.
170 170  
171 +=== semanticConfig ===
172 +
173 +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"]]:
174 +
175 +{{code language="xml"}}
176 + <semanticOption
177 + class="de.cau.cs.kieler.synccharts.Scope"
178 + config="de.cau.cs.kieler.synccharts.diagram.custom.AnnotationsLayoutConfig">
179 + </semanticOption>
180 +{{/code}}
181 +
182 +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.
183 +
184 +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:
185 +
186 +{{code}}
187 +@portConstraints FIXED_SIDE
188 +@minWidth 20.0
189 +@minHeight 15.0
190 +entity IdentityActor
191 +{
192 + @portSide WEST
193 + port Input;
194 +
195 + @portSide EAST
196 + port Output;
197 +}
198 +{{/code}}
199 +
200 +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.
201 +
202 +=== customConfig ===
203 +
204 +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.
205 +
206 +== Using Volatile Configurators ==
207 +
208 +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:
209 +
210 +{{code theme="Eclipse" language="java"}}
211 +DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,
212 + new VolatileLayoutConfig()
213 + .setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.klay.layered")
214 + .setValue(LayoutOptions.SPACING, 30.0f)
215 + .setValue(LayoutOptions.ANIMATE, true));
216 +{{/code}}
217 +
218 +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:
219 +
220 +{{code theme="Eclipse" language="java"}}
221 +DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,
222 + new VolatileLayoutConfig()
223 + .setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.klay.force"),
224 + new VolatileLayoutConfig()
225 + .setValue(LayoutOptions.ALGORITHM, "de.cau.cs.kieler.kiml.libavoid"));
226 +{{/code}}
227 +
228 +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"]]:
229 +
230 +{{code theme="Eclipse" language="java"}}
231 +DiagramLayoutEngine.INSTANCE.layout(workbenchPart, diagramPart,
232 + CompoundLayoutConfig.of(config1, config2, ...));
233 +{{/code}}
234 +
235 +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"]]:
236 +
237 +{{code theme="Eclipse" language="java"}}
238 +public <T, C> VolatileLayoutConfig setValue(final IProperty<? super T> option, final C contextObj,
239 + final IProperty<? super C> contextKey, final T value)
240 +{{/code}}
241 +
242 +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.
243 +
244 +=== Configuration During Layout Graph Construction ===
245 +
246 +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:
247 +
248 +{{code theme="Eclipse" language="java"}}
249 +KNode childLayoutNode = KimlUtil.createInitializedNode();
250 +KShapeLayout nodeLayout = childLayoutNode.getData(KShapeLayout.class);
251 +Dimension minSize = nodeEditPart.getFigure().getMinimumSize();
252 +nodeLayout.setProperty(LayoutOptions.MIN_WIDTH, (float) minSize.width);
253 +nodeLayout.setProperty(LayoutOptions.MIN_HEIGHT, (float) minSize.height);
254 +{{/code}}
255 +
256 +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:
257 +
258 +{{code theme="Eclipse" language="java"}}
259 +mapping.getLayoutConfigs().add(VolatileLayoutConfig.fromProperties(mapping.getLayoutGraph(), PRIORITY));
260 +{{/code}}
261 +
262 +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.
263 +
264 +If you are uncertain about which value to use for {{code language="none"}}PRIORITY{{/code}}, take something like 25.
265 +
171 171  
Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -9469991
1 +9469997
URL
... ... @@ -1,1 +1,1 @@
1 -https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/9469991/Configuring Automatic Layout
1 +https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/9469997/Configuring Automatic Layout

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage