Wiki source code of Working With Layout Options
Version 3.1 by cds on 2013/09/11 15:52
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | This page describes how layout options are applied by KIML during the layout process. After having read this, you should be able to answer the following questions: | ||
| 2 | |||
| 3 | * What are //layout options//? | ||
| 4 | * How do layout options end up in KGraph elements? | ||
| 5 | * How can I set layout options on elements programmatically? | ||
| 6 | |||
| 7 | 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]]. | ||
| 8 | |||
| 9 | |||
| 10 | |||
| 11 | **Contents** | ||
| 12 | |||
| 13 | |||
| 14 | |||
| 15 | {{toc/}} | ||
| 16 | |||
| 17 | = Layout Options and What They Are Good For = | ||
| 18 | |||
| 19 | Even the most basic layout algorithm has 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: | ||
| 20 | |||
| 21 | {{code language="html/xml"}} | ||
| 22 | <extension point="de.cau.cs.kieler.kiml.layoutProviders"> | ||
| 23 | <layoutOption | ||
| 24 | id="de.cau.cs.kieler.nodeLabelPlacement" | ||
| 25 | name="Node Label Placement" | ||
| 26 | description="Hints for where node labels are to be placed; if empty, the node label's position is not modified." | ||
| 27 | advanced="true" | ||
| 28 | appliesTo="nodes" | ||
| 29 | type="enumset" | ||
| 30 | class="de.cau.cs.kieler.kiml.options.NodeLabelPlacement" | ||
| 31 | default=""> | ||
| 32 | </layoutOption> | ||
| 33 | </extension> | ||
| 34 | {{/code}} | ||
| 35 | |||
| 36 | (% style="line-height: 1.4285715;" %)Let's walk through the parameters available for layout options (not every available parameter appears in the example above): | ||
| 37 | |||
| 38 | * (% 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.(%%)\\ | ||
| 39 | * {{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. | ||
| 40 | * (% style="line-height: 1.4285715;" %){{code language="none"}}name{{/code}} – A user friendly name of this layout option, to be displayed in the UI. | ||
| 41 | |||
| 42 | * (% 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. | ||
| 43 | |||
| 44 | * (% 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}}. | ||
| 45 | |||
| 46 | * {{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.\\ | ||
| 47 | * (% 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. | ||
| 48 | |||
| 49 | * (% 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. | ||
| 50 | * (% 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. | ||
| 51 | * (% 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. | ||
| 52 | * (% 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 | |||
| 54 | |||
| 55 | {{warning title="ToDo"}} | ||
| 56 | Provide a better explanation of what the latter three parameters are used for. Are they only relevant to evolutionary layout? | ||
| 57 | {{/warning}} | ||
| 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: | ||
| 60 | |||
| 61 | {{code language="html/xml"}} | ||
| 62 | <extension point="de.cau.cs.kieler.kiml.layoutProviders"> | ||
| 63 | <layoutAlgorithm ...> | ||
| 64 | <knownOption | ||
| 65 | option="de.cau.cs.kieler.borderSpacing" | ||
| 66 | default="20"> | ||
| 67 | </knownOption> | ||
| 68 | </layoutAlgorithm> | ||
| 69 | </extension> | ||
| 70 | {{/code}} | ||
| 71 | |||
| 72 | (% 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 Layout Options Manager(%%) = | ||
| 75 | |||
| 76 | {{warning title="ToDo"}} | ||
| 77 | Write this section. | ||
| 78 | {{/warning}} | ||
| 79 | |||
| 80 | (% style="line-height: 1.4285715;" %) | ||
| 81 | |||
| 82 | |||
| 83 | = (% style="line-height: 1.4285715;" %)Programmatically Setting Layout Options(%%) = | ||
| 84 | |||
| 85 | {{warning title="ToDo"}} | ||
| 86 | 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}}. | ||
| 87 | {{/warning}} | ||
| 88 | |||
| 89 | (% style="line-height: 1.4285715;" %) |