The Roundbar widget

Author: Christian Mayer
Available since: 0.12.0 (2020)

Description

Adds a display to the visu that can represent values from the BUS and shows them with a round bar.

The design can the set in many different details:

Example for complex Roundbar widgets

Example for complex Roundbar widgets

Settings

For a general understanding of how the configuration files are structured and what elements and attributes are it is recommended to read this section first: Pages and structure of CometVisu.

The behaviour and appearance of the Roundbar widget can be influenced by using certain attributes and elements. The following tables show the allowed attributes and elements and their possible values. The screenshots show, how both can be edited in the editor.

Attributes underlined by ….. are mandatory, all the others are optional and can be omitted.

Allowed attributes in the Roundbar-element

Element

Attribute

Name

Content

Description

roundbar

min

decimal

Minimal value.

max

decimal

Maximum value.

format

string

Formatting of the value (printf syntax).

axisradius

decimal

Radius of the round axis.

axiswidth

decimal

Width of the axis.

axiscolor

string

Color of the axis.

ranges

string

Colored ranges.

minorradius

decimal

Radius for the minor ticks.

minorwidth

decimal

Width of the minor ticks.

minorspacing

decimal

Spacing of minor ticks.

minorcolor

string

Color of minor ticks.

majorradius

decimal

Radius for the major ticks.

majorwidth

decimal

Width of the major ticks.

majorposition

string

Positions of the major ticks, separated by “;”.

majorcolor

string

Color of the major ticks.

labels

string

Labels, separated by “;”.

labelstyle

string

CSS style of label text.

start

decimal

Start angle in degrees.

startarrow

decimal

Arrow size of bar start.

end

decimal

End angle in degrees.

endarrow

decimal

Arrow size of bar end.

arrowtype

angle or distance

Unit type of arrow size.

spacing

decimal

Spacing between the bars for automatic radius selection.

overflowarrow

true or false

Show an arrow when the value is out of range.

fontsize

decimal

Font size of the value.

textx

decimal

X position of the value.

texty

decimal

Y position of the value.

textlength

decimal

Length of the space to reserve for the value.

textanchor

start, middle or end

Orientation of value display in relation to the anchor point.

linespace

decimal

Distance between the rows for multiple values.

bboxgrow

string

Enlargement of the mounding box in virtual pixels to take care of sticking out parts (everywhere or horizontal;vertical or left;up;right;down).

debug

true or false

Activates the debug mode and shows the automatic determined border.

preset

A, B or bridge

Choose a preset design.

../../../_images/en_config_widgets_roundbar_index_editor_attributes.png

Attributes in the editor (simple view) [1]

Allowed child-elements and their attributes

Element

Attribute

Structure

Name

Content

Description

roundbar
  • layout

colspan

decimal

Amount of columns this widget should be wide.

colspan-m

decimal

Overrules the amount of columns on a medium screen.

colspan-s

decimal

Overrules the amount of columns on a small screen.

rowspan

decimal

Amount of rows this widget should be high.

x

string

Horizontal position of the widget for 2D pages.

x-s

string

Horizontal position of the widget for 2D pages on a small screen.

x-m

string

Horizontal position of the widget for 2D pages on a medium screen.

y

string

Vertical position of the widget for 2D pages.

y-s

string

Vertical position of the widget for 2D pages on a small screen.

y-m

string

Vertical position of the widget for 2D pages on a medium screen.

z

string

Reserved for future use.

width

string

Width for the widget for 2D pages.

width-s

string

Width for the widget for 2D pages on a small screen.

width-m

string

Width for the widget for 2D pages on a medium screen.

scale

true or false

Enable/Disable scaling layout values relative to backdrop on 2d pages (default: true).

scale-s

true or false

Enable/Disable scaling layout values relative to backdrop on 2d pages on a small screen (default: true).

scale-m

true or false

Enable/Disable scaling layout values relative to backdrop on 2d pages on a medium screen (default: true).

Element

Attribute

Structure

Name

Content

Description

roundbar
  • label

  • icon

name

string

Name of the icon registration.

type

string

flavour

string

Selection of a display variant. See also Flavour.

color

string

Color of the icon in CSS notation (e.g. #1188FF).

styling

string

Change the color of the displayed value depending on its value. See also Styling

class

string

Add this value to the CSS class so that it can be formatted by a user provided style sheet.

roundbar
  • label

    • #text

string

Text to display a label for the widget.

Element

Attribute

Structure

Name

Content

Description

roundbar
  • address

transform

string

Transformation of the bus system value to be shown.

mode

disable, read, write or readwrite

“disable” deactivates the communication, “read” will only fetch data from the backend, “write” will only write to it and an address with “readwrite” will be both, read from and written to.

type

bar or pointer

Type of the indicators.

showvalue

true or false

Shows the value for this indicator.

min

decimal

Overrules the minimum value of the widget for this indicator.

max

decimal

Overrules the maximum value of the widget for this indicator.

radius

decimal

Radius of the indicator.

width

decimal

Width of the indicator.

thickness

decimal

Thickness of the indicator (only for pointer).

valuepos

integer

Position (sorting) of the value of this indicator.

style

string

CSS style for the indicator.

roundbar
  • address

    • #text

string

The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

../../../_images/en_config_widgets_roundbar_index_editor_elements.png

Elements in the editor

Examples

It is possible to manually edit the visu_config.xml and add an entry for the Info widget.

Caution

Make sure that you only use UTF-8 encoded characters by settings the encoding in your XML-editor to UTF-8 mode!

<roundbar>
     <address transform="DPT:9.001" mode="read">3/3/1</address>
 </roundbar>

Design elements

The roundbar widget is assembled by many different elements, some of them are optional and can be configured by different means. The realisation of the roundbar is basically a SVG block that is included in the visu page, so it’s appearance can be altered by using CSS rules (see also “Change existing design”).

Indicators

The most obvious element is an indicator which is displayed as a round bar or a pointer. A Roundbar widget can contain multiple indicators at the same time.

Bar and pointer

Bar and pointer

<group nowidget="true">
    <layout colspan="4" rowspan="2"/>
    <roundbar>
        <layout colspan="2" rowspan="2"/>
        <address transform="DPT:9.001" mode="read">3/3/1</address>
    </roundbar>
    <roundbar format="%.1f">
        <layout colspan="2" rowspan="2"/>
        <address transform="DPT:9.001" type="pointer" radius="50" width="-50" thickness="3" mode="read">3/3/1</address>
    </roundbar>
</group>

Marking

To partition the axis markings can be used. The values for the big (major) markings can be chosen freely, the small (minor) markings are evenly distributed.

Big and small markings

Big and small markings

<roundbar majorradius="35" majorwidth="15" majorposition="0;20;40;60;80;100" minorradius="45" minorwidth="5" minorspacing="5" format="%.1f">
    <layout colspan="2" rowspan="2"/>
    <address transform="DPT:9.001" mode="read">3/3/1</address>
</roundbar>

Labels

The axis can be labeled with different ways. For this the attribute labels must contain the values separated by a semicolon:

labels="0;20;40;80;100"

Each value can have an individual radius as well as an individual text to display:

value,radius

value,radius,text

Also the position (outside, center and inside) as well as the orientation (horizontal, parallel, perpendicular, roundstart, roundmiddle and roundend) can be chosen and put in front of the text, separated by a colon:

position:value

,orientation:value

position,orientation:value

It is sufficient to put the position, the orientation and also the radius just in front of the first value, all following values are inheriting this property. For special effects it’s possible to change these properties multiple times:

Labels

Labels

<roundbar labels="inside:0,44;25;50;75;100" majorradius="45" majorwidth="5" majorposition="0;25;50;75;100" minorradius="48" minorwidth="2" minorspacing="5" format="%.1f">
    <layout colspan="2" rowspan="2"/>
    <address transform="DPT:9.001" mode="read">3/3/1</address>
</roundbar>

Ranges

To have a quick overview of the current value it is possible to mark value ranges by a color. For this the ranges attribute needs a list of range definitions that is separated by a semicolon.

Each range itself consists out of a list that is separated by colons:

value,radius,width,color

start...end,radius,width,color

Example:

ranges="0...70,63,3,green;70...100,63,3,red;70,60,9,#ff0"

This defines three ranges. First one for the values between 0 and 70 with a green arc of radius 63 and a width of 3. Then a red arc from 70 to 100, also with radius 63 and a width of 3. Last a line is drawn at value 70 that goes out from radius 60 for 9 units and has the color #ff0 which is a bright yellow.

Ranges

Ranges

<roundbar ranges="0...70,63,3,green;70...100,63,3,red;70,60,9,#ff0" format="%.1f">
    <layout colspan="2" rowspan="2"/>
    <address transform="DPT:9.001" mode="read">3/3/1</address>
</roundbar>

Tips

Presets

To simplify the configuration there are preset designs. All details of a preset can be overruled by the configuration file.

Preset "A", "B" and "bridge"

Preset “A”, “B” and “bridge”

<group nowidget="true">
    <roundbar preset="A">
        <layout colspan="2" rowspan="2"/>
        <address transform="DPT:9.001" mode="read">3/3/1</address>
    </roundbar>
    <roundbar preset="B">
        <layout colspan="2" rowspan="2"/>
        <address transform="DPT:9.001" mode="read">3/3/1</address>
    </roundbar>
    <roundbar preset="bridge">
        <layout colspan="2" rowspan="2"/>
        <address transform="DPT:9.001" mode="read">3/3/1</address>
    </roundbar>
</group>

Debug mode

The Roundbar widget tries to fill in the available space as big as possible. To be able to do so it must know already during the creation of the visu page how big its content can become. Especially for the text parts like the labels or the value this is not possible in an automated way.

For this the attribute bboxgrow can add to the automatically determined value a user specified distance. When it contains a single number this will be added on all sides simultaneously. Separated by a semicolon it is possible to add specific distances for horizontal;vertical. And for special effects each side can be adjusted individually by left;up;right;down.

To be able to reach a good result quicker, especially as it is an iterative effort to get the best numbers, the attribute debug can be set to true to get a blue frame to see the automatically derived dimensions and a green frame for the final dimensions.

Activated debug mode

Activated debug mode

<roundbar debug="true" bboxgrow="50;0">
    <layout colspan="2" rowspan="2"/>
    <address transform="DPT:9.001" mode="read">3/3/1</address>
</roundbar>

Footnotes