Value Indicators

  • 4 minutes to read

Value indicators is a group of elements that are used to point to the specific value on the related scale. This group consists of needle, level bar, range bar and marker elements. Each value indicator has its own Value property, which however should only be used if there are multiple value indicators linked to the same scale. For instance, the images below illustrate two analog gauges with one scale in each. Both of these gauges have three different value indicators that reflect different scale values.

ArcValueIndicators LinearValueIndicators

For any other scenario, when there is only one value indicator for each existing scale, the indicator's Value property should not be manually customized. Instead, link the indicator to the specific scale by using the ArcScale (LinearScale) property and the indicator will automatically move as the scale value changes.

The How to: Move Value Indicators at Runtime example illustrates how to allow your end-users to click a gauge in order to change the value to which a value indicator points.

Needle

Needles are base value indicators for circular gauges. In code, needles are represented by an instance of the ArcScaleNeedleComponent class. Needles are independent objects, which means you can add unlimited number of needles to your gauge regardless of the scales' count. The figure below illustrates a circular gauge with one scale and two needles.

CircularGauge_Needle

Needles start from the gauge's center. You can move a needle closer/further from this center point and scale by using its ArcScaleNeedle.StartOffset and ArcScaleNeedle.EndOffset properties respectively. To bind a needle to the specific scale, use the ArcScaleNeedle.ArcScale property.

The needle shape is managed by the ArcScaleNeedle.ShapeType property.

Level Bar

A level bar (the LinearScaleLevelComponent class' instance) is the needle's analog for linear gauges. This element is a base element that reflects changes to the linear scale value. Typically, there is only one level bar for each linear scale (see the figure below). However, you are free to add as many level bars as you want.

LinearGauge_LevelBar

Unlike needles, level bars cannot be moved and always go along the related scale (to relate a scale to a level bar, use the LinearScaleLevel.LinearScale property).

Level bar appearance is specified by two properties: the LinearScaleLevel.ShapeType property that sets the bar's shape, and the BaseLeafPrimitive.Shader property that allows you to paint a level bar using custom shaders. For instance, the following figure illustrates a level bar painted with the Style shader that uses red and blue colors.

XtraGauges - Customized Level Bar

Range Bar

Range bars are common to both circular and linear gauges elements. These elements repeat the related scale's shape (circle for circular gauges and bar for linear gauges) and fill this shape up to the specific value. Range bars inherited from the base BaseRangeBar class, but depending on your gauge type, an object of either ArcScaleRangeBarComponent or LinearScaleRangeBarComponent will be added.

Range bars can reflect either their own value specified by the BaseRangeBar.Value property, or the value of the related circular or linear scale. It is possible to set the ground level for a range bar by setting its BaseRangeBar.AnchorValue property.

Circular Range Bar

A circular range bar is displayed as a sector or a thick arc, whose inner radius is specified by the BaseRangeBar.StartOffset property and inner radius - by the BaseRangeBar.EndOffset. For instance, in the figure below both range bars have the StartOffset property equal to 0 and are displayed as circle sectors.

CircularGauge_Range Bar

If the inner range bar radius is greater than zero, the range bar is displayed as an arc. Such range bars can be seen in Haze and Ignis gauge presets, where range bars serve as a replacement for needles.

XtraGauges - Ignis in Preset Manager

In both of these styles the light-gray arc displays the scale's interval from the actual value (the value, reflected by a range bar) to its maximum. It is possible to hide this interval by setting the ArcScaleRangeBar.ShowBackground property to false.

The circular range bar's ArcScaleRangeBarComponent.StartAngle and ArcScaleRangeBarComponent.EndAngle property are bound in the two-way mode to the corresponding properties of the related scale.

Linear Range Bar

Linear range bars are displayed as linear bars, moved away from their related scales (the LinearScaleRangeBar.LinearScale property) by the BaseRangeBar.StartOffset units in relative coordinates. The bar's thickness equals BaseRangeBar.EndOffset minus BaseRangeBar.StartOffset units.

LinearGauge_RangeBar

Marker

Markers are small thumbs that point the specific value on the related scale. Inherited from the base ValueIndicatorComponent<TProvider> class, markers can be represented by either ArcScaleMarkerComponent or LinearScaleMarkerComponent class objects, depending on the parent gauge's type. The images below illustrate markers within circular and linear gauges.

CircularGaugeMarker LinearGauge_Marker

As other value indicators, markers have multiple built-in shapes, toggled by the ArcScaleMarker.ShapeType (LinearScaleMarker.ShapeType) properties. Markers can be moved away from the related scale by using the ArcScaleMarker.ShapeOffset (LinearScaleMarker.ShapeOffset) property. To shrink or enlarge a marker, use its ArcScaleMarker.ShapeScale (LinearScaleMarker.ShapeScale)