Summary

• Page properties (2 modified, 0 added, 0 removed)
• Objects (1 modified, 0 added, 0 removed)
  • Confluence.Code.ConfluencePageClass[0]

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.cds
	1	+XWiki.msp

Content

...	...	@@ -1,6 +1,4 @@
1		-{{warning}}
2		-We haven't finished writing this page yet.
3		-{{/warning}}
	1	+
4	4
5	5	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:
6	6
...	...	@@ -38,7 +38,7 @@
38	38	</extension>
39	39	{{/code}}
40	40
41		-(% style="line-height: 1.4285715;" %)Let's walk through the parameters available for layout options (not every available parameter appears in the example above):
	39	+(% 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):
42	42
43	43	* (% 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.(%%)\\
44	44	* {{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.
...	...	@@ -52,14 +52,12 @@
52	52	* (% 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.
53	53
54	54	* (% 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.
55		-* (% style="line-height: 1.4285715;" %){{code language="none"}}lowerBound{{/code}} – An optional lower bound on the values of this layout option. This is used when a layout configuration is determined automatically.
56		-* (% style="line-height: 1.4285715;" %){{code language="none"}}upperBound{{/code}} – An optional upper bound on the values of this layout option. This is used when a layout configuration is determined automatically.
57		-* (% style="line-height: 1.4285715;" %){{code language="none"}}variance{{/code}} – 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.
	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.
58	58
59	59
60		-{{warning title="ToDo"}}
61		-Provide a better explanation of what the latter three parameters are used for. Are they only relevant to evolutionary layout?
62		-{{/warning}}
	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.
63	63
64	64	(% style="line-height: 1.4285715;" %)If a layout algorithm supports a particular layout option, it must tell KIML so. Here's an example:
65	65
...	...	@@ -76,71 +76,100 @@
76	76
77	77	(% 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.
78	78
79		-= (% style="line-height: 1.4285715;" %)The Layout Options Manager(%%) =
	75	+= (% style="line-height: 1.4285715;" %)The Layout Option Manager(%%) =
80	80
81		-(% 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 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.
	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"]].
82	82
83		-{{tip}}
84		-The [[KIML page>>doc:Infrastructure for Meta Layout (KIML)]] has a high-level explanation of what happens when during the layout process. To take a look at it if you haven't already – it will make the following concepts easier to understand. Plus, there's a nice picture that took Miro quite some time to create.
85		-{{/tip}}
	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.
86	86
87		-(% style="line-height: 1.4285715;" %)After a 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 layout options to the correct KGraph elements. Sounds easy enough.
	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:
88	88
89		-{{note}}
90		-Since the options manager starts by removing all layout options set on graph elements, setting layout options on the graph elements in the layout manager is a futile endeavor.
91		-{{/note}}
	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.
92	92
93		-(% 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 configuration//. KIML currently provides the following layout configurations, each representing a particular source of layout options:
	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.
94	94
95		-* {{code language="none"}}DefaultLayoutConfig{{/code}} – Sets fixed default values defined for layout options.
96		-* {{code language="none"}}EclipseLayoutConfig{{/code}} – Users can define default layout options to be set on elements that meet certain criteria via the KIML preference page. This layout configuration takes these options and applies them.
97		-* {{code language="none"}}SemanticLayoutConfig{{/code}} – A configuration that bases its layout option values on the semantic objects represented by the KGraph elements.
98		-* {{code language="none"}}GmfLayoutConfig{{/code}} / {{code language="none"}}GraphitiLayoutConfig{{/code}} – These configurations apply layout options set by the user in the layout view or stored in the notation model file of a diagram.
99		-* {{code language="none"}}VolatileLayoutConfig{{/code}} – A configuration whose only purpose it is to make sure certain layout options are set on certain diagram elements in a particular layout run.
	91	+== A Few Details on Layout Configurators ==
100	100
101		-The options manager collects all available and applicable layout configurations and sorts them by priority (incidentally, the configurations were sorted by increasing priority just now). For every graph element, each configuration is asked to provide layout options, starting with the default layout configuration and working through the priority chain.
	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:
102	102
103		-== A Few Details on Layout Configurations ==
104		-
105		-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 configuration provides:
106		-
107	107	{{code language="java"}}
108	108	public interface ILayoutConfig {
109	109	int getPriority();
110		- void enrich(LayoutContext context);
111		- Object getValue(LayoutOptionData<?> optionData, LayoutContext context);
112		- void transferValues(KLayoutData layoutData, LayoutContext context);
	98	+ Object getOptionValue(LayoutOptionData optionData, LayoutContext context);
	99	+ Collection<IProperty<?>> getAffectedOptions(LayoutContext context);
	100	+ Object getContextValue(IProperty<?> property, LayoutContext context);
113	113	}
114	114	{{/code}}
115	115
116		-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. The other three methods look a bit more obscure, so we have to provide more details on what the options manager does, exactly.
	104	+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.
117	117
118		-ENRICHING (+ WHAT IS A LAYOUT CONTEXT)
	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.
119	119
120		-The {{code language="none"}}transferValues(...){{/code}} method is the main workhorse of the interface. This is where a KGraph element, identified by the given layout context, is equipped with the layout option values a layout configuration deems necessary. It thus becomes the most important part of a layout configuration that you absolutely have to implement, no excuses. If for example every {{code language="none"}}KNode{{/code}} should have its port constraints set to {{code language="none"}}FIXED_POS{{/code}}, this is the place to do it.
	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.
121	121
122		-With all these layout configurations active, it's by no means clear which layout option values KGraph elements will end up with during the layout process. Enter the {{code language="none"}}getValue(...){{/code}} method. For a given element and layout option, it returns the value it would set on the element if {{code language="none"}}transferValues(...){{/code}} was called. This method is mainly used by the Layout view to inform the user about the layout option values of whatever graph element he (or she) has clicked on. It is also the method you can safely neglect to implement if your final product won't include the layout view anyway.
	110	+= (% style="line-height: 1.4285715;" %)Programmatically Setting Layout Options(%%) =
123	123
124		-== (% style="line-height: 1.4285715;" %)Implementing a Layout Configuration(%%) ==
125	125
126		-{{warning title="ToDo"}}
127		-deciding what options are applicable depending on the context object; setting the options;
128		-{{/warning}}
129	129
130		-(% style="line-height: 1.4285715;" %)
	114	+{{id name="programmatic-config"/}}\\
131	131
	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.
132	132
133		-= (% style="line-height: 1.4285715;" %)Programmatically Setting Layout Options(%%) =
	118	+== (% style="line-height: 1.4285715;" %)Using the Extension Point(%%) ==
134	134
135		-(% style="line-height: 1.4285715;" %)So with all these layout configurations available, how do you actually go about setting layout options programmatically? Well, as always: it depends.
	120	+(% 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.
136	136
	122	+=== (% style="line-height: 1.4285715;" %)staticConfig(%%) ===
137	137
138		-(% style="line-height: 1.4285715;" %)
	124	+(% 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:
139	139
	126	+{{code language="xml"}}
	127	+ <staticConfig
	128	+ class="org.eclipse.emf.ecore.EReference"
	129	+ option="de.cau.cs.kieler.edgeType"
	130	+ value="ASSOCIATION">
	131	+ </staticConfig>
	132	+{{/code}}
140	140
141		-{{warning title="ToDo"}}
142		-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}}.
143		-{{/warning}}
	134	+(% 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.
144	144
145		-(% style="line-height: 1.4285715;" %)
	136	+Alternatively to domain model elements, {{code language="none"}}staticConfig{{/code}} may also reference concrete syntax elements:
146	146
	138	+{{code language="xml"}}
	139	+ <staticConfig
	140	+ class="org.eclipse.emf.ecoretools.diagram.edit.parts.EClassESuperTypesEditPart"
	141	+ option="de.cau.cs.kieler.edgeType"
	142	+ value="GENERALIZATION">
	143	+ </staticConfig>
	144	+{{/code}}
	145	+
	146	+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.
	147	+
	148	+A third variant is the use of //diagram types//, as in this example:
	149	+
	150	+{{code language="xml"}}
	151	+ <diagramType
	152	+ id="de.cau.cs.kieler.layout.diagrams.classDiagram"
	153	+ name="Class Diagram">
	154	+ </diagramType>
	155	+ <staticConfig
	156	+ class="org.eclipse.emf.ecore.EPackage"
	157	+ option="de.cau.cs.kieler.diagramType"
	158	+ value="de.cau.cs.kieler.layout.diagrams.classDiagram">
	159	+ </staticConfig>
	160	+ <staticConfig
	161	+ class="de.cau.cs.kieler.layout.diagrams.classDiagram"
	162	+ option="de.cau.cs.kieler.edgeRouting"
	163	+ value="SPLINES">
	164	+ </staticConfig>
	165	+{{/code}}
	166	+
	167	+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//).
	168	+
	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	+
	171	+

Confluence.Code.ConfluencePageClass[0]

Id

...	...	@@ -1,1 +1,1 @@
1		-9469977
	1	+9469991

URL

...	...	@@ -1,1 +1,1 @@
1		-https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/9469977/Configuring Automatic Layout
	1	+https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/9469991/Configuring Automatic Layout