Skip to content

The Segmented Arc tool

1.0.0 · Output

The Segmented Arc tool is a complex, multi-part tool with a custom animation.
The tool consists of multiple separate segments that 'behave' like a single, segmented object.

The Arc can be between 0 and 360 degrees with configurable start and end angle. It can have an additional scale. The Arc supports colorstops and colorlists to display the state value.

It is by far the most complex tool. Was fun to make, and fairly unique.
The 360 degrees arc takes a prominent place in many examples.

<circle %="" <="" circle="" class="sak-circle__circle" cx="0" cy="0" r="110.00000000000001" style="fill: var(--md-primary-fg-color--50); stroke-width: 0;"> 23 %

Basic usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- type: 'segarc'            # tooltype is 'segarc'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    start_angle: -130       # start angle...
    end_angle: 130          # .. --> Arc from left to right!
    width: 7                # Width of arc 'bar'
    radius: 45              # Size or arc radius
  entity_index: 0           # connect to state of entity 0
  scale:
    min: -20                # Temperatures from -20 to +40
    max: 40
    offset: -4.5            # Scale on inside of arc bar
  show:
    style: colorlist        # use single color colorlist
    scale: true             # show scale too
  segments:
    colorlist:
      gap: 1                # gap between segments
      colors:
        - 'black'
  styles:
    background:
      fill: grey

The default style, 'fixedcolor' is broken, therefore the basic example uses a single color colorlist.

The direction of the arc is determined by the start and end angle

Arc from LEFT to RIGHT: end_angle > start_angle

  start_angle: -90
  end_angle: 0

Arc from RIGHT to LEFT: start_angle > end_angle

  start_angle: 90
  end_angle: 0

A circle for example has a start_angle of 0 and end_angle of 360

The arc can become an ellipse by specifying radius_x and radius_y separately

Extended usage

 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
- type: 'segarc'            # tooltype is 'segarc'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    start_angle: -130       # start angle...
    end_angle: 130          # .. --> Arc from left to right!
    width: 7
    radius: 45
  entity_index: 0           # connect to state of entity 0
  scale:
    min: 15                 # Inside temperature
    max: 25
    offset: -4.5            # Scale on inside of arc bar
  show:
    style: colorstops       # Use a colorstop
    lastcolor: true         # use last color to fill segments
  segments:
    colorstops:
      template:             # Use template colorstop (re-use!)
        name: colorstops_temperature_inside
        variables:
          - thegap: 1
  styles:
    background:
      fill: var(--primary-background-color)
      filter: url(#is-1)    # inset shadow for background

The use of show.lastcolor...

This setting determines whether a segment gets its color according to its own colorstop, or that the color of the last segment determines the colors of the previous segments.

Example:

Say we have a colorstop blue=0/green=25/yellow=50/red=75.

  • with the default lastcolor = false, with a state value of 60, you have filled blue and green segments, and a small part of the yellow segment is filled.
  • with lastcolor = true setting, all segments are yellow: they all take the 'last' color as their fill color.

Styling

The Segmented Arc tool has support for the following forms of styling:

Method Support Description
classes Using SAK or User defined class definitions
styles Using inline SVG and CSS styles

The Segmented Arc tool is composed of two objects: "foreground" and "background" are the selector for styling:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- type: 'segarc'
  position:
    cx: 50
    cy: 50
    start_angle: -130       # start angle...
    end_angle: 130          # .. --> Arc from left to right!
    width: 7
  classes:
    background:             # Background selector
      <...>
    foreground:             # Foreground selector
      <...>
  styles:
    background:             # Background selector
      <...>
    foreground:             # Foreground selector
      <...>

Populair properties for both 'foreground' and 'background' selectors:

Property Does what? Example
fill Fill color fill: red sets fill to color red
stroke-width Stroke width stroke-width: 2em sets width to relative width of 2em
stroke Stroke color stroke: blue sets stroke to blue
opacity Opacity (stroke/fill) opacity: 0.7 sets the opacity of rect to 70%
fill-opacity Opacity for fill fill-opacity: 0.5 sets the fill opacity to 50%
stroke-opacity Opacity for stroke stroke-opacity: 0.5 sets the stroke opacity to 50%

Haptics

The tool supports haptic feedback through user_actions/ tap_action definition

Action Haptic Description
Click haptic Uses the haptic property defined in the user_actions definition of the tool. If not specified, a default of medium is used
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
  tools:
    - type: icon
      position:
        cx: 10
        cy: 10
        align: center
        icon_size: 15
      entity_index: 0
      user_actions:
        tap_action:
          haptic: success
          actions:
            - action: more-info

Possible values for haptic feedback:

Haptic Description
success Indicates that a task or action has completed.
warning Indicates that a task or action has produced a warning of some kind.
failure Indicates that a task or action has failed.
light Provides a physical metaphor that complements the visual experience.
medium Provides a physical metaphor that complements the visual experience.
heavy Provides a physical metaphor that complements the visual experience.
selection Indicates that the selection is actively changing.

Animations

The Segmented Arc tool 'foreground' part has support for the following forms of animations:

Method Support Description
colorstops List of state values to set the color
colorlist Using a colorlist definition, creating equally sized segments
animations Operator state based animations with class/style styling

Detailed usage

The segarc tool has some functionalities which haven't been explained yet in the above examples.

Scale placement

The scale, if enabled through show.scale: true can be placed inside, on or on the outside of the arc.

The scale.offset value is responsible for that functionality and works together with the position.width property.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- type: 'segarc'            # tooltype is 'segarc'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    start_angle: -130       # start angle...
    end_angle: 130          # .. --> Arc from left to right!
    width: 7                # Width of arc 'bar'
    radius: 45              # Size or arc radius
  entity_index: 0           # connect to state of entity 0
  scale:
    min: -20                # Temperatures from -20 to +40
    max: 40
    offset: -4.5            # Scale on inside of arc bar
  show:
    style: colorlist        # use single color colorlist
    scale: true             # show scale too
  segments:
    colorlist:
      gap: 1                # gap between segments
      colors:
        - 'black'
  styles:
    background:
      fill: grey

The math is as follows:

  • the arc bar width of the arc is 7. As the math is from the center, we take 7/2 = 3.5 as the value to do the math with
  • the scale offset is -4.5. That is the offset from the center of the arc bar. A value of -4.5 means on the inside.
  • As the width of the arc is 3.5 from the center, there is a 'gap' between the arc and the scale of 1.

If you want the scale to be on the outside of the arc bar, use a positive offset value.

Animation duration

The arc uses a custom animation to draw the arc. The animation duration is default 5 seconds and can be configured as follows:

1
2
3
- type: 'segarc'            # tooltype is 'segarc'
  animation:
    duration: 5             # Animation in seconds

Gap between segments

The colorlist or colorstop show.style determines the number of segments the arc has.

The gap between the drawn segments can be configured using the gap property. The default is 1.
Setting this to 0 removes the gap between the segments.

1
2
3
4
5
  segments:
    colorlist:
      gap: 1                # gap between segments
      colors:
        - 'black'

Don't make the gap larger than the size of a segment

It may yield unexpected results.