User Tools

Site Tools


v020:layout

This is an old revision of the document!


Diagram Language Guide for version 0.2.0

Currently txtUML supports diagram definitions for class diagrams.

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.

class MyDiagram extends Diagram {
  // layout constraints as annotations
  class MyLayout extends Layout {}
}

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:

  • @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) : 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) : 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) : 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.
  • @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.
  • @Left(val = A.class, from = B.class) : box A is west from B and is right next to it.

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:

  • @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, 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.
  • @TopMost(A.class) : Box A is north from every other box.
  • @RightMost(A.class) : Box A is east from every other box.
  • @BottomMost(A.class) : Box A is south from every other box.
  • @LeftMost(A.class) : Box A is west from every other box.

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.

  • @North(val = L.class, from = A.class) : link L will connect to box A on A's northern side.
  • @North(val = L.class, from = A.class, end = LinkEnd.Start) : reflexive link L's starting 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.
  • @Priority(val = L.class, prior = 50) : gives link L a priority value of 50. Higher priority means shorter route and less turns.

Example: Model contains these classes: A and B. Model contains these links: L (A - B) and R (A -A).

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, LinkEnd.Start)
  @South(val = R.class, from = A.class, LinkEnd.End)
  class MyLayout extends Layout {}
}

TODO:IMAGE_HERE

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.

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.

  @Contains({A.class, B.class})
  class NG1 extends NodeGroup {}
  @Contains({L.class, J.class})
  class LG1 extends LinkGroup {}

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.

  @Contains({NG1.class, C.class})
  @Alignment(AlignmentType.TopToBottom)
  class NG2 extends NodeGroup {} 

With these groups we can use the previously mentioned statements.

  • @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, from = {B.class, C.class}) : box A is north from box B and from box C as well. The layout between B and C is not defined.
  • @North(val = LG1.class, from = A.class) : Every element of group LG1 is north from box A. The layout between the elements of LG1 is not defined.
  • Can be used similarly with @East, @South and @West.
  • @TopMost({A. class, B.class}) : boxes A and B are north from every other boxes in the model.
  • @TopMost(NG1.class) : boxes which are elements of LG1 are north from every other boxes in the model.
  • Can be used similarly with @RightMost, @BottomMost and @LeftMost.

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.

Example:

  class MyPhantom extends Phantom {}
  
  //...
  
  @Above(val = A.class, from = MyPhantom.class)
  @Above(val = MyPhantom.class, from = B.class)
  //...

TODO:IMAGE_HERE

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.

@Show(A.class) : box A is present in the diagram.

Example: Model contains these classes: A and B.

class MyDiagram extends Diagram {
  
  @Show(A.class)
  class MyLayout extends Layout {}
}

TODO:IMAGE_HERE(B missing)

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.
v020/layout.1446733762.txt.gz · Last modified: 2015/11/05 15:29 by deva