Skip to content

Tools and Entities

Tools and Entities have a strong relationship in most cases. The state of an entity determines what a tool displays, how it is displayed (styling) and how it interacts with the user.

Up to 2.4.1, a tool could be connected to zero (none) or one (1) entity. As of 2.4.1, a tool can be connected to a list of entities.

Standalone/Unconnected Tools

A tool that is not connected to an entity, that is it has no entity_index: x field is used solely for display purposes. This can be anyting, but circles, rectangles and lines are mostly used for that.

Example: 

1
2
3
4
5
- type: 'circle'            # tooltype is 'circle'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    radius: 25              # radius of circle. Width/height is 50

Single entity/Connected Tools

This is the most used combination: a tool is connected to a single entity to display its state and/or to have user interaction to for instance switch the entity on/off.
The tool has an entity_index: x definition.

Example: 

1
2
3
4
5
6
- type: 'circle'            # tooltype is 'circle'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    radius: 25              # radius of circle. Width/height is 50
  entity_index: 0           # connect to state of entity 0

Multi-entity Tools

2.4.1 In this case, the tool has an entity_indexes list definition instead of the entity_index: x definition:

1
2
3
4
  entity_indexes:
    - entity_index: 1     # Main / default entity index for this tool
    - entity_index: 0     # Additional entity #1
    - entity_index: 2     # Additional entity #2

These multiple indexes can be used in the animations section to control the state/styling of the tool using other entities.

For instance, you want the tool to be hidden depending on the state of another entity:

Hide/Display tool
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
- type: 'circle'            # tooltype is 'circle'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    radius: 25              # radius of circle. Width/height is 50
    entity_indexes:
      - entity_index: 1     # Default entity
      - entity_index: 0     # On/Off switch will show/hide this tool
    animations:
      - state: '50'
        operator: '>='
        reuse: true
        styles:
          track:
            opacity: 0.3
            transition: opacity 1s ease
      - state: '50'
        operator: '<'
        reuse: true
        styles:
          track:
            opacity: 1
            transition: opacity 1s ease

      - state: 'on'         # Show this tools state
        entity_index: 0     # If entity 0 is switched on
        reuse: true
        styles:
          circle:
            stroke: red
          tool:
            display: initial
      - state: 'off'        # Hide this tools state
        entity_index: 0     # if entity 0 is switched off
        reuse: true
        styles:
          tool:
            display: none