Pointers
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
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
Colors/Brushes
There are two brushes used by bars: Background and BorderBrush. The BorderBrush property is only used when the BorderWidth property is greater than 0
.
Extents
Bars use the PointerExtent property to determine the thickness of the band. The PointerAscent property is not used.
Caps
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
Types
Several cap types are supported and can be configured by setting the CapType property. Each cap type supports a special effect.
Colors/Brushes
There are two brushes used by caps: Background and BorderBrush. The BorderBrush property is only used when the BorderWidth property is greater than 0
.
Extents
Caps use the PointerExtent property to determine the radius of the cap. The PointerAscent property is not used.
Labels
Labels are pointers that render text at the specified value.
Text
When Text is non-null, then that sting is used. When null, the text is determined by the DisplayValue, RoundMode, and TextFormat properties.
Font and Foreground
There are several properties for setting the appropriate font and/or foreground.
Markers
Markers are indicators or shapes rendered at the specified value.
A CircularGauge with the marker highlighted
Types
Several marker types are supported and can be configured by setting the MarkerType property.
Colors/Brushes
There are two brushes used by markers: Background and BorderBrush. The BorderBrush property is only used when the BorderWidth property is greater than 0
.
Extents/Ascents
Markers use the PointerExtent and PointerAscent properties to determine the overall bounding rectangle of the shape rendered.
Needles
Needles are shapes that point to the specified value and are anchored (or pivot) around a central point.
A CircularGauge with the needle highlighted
Types
Several needle types are supported and can be configured by setting the NeedleType property.
Colors/Brushes
There are two brushes used by needles: Background and BorderBrush. The BorderBrush property is only used when the BorderWidth property is greater than 0
.
Extents/Ascents
Needles use the PointerExtent and PointerAscent properties to determine the overall bounding rectangle.
Pointer Direction
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.
Dampening
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.
Refresh Rate
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.
Snapping
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.
Tip
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.
Interactive Pointers
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.
Tip
By setting IsFocusable
to 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 true
.
Scale Placement
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:
Value | Description |
---|---|
Inside |
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. |
Outside |
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. |
Overlay |
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.
Value Events
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.