Donut Gauge¶

A donut gauge uses a ring-shaped progress arc to show where a value sits within a specified range, presenting progress towards a target at a glance. Once a comparison field is added, several gauges can be arranged side by side to compare multiple groups of data.

This topic describes the configuration items specific to the donut gauge. For the items common to all charts, such as the Basic tab and the Filter tab, see Common Configurations for Charts.

Types of Donut Gauge¶

When adding a widget, the Donut Gauge group provides the following options:

Preset	Description	Recommended scenario
Basic Donut Gauge	A single ring-shaped progress arc showing the progress of one measurement.	Showing the load rate of a device or the target achievement rate of a production line.
Ring pointer instrument panel	A ring appearance with tick marks outside the arc. This is the Ring Style layout of the meter gauge and has no pointer. For the configuration method, see Meter Gauge.	When a ring appearance is wanted but tick marks need to be kept.
With Metric Card	One donut gauge combined with up to two metric cards. For the configuration method, see Donut Gauge with Metric Card.	Showing progress alongside a few key values.
With Comparison	Split into several donut gauges by comparison field and shown side by side.	Comparing the completion rate of each production line or region.

The configuration panels of Basic Donut Gauge and With Comparison are identical; the only difference is that the latter comes with a Comparison data field preconfigured. You can add or remove the comparison field at any time after creating one, so the two presets convert into each other. The rest of this topic applies to both.

Data of Donut Gauge¶

In a donut gauge, Measurement determines the position of the progress arc and Comparison splits the widget into several gauges.

For common configuration such as the data source, category, data source parameters, aggregation, sorting, alias, and unit, see Common Configurations for Charts > Configuring Data.

Measurement¶

Measurement determines how far the progress arc is filled, and exactly 1 field is required. The measurement value is converted proportionally into an arc length between the minimum and maximum of the Axis Range.

Comparison¶

Comparison is optional and accepts up to 1 field. Once added, the data is grouped by the values of that field, each value produces its own donut gauge, and the gauges are arranged side by side according to the rows and columns set in Layout.

Without a comparison field, the widget shows a single gauge and the Comparison Style section is hidden.

Note

The donut gauge uses only Measurement and Comparison data fields; adding other data fields has no effect on the chart.

Style of Donut Gauge¶

The Style tab is organized into three sections: comparison style, metric style, and gauge style. For common styles such as the title, widget padding, and background, see Common Configurations for Charts > Configuring Style.

Once the data fields are configured, the titles of the Comparison and Metric collapsible panels show the names of the selected fields automatically, which makes it easy to confirm which field you are configuring.

Chart Layout¶

Chart Layout determines the overall form of the gauge. Options are Pointer Style (default) and Ring Style.

Pointer Style: A semicircular dial with a pointer that points to the position of the current value. The lower and upper limits of the range are labeled at both ends of the arc, and the measurement name, value, and unit appear below the chart.
Ring Style: A nearly complete ring whose arc length represents the current value. The value, unit, and name appear inside the ring, tick marks sit outside the arc, and no range labels are shown.

This option switches 4 configuration items; all others are shown in both layouts:

Configuration item	Pointer Style	Ring Style
Data Font	Shown	Hidden
Color Rules	Shown	Hidden
Color Rule for Value	Hidden	Shown
Color Rule for Remaining	Hidden	Shown

Note

The pointer is drawn by the widget in the colors of the current theme and is not affected by Color Rules. Ring Style has no pointer.

Comparison Style¶

This section is shown only once a comparison field has been added.

Layout¶

Layout uses Row and Column to arrange several gauges, with a default of 3 rows and 3 columns. The number of rows and columns determines how many gauges are visible at once.

The valid range is 1 to 24: values below 1 or above 24 are treated as the boundary value, and only the integer part of Column is used.

Show “Expand”¶

When selected, if the number of gauges exceeds the rows and columns of the layout, an Expand entry appears at the bottom of the widget for viewing the rest. When cleared, only the gauges that fit the layout are shown and the rest cannot be viewed.

Value Font¶

Sets the font, font size, color, and style of the comparison field label above each gauge.

The Metric Style section contains another item with the same name, Value Font, which applies to the value at the center of the gauge. The Value Font here applies only to the comparison field label.

Metric Style¶

This section is shown only once a measurement field has been added, and contains one collapsible panel. The items below are described in panel order.

Interaction Settings¶

Configures the jump or linkage behavior triggered by clicking the value at the center of the gauge. See Common Configurations for Charts > Interaction Settings. This applies only to the center value; the comparison field label above the gauge does not support click interaction.

Show Name¶

When selected, the name label of the measurement field is shown in the gauge. Cleared by default. The name text is the Alias of the measurement field, or the field name when no alias is configured. In Pointer Style the name appears to the left of the value below the chart; in Ring Style it appears below the value inside the ring.

Once the name is shown, you can set the font, font size, color, bold, and italic style of the measurement name label.

Note

In Pointer Style the name label is not rendered when the font size is empty or 0. If you selected Show Name but see no name, check that the font size here is set. In Ring Style an empty font size renders as 16 pt, so the problem does not occur.

Value and Unit¶

Unit Name: The unit text shown after the value. Empty by default. Once Show As Percentage is selected, the unit set here no longer appears in the chart.
Dynamic Unit: When selected, the unit is converted automatically according to the magnitude of the data. See DTV Unit Library. In Pointer Style this applies to both the value below the chart and the range labels at either end of the arc. In Ring Style the value inside the ring does not take part in unit conversion: Dynamic Unit has no effect and the unit that comes with the data field is not shown either, so the ring shows only the text entered in Unit Name (or the percent sign once Show As Percentage is selected).
Decimal Places: Rounds the value to the specified number of decimal places, with a default of 2. The source data is not affected.
Unit Wrap: When selected, the unit or percent sign appears on a separate line from the value. Cleared by default.

Font Settings¶

Name Font, Unit Font, and Value Font set the font, font size, color, and style of the measurement name, the unit text, and the value at the center of the gauge respectively. The color of the value text is determined by Value Font and is not affected by Color Rules.

Axis Range¶

Min and Max specify the data range the progress arc corresponds to, with a default of 0 to 100. The measurement value is converted into an arc length within that range: the arc is empty at Min and full at Max.

Empty boxes fall back to the defaults: an empty Min counts as 0 and an empty Max counts as 100. This still holds once a comparison field is added, where all groups of gauges share one range rather than adjusting to the actual maximum of each group.

Both boxes accept placeholders, so the range can be controlled dynamically by parameters. For more information, see Configuring Dynamic Parameters.

Note

Avoid setting Max to the same value as Min, since the denominator of the conversion would be 0 and the chart could not derive a valid percentage.

Show As Percentage¶

Selected by default. When selected, the center of the gauge shows the current value as a percentage of the axis range rather than the raw measurement value, and Unit Name is no longer shown. When cleared, the raw measurement value and its unit are shown, and the range labels show the actual minimum and maximum.

This option also determines the matching basis of Color Rules: when selected, rules match on the percentage (0 to 100); when cleared, they match on the raw measurement value. Review the configured color rule ranges after changing this option.

Color Rule for Value¶

Assigns a color to the filled part of the ring arc per value range. The rule structure is the same as Common Configurations for Charts > Color Rules. Shown only when Chart Layout is Ring Style.

Color Rule for Remaining¶

Assigns a color to the unfilled part of the ring arc per value range. The rule structure is the same as Common Configurations for Charts > Color Rules. When left empty, the unfilled part uses the default color of the page theme. Shown only when Chart Layout is Ring Style.

Note

Color rules apply only to the progress arc. The color of the background track is determined by the page theme and the color of the value text by Value Font; neither is affected by color rules.
When the measurement value falls outside the Axis Range, the derived percentage can be below 0 or above 100, and color rules match on that actual percentage, while the progress arc itself is clamped to 0 to 100. A full arc can therefore still take the color of a rule range above 100.

Gauge Style¶

This section has a single collapsible panel named Gauge, which contains only Gauge Thickness.

Gauge Thickness¶

Specifies the thickness of the ring arc in pt, with a default of 6 and a minimum of 0. The value applies to both the progress arc and the background track. At 0 the arc is not drawn at all and only the pointer and the text remain.

The thickness is converted into a proportion of the actual rendered ring size, so the same value looks thinner in a larger widget. When the value exceeds the pixel size of the ring itself, the arc is not drawn.

Interactions at Runtime¶

The donut gauge behaves as follows at runtime:

Value animation: On the running page, the progress arc fills from 0 to the target position while the center value counts up. The editor shows the final value directly, which makes configuration easier.
Hover tooltip: Hovering the mouse over the value, unit, name, or comparison label shows the full text.
Multiple gauge arrangement: Once a comparison field is added, the gauges are arranged by the rows and columns of Layout; when Show “Expand” is selected, the overflow can be viewed with Expand.
Adaptive size: Gauges are always rendered square, with the side length taken from the smaller of the available widget width and height, leaving room for the title and the name.
Empty state: When no measurement field has been added, an empty-state prompt is shown.
Invalid value: When the measurement value is not a number, the center shows --.

Note

The donut gauge provides no Show Tooltip item. See Common Configurations for Charts > Show Tooltip. The hover tooltip on values is provided by the widget directly and neither needs nor allows a configuration switch.
The donut gauge does not support Link Other Widgets, and the Filter tab does not show that area. See Common Configurations for Charts > Scope.