LinearGauge Control Reference

Display values on a linear scale.

Reference → Controls → Gauge → LinearGauge

Requirements

This component is Portable. It runs both on Windows and on Web Pages hosted in any platform.

Configuration

1. Go to Displays / Draw.
2. On the Components Panel, select Gauges, then LinearGauge.
3. Click or drag-and-drop it on the Drawing area to use it.
4. Double-click the object to open the configuration window.

Linear Gauge configurations encompass settings for General, Scale, Labels, Ticks, Pointer, and Range. General settings include gauge orientation, positions, linked value, range start, and end values. Scale settings involve scale direction, interval, bar size, stroke, border color, and thickness. Label settings cover visibility, size, stroke, prefix, and postfix options. Tick settings define major and minor tick sizes, thickness, stroke, and the number of minor ticks per interval. Pointer settings determine the type, stroke, thickness, height, and width of the pointer. Range settings specify segments, start and end values, color, and boundary width.

General

Linear Gauge General settings control the basic appearance and functionality of the gauge. These settings include orientation (horizontal or vertical), position relative to other elements (above or below),specific data value or source link (e.g., "Tag.Level"), and defining the starting and ending values of the gauge range (e.g., 0 to 100).

Scale

Linear Gauge Scale settings also manage the scale's direction, interval, size, stroke, border color, and thickness. Users can set the scale direction to forward or backward, define intervals between scale markings, adjust the scale bar size and stroke width, and customize the border's color and thickness to enhance visual clarity.

Labels

Linear Gauge Labels Settings handle the visibility, size, stroke, prefix, and postfix of labels. Users can choose to show or hide labels, define their size, adjust the stroke color for emphasis, and add prefixes or postfixes to label values, allowing for clear and customized data representation.

Ticks

Linear Gauge Ticks settings specify the dimensions and appearance of major and minor tick marks. These settings include the size, thickness, and stroke color of both major and minor ticks, and the number of minor ticks per interval, enabling precise and detailed scale gradations for better data readability.

Pointer

Linear Gauge Pointer Settings determine the type and appearance of the gauge pointer. Users can choose between a bar pointer or symbol pointer, and adjust the stroke color and thickness for the bar pointer, or define the height, width, and stroke color for the symbol pointer, ensuring the pointer is clearly visible and fits the gauge design.

Range

Linear Gauge Range Settings configure specific segments of the gauge. Users can enable or disable each range segment, set the starting and ending values for each segment, assign different colors to segments, and define the start and end width of each segment's boundaries, allowing for distinct and visually segmented data representation.

Color Mode

Linear Gauge Color Mode settings control how the gauge bar is colored. Users can select between a static color or a dynamic color mode driven by range segments, and define a neutral color to be displayed when the value is within a normal or inactive state.

Value

Linear Gauge Value settings control how the current value is displayed on the gauge. Users can show or hide the value, pin it near the pointer, define its numeric format, configure out-of-range (OOR) text and color, and customize the font size and color of the value label.

Setpoint

Linear Gauge Setpoint settings configure a visual setpoint indicator on the gauge. Users can enable or disable the setpoint marker, define its value, choose the pointer shape, set its size, customize fill and stroke colors and thickness, and optionally show a label next to the setpoint marker.

The Setpoint marker serves as a reference indicator on the gauge scale, visually distinct from the value pointer. It marks a specific threshold value where a defined behavior or automated action is expected to occur, for example, when a tank level reaches 40%, a pump may turn on automatically. Unlike the value pointer, the Setpoint does not move with the current reading, although it can be moved dynamically; it remains fixed at the configured value to provide a constant visual reference for operators.

Historian

The Historian bar is rendered as an overlay directly on the gauge scale, visually distinct from the main value bar. It represents a historical data range — for example, the minimum and maximum values recorded over the last two hours — displayed as a shaded band on the gauge, giving operators an immediate visual reference of how the value has behaved over time without leaving the screen.

The Historian Min and Historian Max fields accept tag bindings, meaning the range boundaries are dynamic. The logic for calculating those boundaries — such as querying the historian for the lowest and highest values in the last two hours — must be implemented in a Script Task that writes the results to the bound tags, which the gauge then reads automatically.

Alarm Linear Gauge

The Alarm LinearGauge extends the standard LinearGauge with alarm management capabilities built on the ISA-101 HMI standard. The goal is to give operators a richer, more immediate understanding of a process variable's state, not just its current value, but its alarm condition, recent behavior, and whether any automatic protective action has already been triggered.

Six elements were added on top of the base control:

Alarm Symbol — An ISA-101 compliant symbol rendered alongside the gauge that uses geometric shapes (triangles for process alarms, rectangles for system states), a priority number, and standardized colors to communicate alarm severity at a glance. Operators can instantly identify the priority of an alarm without relying solely on the pointer position.

Alarm Colors — Color zones that appear directly on the gauge bar when the live value enters an alarm region. High and Low alarms are shown in orange; HiHi and LoLo alarms are shown in yellow. These colors only appear when the value actually reaches the threshold, making it immediately obvious that an alarm condition is active.

Historian Bar — A semi-transparent blue bar overlaid on the gauge scale showing the min/max range of the process variable over the last two hours. This gives operators a quick sense of how the variable has been behaving over time without opening a trend chart. The min and max boundaries are driven by tag bindings, and the logic to compute them must be implemented in a Script Task that queries the historian and writes the results to those tags. (Code example below)

Alarm Duration — A label displayed above the gauge showing how long the current alarm has been active. This helps operators assess urgency and decide whether escalation is needed.

Interlocks — Visual indicators at the high and low extremities of the gauge scale that signal when a process interlock has been triggered for that variable, meaning the control system has already taken automatic protective action. This helps operators distinguish between a value in an alarm region versus one where the system has already responded.

Setpoint — A diamond-shaped marker positioned on the gauge scale to indicate a target or threshold value for the process variable. Following ISA-101 High Performance Graphics conventions, the diamond shape was chosen specifically to be visually distinct from both the value pointer and the alarm indicators, making it immediately recognizable as a reference point rather than a live reading. The setpoint does not move; it remains fixed at the configured value so operators always have a clear visual anchor for where the process should be operating or where a specific automated action is expected to occur. This is consistent with the HPG principle of reducing cognitive load by encoding meaning through shape, not just color.

The Alarm LinearGauge symbol looks like this:

Importing the Symbol

1 - Go to Displays / List and select the display you want to add that symbol.

2 - In the left menu you go to Symbols > Library and search for Alarm_Linear_Gauge

3 - Click the symbol, then click on the drawing area to place it.

Configuration

Once the Alarm LinearGauge symbol is imported into the solution, double-click it to open the Symbol Links configuration and map each parameter to the appropriate tags or values for your application.

The symbol is ready to use as-is if the selected tag in AlarmTag has LoLo, Lo, Hi, and HiHi alarms configured. If your tag uses a different alarm structure, you will need to edit the symbol to match your configuration.

Historian and Duration Scripts

The Historian and Alarm Duration calculations are implemented as Script Tasks rather than directly on the display. Since displays run on a single thread, performing database queries or time calculations there would impact rendering performance. Running these scripts on separate tasks keeps the display responsive and ensures the gauge updates without affecting the UI thread.

This script queries the historian database for the minimum and maximum values of the process variable over the last two hours, using the current UTC time as the upper boundary. The result is written to two tags (e.g., Tag.Tag1_Min and Tag.Tag1_Max which are bound to the Historian Min and Historian Max properties of the gauge. This is what drives the blue historical range bar on the gauge scale.

DateTime utcNow = DateTime.UtcNow;
DateTime twoHoursAgo = utcNow.AddHours(-2);
long ticksNow = utcNow.Ticks;
long ticksTwoHoursAgo = twoHoursAgo.Ticks;
string tableName = "Table1";

@Dataset.Query.AlarmLinearGauge.SqlStatement = $@"
    SELECT MIN(Tag1) AS MinValue, MAX(Tag1) AS MaxValue
    FROM {tableName}
    WHERE UTCTimestamp_Ticks >= {ticksTwoHoursAgo}
      AND UTCTimestamp_Ticks <= {ticksNow}";

var dataset = await @Dataset.Query.AlarmLinearGauge.SelectCommandAsync();

var row = dataset.Rows[0];
@Tag.Tag1_Min = Convert.ToDouble(row["MinValue"]);
@Tag.Tag1_Max = Convert.ToDouble(row["MaxValue"]);


}

This script checks the current alarm state of the process variable and retrieves the timestamp of when that alarm became active. It then calculates the elapsed time and writes it in {hh:mm:ss} format to a tag (e.g., Tag.TimeElapsed bound to the Duration display on the gauge. If no alarm is active, the tag is set to "None".

DateTimeOffset activeTime = DateTimeOffset.MinValue;
if(@Tag.Tag1.AlarmState == 7) //LoLo
{
	activeTime = @Tag.Tag1.LoLo.ActiveTime;
}
if(@Tag.Tag1.AlarmState == 3) //Lo
{
	activeTime = @Tag.Tag1.Lo.ActiveTime;
}
if(@Tag.Tag1.AlarmState == 9) //Hi
{
	activeTime = @Tag.Tag1.Hi.ActiveTime;
}
if(@Tag.Tag1.AlarmState == 25) //HiHi
{
	activeTime = @Tag.Tag1.HiHi.ActiveTime;
}
if(@Tag.Tag1.AlarmState != 0) //Duration Calc
{
	TimeSpan elapsed = DateTimeOffset.Now - activeTime;
	@Tag.TimeElapsed = $"{(int)elapsed.TotalHours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}";	
}
if(@Tag.Tag1.AlarmState == 0) //No Alarm
{
	@Tag.TimeElapsed = "None";	 

Runtime Execution

The LinearGauge Control provides a visual representation of data ranges in a linear manner. Users can customize the gauge by setting its orientation, position, and the data it is linked to. The control allows for detailed adjustments including the start and end of the range, scale direction, interval, and size. Additionally, users can modify the appearance of labels, ticks, pointers, and range segments in terms of size, thickness, and stroke. This level of customization ensures that the LinearGauge Control can be tailored to fit the specific needs of any application that requires linear data display.

In this section...