Package de.xima.fc.interfaces.workflow.bpmn

Interface IWorkflowBpmnLayouter

  • public interface IWorkflowBpmnLayouter
    Layout helper that can be used to lay out the BPMN diagram, such as aligning the parts of a workflow node in a sequence.
    Since:
    8.4.0

    • Method Detail

      • alignAround

        IWorkflowBpmnLayoutAlignAroundBuilder alignAround()
        Aligns two items, with the second item positioned relative to the first item, optionally with spacing.
        Returns:
        A builder for aligning a second item relative to a first item, with options for the direction and spacing.

      • alignAtAxis

        IWorkflowBpmnLayoutAlignAtAxisBuilder alignAtAxis()
        Aligns child items in a chosen axis-aligned direction, optionally with spacing.
        Returns:
        A builder for configuring the options for the alignment and a build method to perform the alignment.

      • alignAtPorts

        IWorkflowBpmnLayoutAlignAtPortsBuilder alignAtPorts()
        Creates a builder for aligning a list of items in the flow direction. The items are optionally spaced in the direction of the flow, and the out port of one item is aligned with the in port of the next item.
        Returns:
        A builder for configuring the options for the alignment and a build method to perform the alignment.

      • alignBinarySelectionGatewayFlowLabel

        IBinarySelectionGatewayFlowLabelHelperBuilder alignBinarySelectionGatewayFlowLabel()
        Gets a builder for a flow label helper for binary selection gateways, i.e. gateways with two branches, usually an if and an else branch. Helps to position the labels for the names of the two SequenceFlow that emerge from the gateway.

        Assumptions:

        • The two sequence flow lines emanating from the gateway are perpendicular to each other, i.e. one is horizontal and the other is vertical.
        • Both labels for the flow lines are positioned inside the corner formed by the two lines.
        • The alignment items for the consequent and alternate branch are placed next to each other. The alignment item for the consequent branch is at index 0, and the alignment item for the alternate branch is at index 1.
        • The gateway is placed next to the aligned body with the consequent and alternate branches. The alignment for the gateway is at index 0, and the alignment for the body is at index 1.

        Horizontal layouts might look like this: 

                                    +----------------+
       -------------------> |    alternate   |
       |                    +----------------+
       |
       |
       | no
       |
       x    yes             +----------------+
     x x x ---------------> |   consequent   |
       x                    +----------------+
    gateway


     gateway
       x                    +----------------+
     x x x ---------------> |   consequent   |
       x     yes            +----------------+
       |
       | no
       |
       |
       |                    +----------------+
       -------------------> |    alternate  |
                            +----------------+


                            +----------------+
                            |    alternate   | <-------------------
                            +----------------+                    |
                                                                  |
                                                                  |
                                                               no |
                                                                  |
                            +----------------+             yes    x
                            |   consequent   | <--------------- x x x
                            +----------------+                    x
                                                               gateway


                                                               gateway
                            +----------------+                    x
                            |   consequent   | <----------------x x x
                            +----------------+            yes     x
                                                                  |
                                                               no |
                                                                  |
                                                                  |
                            +----------------+                    |
                            |    alternate   | <-------------------
                            +----------------+

        Vertical layouts might look like this: 

               gateway
          x
        x x x ------------------------
          x     no                   |
          |                          |
          | yes                      |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          v                          v
  +----------------+        +----------------+
  |   consequent   |        |    alternate   |
  +----------------+        +----------------+


                                  gateway
                                     x
          ------------------------ x x x
          |                 no       x
          |                          |
          |                      yes |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          v                          v
  +----------------+        +----------------+
  |    alternate   |        |   consequent   |
  +----------------+        +----------------+


  +----------------+        +----------------+
  |   consequent   |        |    alternate   |
  +----------------+        +----------------+
          ^                          ^
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          | yes                      |
          |                          |
          x     no                   |
        x x x ------------------------
          x
       gateway


  +----------------+        +----------------+
  |    alternate   |        |   consequent   |
  +----------------+        +----------------+
          ^                          ^
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                          |
          |                      yes |
          |                 no       x
          ------------------------ x x x
                                     x
                                  gateway
        To create such a layout, you should proceed as follows:
        Returns:
        A builder for configuring the options for the binary selection gateway flow label helper.

      • alignOnFlowSide

        IWorkflowBpmnLayoutAlignOnFlowSideBuilder alignOnFlowSide()
        Creates a builder for aligning an item on a side of the edge of a flow, such as a SequenceFlow or MessageFlow. See IWorkflowBpmnLayoutAlignOnFlowSideConfigurator for more details on the available layout options. 
         (example with segment index = 1, side = RIGHT_OF_FLOW, alignment = 0.5, spacing = 3)

                                                                       +----------+
                                                                       |          |
                                   ┌──────────────────────────────────>|  target  |
                                   │                                   |          |
                                   │                                   +----------+
                                   │
                                   │   +------------+
                                   │   |    item    |
                                   │   +------------+
                                   │
 +----------+                      │
 |          |                      │
 |  source  |──────────────────────┘
 |          |
 +----------+

        The following image illustrates the alignment for side = RIGHT_OF_FLOW, alignment = 1.0 spacing = 20, offset = 0; when the red flow line goes from top-left to bottom-right and the alignment item has a yellow bounding box of 50x20 pixels:

        Align on flow side example

        • The rectangle is on the right side of the flow line.
        • The spacing 20 is the distance between the line and the rectangle, i.e. the distance between the top-right corner of the rectangle and the line in the example image above (yellow).
        • An alignment of 1.0 means the rectangle is as close to the end of the line as possible, i.e. the bottom-right point of the rectangle touches the line that is orthogonal to the flow line and passes through the flow line's end point.
        • The offset is 0 so the rectangle is not set off. If the offset were non-zero, the rectangle would be shifted by that amount in the direction of the red flow line. A positive offset would shift the rectangle to the bottom right, a negative offset would shift it to the top left.
        Returns:
        A builder for aligning an item on a side of the edge of a flow.

      • axisAlignedPath

        List<Point2DDouble> axisAlignedPath​(Iterator<Point2DDouble> points,
                                    ECartesianAxis2D firstAxis)
        Given a set of points, returns a list of points that represent the path from the first point to the last point, using only straight (axis-aligned) lines. The path is created by first going straight on the given axis, then making a sharp turn to the other axis for the second point. Then proceeds along the same axis to the next point, and so on.

        To illustrate, here's an example of a path with 4 points, 1 source point (s), 3 waypoints (w1, w2, w3), and 1 target point (t). The input points are: (s, w1, w2, t). The first axis is the y-axis (vertical): 

                             w2
                      o────────────┐ c3
                      │            │
  c1 ┌───────o────────┘ c2         │
     │       w1                    o w3
     │                             │
     │                             │
     │ first axis                  └────────────o
     │                            c4            t
     o  s
        The resulting list contains 7 points, in this order: (s, c1, c2, w2, c3, c4, t). The waypoints w1 and w3 are not included in this list as they lie on the same axis as the neighbouring points.
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        firstAxis - The first axis to go straight on.
        Returns:
        The path through the points, using only straight (axis-aligned) lines.

      • axisAlignedPath

        List<Point2DDouble> axisAlignedPath​(Iterable<Point2DDouble> points,
                                    ECartesianAxis2D firstAxis)
        Given a set of points, returns a list of points that represent the path from the first point to the last point, using only straight (axis-aligned) lines. The path is created by first going straight on the given axis, then making a sharp turn to the other axis for the second point. Then proceeds along the same axis to the next point, and so on.

        To illustrate, here's an example of a path with 4 points, 1 source point (s), 3 waypoints (w1, w2, w3), and 1 target point (t). The input points are: (s, w1, w2, t). The first axis is the y-axis (vertical): 

                             w2
                      o────────────┐ c3
                      │            │
  c1 ┌───────o────────┘ c2         │
     │       w1                    o w3
     │                             │
     │                             │
     │ first axis                  └────────────o
     │                            c4            t
     o  s
        The resulting list contains 7 points, in this order: (s, c1, c2, w2, c3, c4, t). The waypoints w1 and w3 are not included in this list as they lie on the same axis as the neighbouring points.
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        firstAxis - The first axis to go straight on.
        Returns:
        The path through the points, using only straight (axis-aligned) lines.

      • cornerPoint

        Point2DDouble cornerPoint​(Point2DDouble start,
                          Point2DDouble end,
                          ECartesianAxis2D firstAxis)
        Walks from the given start point to the given end point, by first going straight on the given axis, then making a sharp turn to the other axis. Returns the corner point representing the sharp turn. If both points are axis aligned, returns the midway point between the two points.

        To illustrate, here are a source and target point, together with a corner point. The first axis is the y-axis (vertical): 

          corner
     ┌────────────> target
     │
     │
     │ first axis
     │
     │
   source
        Parameters:
        start - The start point.
        end - The end point.
        firstAxis - The first axis to go straight on.
        Returns:
        The corner point representing the sharp turn.

      • flatten

        IWorkflowBpmnAlignmentItem<String,​?> flatten​(IWorkflowBpmnAlignmentItem<?,​?> item)
        Flattens the alignment items and all its nested children and returns a new alignment item with the flattened children.

        Positions of items are relative to the top-left corner of their containing item. This method resolves all positions and makes them absolute. Usually, you would call this method once you've aligned all items, then use the final positions.

        Parameters:
        item - The item to flatten.
        Returns:
        A new alignment item with the absolute positions for each nested child.

      • flattenToMap

        IFlattenedAlignmentItemMap<String> flattenToMap​(IWorkflowBpmnAlignmentItem<?,​?> item)
        Flattens the alignment items and all its nested children. Returns a map with all alignment items and the value of each alignment item as the key.

        Positions of items are relative to the top-left corner of their containing item. This method resolves all positions and makes them absolute. Usually, you would call this method once you've aligned all items, then use the final positions.

        Parameters:
        item - The item to flatten.
        Returns:
        A map with the absolute positions for each alignment items, indexed by the value of each alignment item.

      • layoutDataObject

        IWorkflowBpmnLayoutDataObjectBuilder layoutDataObject()
        Creates a builder for creating the layout of a BPMN DataObjectReference.
        Returns:
        A builder for the layout of a BPMN data object (reference).

      • layoutDataStore

        IWorkflowBpmnLayoutDataStoreBuilder layoutDataStore()
        Creates a builder for creating the layout of a BPMN DataStoreReference.
        Returns:
        A builder for the layout of a BPMN data store (reference).

      • layoutEvent

        IWorkflowBpmnLayoutEventBuilder layoutEvent()
        Creates a builder for creating the layout of a BPMN Event.
        Returns:
        A builder for the layout of a BPMN event.

      • layoutGateway

        IWorkflowBpmnLayoutGatewayBuilder layoutGateway()
        Creates a builder for creating the layout of a BPMN Gateway.
        Returns:
        A builder for the layout of a BPMN gateway.

      • layoutSubProcess

        IWorkflowBpmnLayoutSubProcessBuilder layoutSubProcess()
        Creates a builder for creating the layout of a BPMN SubProcess.
        Returns:
        A builder for the layout of a BPMN sub process.

      • layoutSubProcessBody

        IBoundedBpmnElementLayout<?> layoutSubProcessBody​(IWorkflowBpmnAlignmentItem<?,​?> body,
                                                  de.xima.bpmn_model.api.element.bpmn.common.FlowElementsContainer<?> container,
                                                  String startEventName,
                                                  String endEventName)
        Adds a StartEvent and EndEvent to the given body alignment item. This is used e.g. by a SubProcess, where the start event indicates where the sub process starts.

        Only adds a StartEvent if the body item has an in port, and only adds a EndEvent if the body item has an out port.

        If the body is empty, returns an empty alignment item with an and out port.

        Parameters:
        body - The body alignment item to add the start and end events to.
        container - The sub process that will contain the start event, body, and end event.
        startEventName - The name of the start event to add.
        endEventName - The name of the end event to add.
        Returns:
        The body alignment item with the start and end events added.

      • layoutTask

        IWorkflowBpmnLayoutTaskBuilder layoutTask()
        Creates a builder for creating the layout of a BPMN Task.
        Returns:
        A builder for the layout of a BPMN event.

      • layoutText

        IWorkflowBpmnAlignmentItem<StyledBpmnLabel,​?> layoutText​(StyledBpmnLabel styledLabel,
                                                               WorkflowBpmnTextLayoutSettings textSettings)
        Lays out the text of a styled BPMN label. Wraps the text into multiple lines, according to the given text layout settings, and returns an alignment item with the styled label as its value.
        Parameters:
        styledLabel - The label with the text to wrap.
        textSettings - The settings for wrapping the text.
        Returns:
        The wrapped text.