This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
v020:layout [2015/10/26 18:56] gregobalu [Compound layout constraints for nodes] |
v020:layout [2015/11/07 13:39] (current) gregobalu [Constraints for links] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ===== Diagram Language Guide for version 0.2.0 ===== | + | ====== Diagram Language Guide for version 0.2.0 ====== |
Currently txtUML supports diagram definitions for class diagrams. | Currently txtUML supports diagram definitions for class diagrams. | ||
- | ==== General structure ==== | + | ===== General structure ===== |
A diagram definition is a Java class inheriting from the ''Diagram'' type. It must contain an inner class definition, inheriting from ''Layout''. The layout constraints can be written as annotations on this inner class. | A diagram definition is a Java class inheriting from the ''Diagram'' type. It must contain an inner class definition, inheriting from ''Layout''. The layout constraints can be written as annotations on this inner class. | ||
Line 14: | Line 14: | ||
</code> | </code> | ||
- | ==== Simple layout constraints for nodes ==== | + | ===== Simple layout constraints for nodes ===== |
In this section **A** and **B** are classes already defined in a txtUML model. Relative layout for these classes (boxes) can be given as presented: | In this section **A** and **B** are classes already defined in a txtUML model. Relative layout for these classes (boxes) can be given as presented: | ||
- | * ''@North(val = A.class, from = B.class)'' : if box **B** cuts the diagram plane vertically into two, then **A** must be in the upper half-plane. | + | * ''@North(val = A.class, from = B.class)'' : The diagram can be cut horizontally such that **A** is in the upper half and **B** is in the lower half. |
- | * ''@East(val = A.class, from = B.class)'' : if box **B** cuts the diagram plane horizontally into two, then **A** must be in the right half-plane. | + | * ''@East(val = A.class, from = B.class)'' : The diagram can be cut vertically such that **A** is in the right half and **B** is in the left half. |
- | * ''@South(val = A.class, from = B.class)'' : if box **B** cuts the diagram plane vertically into two, then **A** must be in the lower half-plane. | + | * ''@South(val = A.class, from = B.class)'' : The diagram can be cut horizontally such that **A** is in the lower half and **B** is in the upper half. |
- | * ''@West(val = A.class, from = B.class)'' : if box **B** cuts the diagram plane horizontally into two, then **A** must be in the left half-plane. | + | * ''@West(val = A.class, from = B.class)'' : The diagram can be cut vertically such that **A** is in the right half and **B** is in the left half. |
- | * ''@Above(val = A.class, from = B.class)'' : box **A** is //north// from **B** and is right next to it. | + | * ''@Above(val = A.class, from = B.class)'' : Box **A** is //north// from **B** and is right next to it. |
* ''@Right(val = A.class, from = B.class)'' : box **A** is //east// from **B** and is right next to it. | * ''@Right(val = A.class, from = B.class)'' : box **A** is //east// from **B** and is right next to it. | ||
* ''@Below(val = A.class, from = B.class)'' : box **A** is //south// from **B** and is right next to it. | * ''@Below(val = A.class, from = B.class)'' : box **A** is //south// from **B** and is right next to it. | ||
* ''@Left(val = A.class, from = B.class)'' : box **A** is //west// from **B** and is right next to it. | * ''@Left(val = A.class, from = B.class)'' : box **A** is //west// from **B** and is right next to it. | ||
- | Example: | + | Example: Model contains these classes: **A**, **B** and **C**. |
+ | {{ :v020:examplesimplediagram.png?200|}} | ||
<code> | <code> | ||
class MyDiagram extends Diagram { | class MyDiagram extends Diagram { | ||
- | |||
@North(val = A.class, from = B.class) | @North(val = A.class, from = B.class) | ||
@Below(val = A.class, from = C.class) | @Below(val = A.class, from = C.class) | ||
Line 38: | Line 37: | ||
} | } | ||
</code> | </code> | ||
- | TODO:IMAGE_HERE | + | ===== Compound layout constraints for nodes ===== |
- | C | + | |
- | A | + | |
- | B | + | |
- | + | ||
- | ==== Compound layout constraints for nodes ==== | + | |
In this section **A**, **B**, **C** and **D** are classes already defined in a txtUML model. Complex layout for these classes (boxes) can be given as presented: | In this section **A**, **B**, **C** and **D** are classes already defined in a txtUML model. Complex layout for these classes (boxes) can be given as presented: | ||
- | * ''@Column({A.class, B.class, C.class})'' : The boxes **A**, **B** and **C** are arranged in a column formation, with the top being **A** and preserving the order. Any number of classes can be given here. | + | * ''@Column({A.class, B.class, C.class})'' : The boxes **A**, **B** and **C** are arranged in a column, with the top being **A** and preserving the order. Any number of classes can be given here. |
- | * ''@Row({A.class, B.class, C.class, D.class})'' : The boxes **A**, **B**, **C** and **D** are arranged in a row formation, with the left most being **A** and preserving the order. Any number of classes can be given here. | + | * ''@Row({A.class, B.class, C.class, D.class})'' : The boxes **A**, **B**, **C** and **D** are arranged in a row, with the left most being **A** and preserving the order. Any number of classes can be given here. |
* ''@Diamond(top = A.class, right = B.class, bottom = C.class, left = D.class)'' : The boxes **A**, **B**, **C** and **D** are arranged in a diamond shape where the four boxes are in the corners and an empty spot remains between them. | * ''@Diamond(top = A.class, right = B.class, bottom = C.class, left = D.class)'' : The boxes **A**, **B**, **C** and **D** are arranged in a diamond shape where the four boxes are in the corners and an empty spot remains between them. | ||
* ''@TopMost(A.class)'' : Box **A** is //north// from every other box. | * ''@TopMost(A.class)'' : Box **A** is //north// from every other box. | ||
Line 55: | Line 49: | ||
* ''@LeftMost(A.class)'' : Box **A** is //west// from every other box. | * ''@LeftMost(A.class)'' : Box **A** is //west// from every other box. | ||
- | Example: Model contains these classes: **C**, **E**, **D**, **O**, **R**, **S1** and **S2** | + | Example: Model contains these classes: **C**, **E**, **D**, **O**, **R**, **S1** and **S2**. |
<code> | <code> | ||
class MyDiagram extends Diagram { | class MyDiagram extends Diagram { | ||
- | |||
@Row({R.class, E.class, D.class}) | @Row({R.class, E.class, D.class}) | ||
@Column({C.class, R.class, O.class, S1.class, S2.class}) | @Column({C.class, R.class, O.class, S1.class, S2.class}) | ||
Line 64: | Line 57: | ||
} | } | ||
</code> | </code> | ||
- | TODO:IMAGE_HERE | + | ===== Constraints for links ===== |
- | ==== Constraints for links ==== | + | |
In this section **A** is a class already defined in a txtUML model and **L** is an association with an endpoint at class **A**. Relative layout for the associations (links) and classes (boxes) can be given as presented. For reflexive links a third parameter must be added which is a value of ''LinkEnd'' enum. | In this section **A** is a class already defined in a txtUML model and **L** is an association with an endpoint at class **A**. Relative layout for the associations (links) and classes (boxes) can be given as presented. For reflexive links a third parameter must be added which is a value of ''LinkEnd'' enum. | ||
Line 73: | Line 65: | ||
* ''@North(val = L.class, from = A.class, end = LinkEnd.End)'' : reflexive link **L**'s ending point will connect to box **A** on **A**'s northern side. | * ''@North(val = L.class, from = A.class, end = LinkEnd.End)'' : reflexive link **L**'s ending point will connect to box **A** on **A**'s northern side. | ||
* Can be used similarly with ''@East'', ''@South'' and ''@West''. | * Can be used similarly with ''@East'', ''@South'' and ''@West''. | ||
- | * ''@Priority(val = L.class, prior = 50)'' : gives link **L** a priority value of **50**. Higher priority means shorter route and less turns. | + | * ''@Priority(val = L.class, prior = 50)'' : gives link **L** a priority value of **50**. Higher priority means shorter route and less turns. |
- | Example: | + | Example: Model contains these classes: **A** and **B**. Model contains these links: **L** (A - B) and **R** (A -A). |
- | TODO | + | {{ :v020:examplelinkdiagram.png?150|}} |
- | TODO:IMAGE_HERE | + | <code> |
- | ==== Groups ==== | + | class MyDiagram extends Diagram { |
+ | @North(val = L.class, from = A.class) | ||
+ | @East(val = L.class, from = B.class) | ||
+ | @Above(val = A.class, from = B.class) | ||
+ | @West(val = R.class, from = A.class, end = LinkEnd.Start) | ||
+ | @South(val = R.class, from = A.class, end = LinkEnd.End) | ||
+ | class MyLayout extends Layout {} | ||
+ | } | ||
+ | </code> | ||
+ | ===== Groups ===== | ||
- | In this section **A**, **B**, **C** are classes already defined in a txtUML model and **L** and **J** are associations with an endpoint at class **A**. Relative layout for the associations (links) and classes (boxes) can be given as presented. | + | In this section **A**, **B**, **C** are classes already defined in a txtUML model and **L** and **J** are associations with an endpoint at class **A**. |
- | There's two way to define a group. The first method is by inheriting a class from either ''NodeGroup'' or ''LinkGroup''. The elements of the group can be specified with the ''@Contains'' annotation. A group can contain model elements of the corresponding type or other groups containing such type of elements. In the latter case, the contained groups are 'flattened', which means that only members of the contained groups are added to the given group instead of adding the contained group objects themselves. | + | A group can be defined by defining a class inheriting either from ''NodeGroup'' or from ''LinkGroup''. The elements of the group can be specified with the ''@Contains'' annotation. A group can contain model elements of the corresponding type or other groups containing elements of the corresponding type. |
<code> | <code> | ||
Line 94: | Line 95: | ||
</code> | </code> | ||
- | If the given group is a ''NodeGroup'', the annotation ''@Alignment'' can be used to set an alignment on its elements, using items of enum //hu.elte.txtuml.layout.lang.AlignmentType//, i.e. ''TopToBottom'', ''BottomToTop'', ''RightToLeft'' or ''LeftToRight''. | + | If the given group is a ''NodeGroup'', the annotation ''@Alignment'' can be used to set the alignment of its elements, using items of enum //hu.elte.txtuml.layout.lang.AlignmentType//, i.e. ''TopToBottom'', ''BottomToTop'', ''RightToLeft'' or ''LeftToRight''. |
<code> | <code> | ||
Line 102: | Line 103: | ||
</code> | </code> | ||
- | With these groups we can use the previously mentioned statements. | + | The previously mentioned statements can be used with these groups as parameters as well. |
* ''@North(val = {A.class, B.class}, from = C.class)'' : both boxes **A** and **B** are north from **C**. The layout between **A** and **B** is not defined. | * ''@North(val = {A.class, B.class}, from = C.class)'' : both boxes **A** and **B** are north from **C**. The layout between **A** and **B** is not defined. | ||
Line 112: | Line 113: | ||
* Can be used similarly with ''@RightMost'', ''@BottomMost'' and ''@LeftMost''. | * Can be used similarly with ''@RightMost'', ''@BottomMost'' and ''@LeftMost''. | ||
- | ==== Phantom nodes ==== | + | ===== Phantom nodes ===== |
In this section **A** and **B** are classes already defined in a txtUML model. Phantoms are defined by extending class ''Phantom'' and can be used as nodes in layout statements. | In this section **A** and **B** are classes already defined in a txtUML model. Phantoms are defined by extending class ''Phantom'' and can be used as nodes in layout statements. | ||
Line 126: | Line 127: | ||
//... | //... | ||
</code> | </code> | ||
- | TODO:IMAGE_HERE | ||
- | ==== Other ==== | + | ===== Other ===== |
If we do not include a class into any statements (annotations) then the class won't appear on the diagram by itself. We can explicitly make a class appear on a diagram without restricting it's position with other statements using ''@Show''. | If we do not include a class into any statements (annotations) then the class won't appear on the diagram by itself. We can explicitly make a class appear on a diagram without restricting it's position with other statements using ''@Show''. | ||
Line 142: | Line 142: | ||
} | } | ||
</code> | </code> | ||
- | TODO:IMAGE_HERE(B missing) | ||
- | ==== Contradictions and other errors ==== | + | ===== Contradictions and other errors ===== |
+ | There may be certain errors that blocks the running of the diagram layout generation process. This may occur because of: | ||
+ | * Contradiction in user given statements | ||
+ | * ''@North(val = A.class, from = B.class)'' and ''@South(val = A.class, from = B.class)'' | ||
+ | * Lack of statements, so two boxes are arranged into the same place. The algorithm might try to solve this, but it is not guaranteed. | ||
- | TODO |