Pointers can be used to show the current value, or values, represented by a gauge. There are five supported pointer types: bars, caps, label, markers, and needles.
Any number of pointers can be included by adding an instance of CircularPointerBar, CircularPointerCap, CircularPointerLabel, CircularPointerMarker, and/or CircularPointerNeedle to the CircularTickSet.Pointers collection. In addition, each pointer can present a separate and specific value by setting the Value property.
A CircularGauge showing all four pointer types
Bars show a continuous band to the current value, much like ranges. By default, the bars are shown from the minimum value to the current value (as seen in the images). It is possible to "anchor" the bar to zero or the maximum value by setting the BarOrigin property appropriately.
A CircularGauge with the bar highlighted
Caps are a special type of pointer that do not actually "point" to a specific value. Caps are typically used in conjunction with 1 or more needles to provide a cleaner and more realistic look.
A CircularGauge with the cap highlighted
Several cap types are supported and can be configured by setting the CapType property. Each cap type supports a special effect.
Labels are pointers that render text at the specified value.
Font and Foreground
There are several properties for setting the appropriate font and/or foreground.
Markers are indicators or shapes rendered at the specified value.
A CircularGauge with the marker highlighted
Several marker types are supported and can be configured by setting the MarkerType property.
Needles are shapes that point to the specified value and are anchored (or pivot) around a central point.
A CircularGauge with the needle highlighted
Several needle types are supported and can be configured by setting the NeedleType property.
When using a sweep angle of 360 degrees, the direction that the pointer rotates can be customized. By default, the pointer always moves between the minimum and maximum values, and does not cross over the minimum/maximum value location.
This behavior can be changed by setting the PointerDirection property. The pointer can be set to only move clockwise or counter-clockwise, or to always take the shortest path to the new value.
All four pointer types can be configured to animate value changes, using a dampening feature. The DampeningMaximumDuration determines the amount of time it should take the pointer to travel the entire length of the scale. The pointers will use a relative duration when only traveling a portion of the scale. For example, if the pointer needs to travel half the length of the scale, then it will take half of the DampeningMaximumDuration to animate to the new location.
When making small value changes then the relative duration may be too short, resulting in a pointer that "jumps". To ensure the duration is not too small, the DampeningMinimumDuration can be used to set a minimum duration.
When using a CircularGauge to display real-time data, it is possible that the value displayed by the gauge will change to quickly for the user to read the individual values. The PointerBase.RefreshRate property can be used to limit the number of updates displayed to the user.
The refresh rate is specified as the amount of time to wait between updates. Therefore, if the refresh rate is set to
500 milliseconds, then there will be two updates to the display every second. If several hundreds value changes are made during that second, then only two of the values will actually be displayed.
The values presented by the various pointers, can be any real value between the minimum and maximum values, including fractions. Pointer values can be "snapped" to a configurable interval, by setting IsSnappingEnabled to
true. When snapping is enabled, the pointer value will be coerced so that it is evenly divisible by the snapping interval, which is specified by the SnappingInterval property.
For example, if snapping is enabled with an interval of 1, then the pointer value will be automatically rounded to the nearest whole number.
Snapping can be used in conjunction with interactive pointers.
The SnappingMode property allows you to determine when snapping occurs. Its default value will always apply snapping when snapping is enabled. Other values allow you to only snap when dragging the pointer, or only when the value is changed programmatically.
Pointer values can be interctively changed, by the end-user, using the mouse when CanDrag is set to
true. When enabled, the cursor is changed to
Cursors.Hand when the mouse is hovered over the pointer. The cursor can be customized by setting DragCursor.
true on a pointer element, the end-user can press the Escape key to cancel a drag operation.
By default, the pointer is not animated when the value is changed using the mouse. This behavior can be altered by setting IsDraggingAnimated to
Bar and marker pointers are positioned relative to the scale bar defined by the associated CircularScale element. By default, these pointers will be overlayed and centered on the scale bar. The placement of these pointers can be altered using the ScalePlacement and ScaleOffset properties.
There are three possible values for the ScalePlacement property:
||Indicates that the bar or marker pointer will be placed inside (or closer to the center) of the scale bar. The outer edge of the bar or marker pointer will be aligned with the inner edge of the scale bar.|
||Indicates that the bar or marker pointer will be placed outside (or further from the center) of the scale bar. The inner edge of the bar or marker pointer will be aligned with the outer edge of the scale bar.|
||Indicates that the bar or marker pointer will be centered over (or on top) of the scale bar. The center line of the bar or marker pointer will be aligned with the center line of the scale bar.|
In addition to the placement, the ScaleOffset can be used to further customize the location of the bar or marker pointers.
The ValueChanging and ValueChanged are raised before and after the pointer's value is changed, respectively. Using the IsValueChangingEventRaised and IsValueChangedEventRaised properties these events can either be enabled or disabled, for performance reasons. By default, the
ValueChanging is disabled and the
ValueChanged event is enabled.