paddingTable of Contents

  1. Overview
  2. Frame
  3. Scales
  4. TickMarks
  5. Labels
  6. GaugePins
  7. Sections
  8. Ranges
  9. Pointers
  10. GaugeItems
  11. Templatized ToolTips
  12. Control Events
  13. Programmatic Use
  14. Collection Referencing
  15. Support Functions

Overview

(Note: Many of the options and abilities of the GaugeControl, as presented in this document, are demonstrated in the GaugeControl Sample Application included in the DotNetBar Samples folder. Please refer to it as an additional source for information and assistance).

The DotNetBar GaugeControl is a highly customizable, interactive gauge control.  It consists of several parts.  Each part of the gauge is highly configurable through its numerous properties and events – properties and events which define and control both display aesthetics as well as interactive and programmatic behavior.

The main parts of the GaugeControl are as follows:

  1. Frame (Circular, Rectangular, Round Rectangular, None)
  2. Scales (Circular, Linear)
  3. TickMarks
  4. Labels
  5. Sections
  6. Ranges
  7. Pointers (Bars, Markers, Needle, Thermometer)
  8. Gauge Text Items
  9. Gauge Image Items
  10. Gauge Numeric and State Indicators
Overview1

Gauge Properties

AntiAlias – If set to true, the control will AntiAlias its output during rendering. If set to false, the default system AntiAlias setting will be honored.

Frame – Contains properties for the customization of the Gauge Frame.

CircularScales – The collection of Circular Scales contained within the Gauge.

LinearScales – The collection of Linear Scales (both Horizontal and/or Vertical).

GaugeItems – The collection of Text and Image items contained in the gauge.

Note: These items are not associated or anchored with any circular or linear scale, but are only tied to the gauge itself.

All of the above gauge collection items can be referenced either by index, gauge.CircularScales[0], or by name, gauge.CircularScales[“Scale1”].

Gauge Frame

The GaugeControl Frame is the bounding “frame” for the control.

Frame Properties

AddGlassEffect – Controls whether the Gauge has a simulated glass effect added to it.  Here is an example of a gauge with the effect added.

Frame9

BackColor – Defines the Gradient fill colors of the inner background area of the control, as well as how it is filled (Center, Horizontally, etc).

BackSigmaFocus – Defines the SigmaBellShape Focus when the background area is Center filled.

BackSigmaScale – Defines the SigmaBellShape Scale used when the background area is Center filled.

ClipOuterFrame – Determines whether the outer frame of the Gauge is clipped. By default it is not clipped. Since Window’s transparency isn’t *real* transparency this can be useful when overlaying a GaugeControl over top of another control.

Here is an example without Frame clipping, and then with clipping (respectively):

FrameColor – Defines the Gradient fill colors of the Beveled Frame areas of the control, as well as how it is filled (Center, Horizontally, etc).

FrameSigmaFocus – Defines the SigmaBellShape Focus when the outer Frame area is Center filled.

FrameSigmaScale – Defines the SigmaBellShape Scale used when the outer Frame area is Center filled.

Image – Establishes an Image to use in place of a user or system drawn Frame. This Image will be centered and scaled to fit the size set for the GaugeControl.

Frame12

InnerBevel – This indicates the inner Frame bevel width, measured as a percentage of the width/height of the GaugeControl. This value can range from 0 to .5 (.5 representing 50% of the width/height of the GaugeControl).

OuterBevel – This indicates the outer Frame bevel width, measured as a percentage of the width/height of the GaugeControl. This value can range from 0 to .5 (.5 representing 50% of the width/height of the GaugeControl).

The Inner and Outer Bevel can be configured to the look and feel you desire.  Here are a couple of examples where the Inner and Outer Bevel were set to something other than the defaults:

Frame5 Frame6 Frame7

RoundRectangularArc – Indicates the arc or radius used when drawing RoundRectangular frames. It is measured as a percentage of the control width/height.

Style – The GaugeControl can have one of 4 built-in Frame styles.

None

Frame4

Circular

Frame1

Rectangular

Frame2

Round Rectangular

Frame3

User RenderedFrame8

Note that the frame style (or shape) is irrespective of the style of scale (or scales) contained within it.  In other words, you can have a Circular frame that contains both CircularScales and/or LinearScales, as well as having a Rectangular frame that contains both CircularScales and/or LinearScales.


Gauge Scales

Each GaugeControl can have as many scales as desired to achieve the look and feel needed for the Gauge you are designing. There are two basic Gauge scale styles – the CircularScale and the LinearScale, with the LinearScale being orientated as either a Horizontal or a Vertical scale. All Scale types have a set of common properties – they are as listed below.

Common Scale Properties

BorderColor – Indicates the Color of the Border used to outline the scale.

BorderWidth – Indicates the width of the scale Border, specified as pixels.  To disable the border, set this value to zero (the default).

Bounds – Gets the Rectangular Bounds of the scale.

CustomLabels – The collection of Custom Labels associated with the Scale. Custom Labels are labels that the user can add independently of the scale’s interval labels (usually displayed in conjunction with the scale’s major tickmarks).  Custom Labels can be added at any interval on the scale, and positioned inside, outside, or centered over the scale. They can be displayed with varying fonts, colors, and angles. They can be auto-orientated so that they stay right-side up, and made adaptive to the scale (adapts the text to fit the curve of the scale). If desired, a Custom label can have an associated built-in tickmark image or a unique image of its own. See Custom Labels for more information.

Frame14

Labels – This property controls the layout of the labels associated with the scale’s interval values,  See Interval Labels for more information.

MajorTickMarks – Controls the presentation and behavior of the scale’s major tickmarks.  See Scale TickMarks for more information.

MinorTickMarks – Controls the presentation and behavior of the scale’s minor tickmarks.  See Scale TickMarks for more information.

MaxPin – Controls the presentation and behavior of the scale’s Maximum Pin. See Gauge Pins for more information.

MinPin – Controls the presentation and behavior of the scale’s Minimum Pin. See Gauge Pins for more information.

MaxLimit / MinLimit – While the MaxValue and MinValue pair define the range of elements to display on the scale, the MaxLimit and MinLimit properties establish a boundary for the scale to scroll within. So, for example, if you set the MinValue to 20 and the MaxValue to 80, then the scale would always display that range on the screen (a 20 to 80 spread).  But if you also set the MaxLimit and MinLimit to something like –100 and 200 (respectfully), then the scale would be able to display that 20 to 80 spread all along the sliding scale of –100 to 200 (e.g. -100 to –40, 0 to 60, 100 to 160, 140 to 200 – and every other combination in between).

MaxValue / MinValue – Gets or sets the maximum and/or Minimum value to display on the scale.

Name – The user defined name of the Scale.

Pointers – The collection of Pointers associated with the scale.  Pointers are Gauge Items that “point” to an interval on the scale. This collection can contain Bars, Markers, Needles, and Thermometers.  Note that Circular Scales do not support Thermometer pointers.  See Pointers for more information.

Ranges – The collection of Ranges associated with the scale. Ranges are user specified areas of the scale (a “range” of values) that are marked and treated in a special way.  A Range may encompass the entire scale or only a small portion of it. Ranges can “interact” with other areas of the scale to effect color changes and event notifications when Pointers enter and exit a range.  See Ranges for more information.

Sections – The collection of Sections associated with the scale. Sections are user specified areas of the scale (a “section” of the scale) that are marked and treated in a special way.  A Section may encompass the entire scale or only a small portion of it. Sections, like Ranges, can “interact” with other areas of the scale to effect color changes and event notifications when Pointers enter and exit a section.  See Sections for more information.

Visible – The Visibility of the Scale.

Width – The width of the scale, specified as a percentage of the width/height of the Gauge.  This value is the default width of the scale. When sections are defined, if their width is set to zero, they will assume the width of the scale.  If the scale is given a border, this is the width of the area that is outlined.

CircularScale Properties

All of the Scales seen thus far in this document have been Circular Scales.  As stated before, the use of Circular Scales is independent of whether the frame is Circular, Rectangular, or even present at all.

PivotPoint – The scale’s center pivot point (the center point of the circular scale). This value is specified as a percentage of the gauge’s height/width.

Radius – The radius of the circular scale, specified as a percentage of the gauge’s height/width.

StartAngle – The starting angle for the scale, specified in clockwise degrees from the x-axis.

SweepAngle – The angle measured from the StartAngle to the ending point of the scale.

LinearScale Properties

Linear scales are non-circular scales.  Their orientation can be either Horizontal or Vertical.

Location – The scale’s center location point (the center point of the linear scale). This value is specified as a percentage of the gauge’s height/width.

Orientation – Specifies the scales horizontal or vertical orientation.

Size – Specifies the size of the scale.  This value is specified as a percentage of the gauge’s height/width.


Scale TickMarks

Each scale can have a set of defined MajorTickMarks and MinorTickMarks.  Scale TickMarks can be configured in numerous ways to permit the creation of scale gradations that suit your needs.

TickMark Properties

Interval – Specifies the spacing in between each like TickMark.

Interval Offset – Specifies the offset from the start of the scale to the first TickMark.  In other words, if your scale starts at 20, but you don’t want TickMarks to begin until 30, then you would set the IntervalOffset to 10.

TickMark Layout Properties

FillColor – Specifies the gradient enabled fill color for the TickMark.

Image – Specifies a user defined Image to use for the TickMark.

TickMark2

Length – Specifies the length of the TickMark. This value is specified as a percentage of the gauge’s height/width.

Overlap – Specifies how the TickMark overlaps previous TickMarks. When TickMarks overlap (for example when a MajorTickMark and a MinorTickMark overlap), this property determines how the overlapping TickMark deals with previous TickMarks.  Tickmark rendering precedence goes as follows (from lowest precedence to highest) – MinorTickMarks, MajorTickMarks, Custom Label TickMarks.

Note, for TickMarks to be considered as “overlapping” they must be at the same Interval with the same specified Placement.

Placement – Specifies whether the TickMark is near, far, or centered over the scale.

Note that when set to Near or Far, depending on the scale style and/or orientation, the TickMark’s display orientation will be automatically reversed to reference the scale properly. Notice in the image shown below that the trapezoid has been rotated 180 degrees when its Placement is set to Far.

Labels4

ScaleOffset – This property permits you to adjust the position of the TickMark, perpendicularly, with respect to the scale. In other words, if you have your TickMarks set to be positioned Near to the scale, but they are by default not as close to the scale as you would like, you can adjust the ScaleOffset property to nudge them closer (or, in like fashion, further away).

Style – TickMarks can be set to 10 different built-in styles.

TickMark1

Visible – The Visibility of the TickMarks.

Width – Specifies the width of the TickMark. This value is specified as a percentage of the gauge’s height/width.


Labels

Interval labels (Scale property “Labels”) are those labels that are associated with Scale Interval positions. Note that TickMarks do not have to be visible for the Labels to be displayed.  Note also, that if the Label’s Interval is left as not set (NaN) then the defined MajorTickMark Interval will be used. Custom Labels are labels that you can define for any interval point on the scale.   Custom Label Text will always override normal Interval Label Text that has the same Placement (Near, Far, Center) – at the same Interval.

Common Label Properties

AdaptiveLabel – Controls whether the label text “adapts” to the shape of the scale.  For CircularScales this means that the label text will be curved to match the positioning of the text with respect to the radius of the scale. When this property is set to true the Angle and RotateLabel properties are ignored. Here are examples of labels with the property set to false, then to true (respectively).

Labels1 Labels2

Angle – When AdaptiveLabel is set to false you can tell the system to add an additional angle of rotation to the label text via setting this property.

AutoOrientation – This property, when set to true, causes the system to individually orient each label so that it will be “right-side-up” as much as possible.  This property is ignored when the RotateLabel property is set to false.

AutoSize – Setting this property to true will cause the system to auto adjust the font size when the size of the scale is adjusted.

Font – The Font to use for the labels. When the AutoSize property is set to true then the Font’s size is taken as a relative size – when false, it is the actual point size for the Font.

ForeColor – The label text Fore Color.

Placement – Specifies whether the Label text is near, far, or centered over the scale.

Labels3

RotateLabel – Specifies that the labels are to be rotated to maintain consistent text rotation over the entire scale. If AdaptiveLabel is set to true, then this property is ignored.

ScaleOffset – This property permits you to adjust the position of the label, perpendicularly, with respect to the scale. In other words, if you have your label’s Placement set to “Near”, but they are by default not as close to the scale as you would like, you can adjust the ScaleOffset property to nudge them closer (or, in like fashion, further away). This value is specified as a percentage of the gauge’s height/width.

Visible – The Visibility of the Label.

Interval Label Properties

FormatString – This property lets you set a .Net Format string to use when formatting the Label Text. (See .Net documentation for Format Specifier details).

Labels5 FormatSpecifier = “C02” Labels6 FormatSpecifier = “E0”

Interval – Specifies the scale spacing in between each Label.

Interval Offset – Specifies the offset from the start of the scale to the first Label.  In other words, if your scale starts at 0, but you don’t want your labels to begin until 250, then you would set the IntervalOffset to 250.

Labels7 Interval = 150 IntervalOffset = 250

ShowMaxLabel – Determines whether the maximum label (the label at the maximum point on the scale) is displayed.

ShowMinLabel – Determines whether the minimum label (the label at the minimum point on the scale) is displayed.

Custom Label Properties

Name – The user defined name of the Label.

Text – The specified text to use for the label.

TickMark – The TickMark Layout definition to use for the label.  (See previous TickMark Layout properties).

Value – The interval value that the label is associated with.


Gauge Pins

Gauge Pins are positions “off the scale” that can be used to denote positions of rest or limiting positions where there is no valid value currently available.  Each scale has the option to have both a Minimum Pin and/or a Maximum Pin. Each pin can be configured to look and behave as you need.  And, each Pointer defined for the scale can be configured to honor each pin independently as well.   In the following example, the Minimum Pin is the rocket, and the Maximum Pin is the flag.

Frame7

Pin Properties

EndOffset – This value specifies the distance from the end of the scale to the pin.  The EndOffset can be positive or negative, placing the pin on or off the scale as desired. This value is specified as a percentage of the gauge’s height/width.

FillColor – Specifies the gradient enabled fill color for the Pin.

Image – Specifies the Image to use for the Pin (See the above rocket and flag images).

Label – The Label associated with the Pin.  The Pin Label contains all the same properties defined under the previous Interval Labels item.

Length – The length of the Pin. This value is specified as a percentage of the gauge’s height/width.

Name – The user defined name of the Pin.

Placement – Specifies whether the Pin is near, far, or centered over the Scale.

ScaleOffset – This property permits you to adjust the position of the Pin, perpendicularly, with respect to the Scale. In other words, if you have your Pin’s Placement set to “Near”, but they are by default not as close to the Scale as you would like, you can adjust the ScaleOffset property to nudge them closer (or, in like fashion, further away). This value is specified as a percentage of the gauge’s height/width.

Style – Specifies the Pin Style. Built-in Pin styles are identical to the built-in TickMark Styles (See TickmMark Style property).

ToolTip – The user defined ToolTip associated with the Pin.

Visible – The Visibility of the Pin.

Width – Specifies the width of the Pin. This value is specified as a percentage of the gauge’s height/width.


Sections and Ranges

Scale Sections and Ranges are areas of the scale which are usually visibly colored or altered in a way to make a part of the scale stand out to the user. Section and Ranges are very similar to each other, but Sections are primarily targeted to be used to denote scale partitions or variances.

Section1

Example showing 5 separate Sections

Range1

Example showing 4 separate Ranges

Common Range and Section Properties

CapFillColor – The Gradient Color a Needle Pointer Cap will assume when the its Value is within the Section or Range.  This property is only valid for Needle Style Pointers.

EndValue – The ending Scale Value for the Section or Range.

PointerFillColor – The Gradient Color that a Pointers will assume when its Value is within the Section or Range.  This property is valid for All Style Pointers.  For Needle Style Pointers this defines the color of the needle portion of the pointer.

FillColor – The Gradient fill Color for the Section or Range.

LabelColor – The Gradient Color that all defined Interval Labels will assume when they lie within the Section or Range.

MajorTickMarkFillColor – The Gradient Color that all defined Interval MajorTickMarks will assume when they lie within the Section or Range.

MinorTickMarkFillColor – The Gradient Color that all defined Interval MinorTickMarks will assume when they lie within the Section or Range.

Name – The user defined name of the Section or Range.

ScaleOffset – This property permits you to adjust the position of the Section or Range with respect to the Scale. In other words, if your Section or Range is not as close to the Scale as you would like, you can adjust the ScaleOffset property to nudge it closer (or, in like fashion, further away). This value is specified as a percentage of the gauge’s height/width.

StartValue – The Starting Scale Value for the Section or Range.

ToolTip – The user defined ToolTip associated with the Section or Range.

Visible – The Visibility of the Section or Range.

Section Only Properties

Width – Specifies the width of the Section.  If you leave this value set to 0, then the section will assume the width specified in its owning Scale. This value is specified as a percentage of the gauge’s height/width.

Range Only Properties

EndWidth – Specifies the ending width of the Range.  This value is specified as a percentage of the gauge’s height/width.

Placement – Specifies whether the Range is near, far, or centered over the Scale.

StartWidth – Specifies the starting width of the Range.  This value is specified as a percentage of the gauge’s height/width.


Pointers

Pointers are scale value indicators.  They “point” to intervals on the scale to display their current Value. There are 4 styles of Pointers available to you.  They are Markers, Needles, Bars, and Thermometers.

Common Pointer Properties

AllowUserChange – Controls whether the user is permitted to interact with the Pointer via the mouse.  If this is set to true, then when the user moves his mouse over the pointer the mouse cursor will change into the defined ChangeCursor, and they will be permitted to drag the pointer to new values on the scale.

ChangeCursor – The Cursor to use when the user moves the mouse over the Pointer (AllowUserChange must be set to true).

DampeningSweepTime – The time (in seconds) that it takes for the Pointer to traverse the entire scale. If no dampening is desired, then this value should be set to zero.  (See the Value and ValueEx properties).

FillColor – The Gradient fill Color for the Pointer.

FillColorEx – The current Gradient fill color for the Pointer, after applying any color changes due to Section / Range definitions.

HonorMaxPin – Determines whether the Pointer “honors” the MaxPin. If true, the Pointer will be permitted to leave the main scale area and point to the pin area.  If false, the Pointer will be constrained to the scale area only.

HonorMinPin – Determines whether the Pointer “honors” the MinPin. If true, the Pointer will be permitted to leave the main scale area and point to the pin area.  If false, the Pointer will be constrained to the scale area only.

Image – The Image to use for the Pointer.

IntervalPoint – The current defined interval Point for the Pointer.  This property is provided for “ease of use” only – and care should be taken if you should choose to use it. It’s value is dependant upon the Pointer type – and may change if the Pointer implementation changes.  Basically this value gives you the Point where the tip of the Pointer is positioned.

IntervalAngle –  The current defined interval Angle for the Pointer.  This property is provided for “ease of use” only – and care should be taken if you should choose to use it. It’s value is dependant upon the Pointer type – and may change if the Pointer implementation changes.  Basically this value gives you the angle where the tip of the Pointer is positioned.

Length – The Length of the Pointer.  For needle style pointers, this value determines the length of the needle “tail” (the portion of the needle that is pointing in the opposite direction to the needle tip).  For Bars and Thermometers this property has no effect. This value is specified as a percentage of the gauge’s height/width.

Placement – Specifies whether the Pointer is near, far, or centered over the Scale.

RotateCapImage – Determines whether the Needle’s cap Image is rotated with the needle.

ScaleOffset – This property permits you to adjust the position of the Pointer with respect to the Scale. In other words, if your Pointer is not as close to the Scale as you would like, you can adjust the ScaleOffset property to nudge it closer (or, in like fashion, further away). This value is specified as a percentage of the gauge’s height/width.

SnapInterval – When set to a non-zero value, the interactive value is “snapped” to a multiple of this value. In other words, the “granularity” of the interval value is determined by this setting.  By setting this value to, say .5, all interactively set Values will be rounded to a multiple of .5.

Style – The style of the pointer – Bar, Marker, Needle, or Thermometer.

ToolTip – The user defined ToolTip associated with the Pointer.

UnderTickMarks – Specifies whether the Pointer is rendered under (or over) the scale’s TickMarks.

In the following example the blue and gold bars have UnderTickMarks set to true.  The red and green bars UnderTickMarks set to false.

Pointer2

Value – The value of the Pointer.  This is the interval value the Pointer is “pointing” to.

Note, setting this value programmatically will cause the on screen Pointer display to be dampened – if DampeningSweepTime has been set to a non-zero value. If programmatic dampening is not desired, you can set the Pointer Value via the ValueEx property.

ValueEx – The value of the Pointer.  This is the interval value the Pointer is “pointing” to.

Note that setting this value programmatically will cause the on screen Pointer display be updated immediately – no matter if DampeningSweepTime has been set to a non-zero value or not. If programmatic dampening is desired, you can set the Pointer Value via the Value property.

Width – Specifies the width of the Pointer. This value is specified as a percentage of the gauge’s height/width.

Marker Properties

MarkerStyle – The style of the marker Pointer.  The marker style can be any one of the values as shown that was available for the scale TickMarks – Circle, Trapezoid, Star5, etc.  (See TickMarks Style property).

Common Bar and Thermometer Properties

BarStyle – If the Pointer Style is “Bar” or “Thermometer” then you can specify what style the end of the bar will be.  It can be set to Point, Round, or Square – as shown in the following example.

Pointer1

Origin – For Bar and Thermometer style Pointers this property specifies the Pointer origin, or starting, anchor point.  The Origin can be “Minimum”, “Maximum”, or “Custom”.   When set to Minimum, the Pointer will be anchored at the scale’s MinValue and extend positively or negatively around it. When set to Maximum, the Pointer will be anchored at the scale’s MaxValue and extend positively or negatively around it.  If set to Custom, then the Pointer will be anchored at the set OriginInterval and extend positively or negatively around that value.

OriginInterval – For Bar and Thermometer Pointers, and the Origin property is set to “Custom”, this value will be used to determine the origin value for the Pointer.  The Pointer will be anchored at this value and will extend positively or negatively around it.

Thermometer Properties

BulbOffset – The distance from the top of the thermometer bulb to the start of the scale.  This value is specified as a percentage of the gauge’s height/width.

Thermo2 BulbOffset = 0
Thermo1 BulbOffset = .07

BulbSize – The size of the thermometer bulb. This value is specified as a percentage of the gauge’s height/width.

Thermo3

BulbStyle – The style of the thermometer reservoir or bulb.  It can either be a bulb or a flask.  The prior thermometer images (see above) are bulb style.

The following is flask style.

Thermo4

ThermoBackColor – The backColor for the non-filled area of the thermometer tube (shown Yellow in the following figure).

Thermo5

Needle Properties

CapBounds – The bounding rectangle for the needle cap.

CapFillColor – The Gradient fill color for the needle cap.

CapFillColorEx – The current Gradient fill color for the needle cap, after applying any color changes due to Section / Range definitions.

CapImage – The image to use for the needle cap.

CapInnerBevel – The width of the needle cap’s inner bevel. This value is specified as a percentage of the cap width.

CapOnTop – Controls whether the needle cap is displayed on top of the needle, or under it.

CapOuterBevel – The width of the needle cap’s outer bevel. This value is specified as a percentage of the cap width.

CapStyle – The needle cap style.

Cap1 CapStyle = Style1 Cap2 CapStyle = Style2

CapWidth – The width of the needle cap. This value is specified as a percentage of the gauge’s height/width.

NeedleStyle – The style of the needle.  There are 8 built-in styles to choose from.

Needle1


Gauge Text and Image Items

Gauge Text and Image items are text strings and Images that you can add at the Gauge Level via the GaugeItems collection property.  These items are not associated with an individual scale, but are associated with the entire gauge, and therefore are positioned and sized solely with respect to the gauge.

Common Text and Image properties

Angle – The angle of rotation to apply to the text or image.

Location – The item’s center location point (the center point of its bounding rectangle ). This value is specified as a percentage of the gauge’s height/width.

Size – Specifies the size of the bounding rectangle for the item.  This value is specified as a percentage of the gauge’s height/width.

ToolTip – The user defined ToolTip associated with the Item.

UnderScale – Specifies whether the text is to be rendered under or on-top-of any/all defined scales.

Gauge Text Properties

AutoSize – Setting this property to true will cause the system to auto adjust the font size when the size of the gauge is adjusted.

Font – The Font to use for the Text. When the AutoSize property is set to true the Font size is taken as a relative size – when false, it is the actual point size for the Font.

ForeColor – The text’s foreground Color.

TextAlignment – The alignment of the text within its bounding rectangle.

Gauge Image Properties

AutoFit – Setting this property to true will cause the system to stretch the given image to fill its bounding rectangle (See Size).

Image – The Image


Gauge Numeric and State Indicator Items

Gauge Numeric and State Indicator items are items that you can add at the Gauge Level via the GaugeItems collection property.  Like Gauge Text and Image items, Gauge Indicators are not associated with an individual scale, but are associated with the entire gauge, and therefore are positioned and sized solely with respect to the gauge.

Numeric Indicators are gauge items that display numeric related data in a “digit-centric” fashion.

State Indicators are indicators that can be used to display gauge state changes.

Common Numeric and State Indicator properties

AutoSize – Setting this property to true will cause the system to auto adjust the font and image size when the size of the indicator is adjusted.

BackColor – Defines the Gradient fill colors of the background area of the indicator, as well as how it is filled (Center, Horizontally, etc).

DampeningSweepTime – The time (in seconds) that it takes for the Indicator display Value to traverse its entire range (MinValue to MaxValue). If no dampening is desired, then this value should be set to zero.  (See the Value and ValueEx properties).

Font – The Font to use for the displayed Text. When the AutoSize property is set to true the Font size is taken as a relative size – when false, it is the actual point size for the Font.

Location – The item’s center location point (the center point of its bounding rectangle ). This value is specified as a percentage of the gauge’s height/width.

MaxValue – The maximum limit value for the indicator.

MinValue – The minimum limit value for the indicator.

OverRangeString – The text to display when the Value of the indicator has gone over, or exceeded, its defined MaxValue.

RefreshRate – Indicates how often the indicator is refreshed per second.

Size – Specifies the size of the bounding rectangle for the item.  This value is specified as a percentage of the gauge’s height/width.

Text – The indicator text to be displayed.

Note, for Numeric Indicators the indicator’s display is derived from its current set Value – unless the Text property is set to a non-null value. If the Text property is set to a displayable value, then the indicator’s Value property is ignored.

ToolTip – The user defined ToolTip associated with the Item.

UnderRangeString – The text to display when the Value of the indicator has gone under its defined MinValue.

UnderScale – Specifies whether the text is to be rendered under or on-top-of any/all defined scales.

Value – The value of the Indicator.

Note, setting this value programmatically will cause the on screen Indicator display to be dampened – if DampeningSweepTime has been set to a non-zero value. If programmatic dampening is not desired, you can set the Indicator Value via the ValueEx property.

ValueEx – The value of the Indicator.

Note that setting this value programmatically will cause the on screen Indicator display be updated immediately – no matter if DampeningSweepTime has been set to a non-zero value or not. If programmatic dampening is desired, you can set the Indicator Value via the Value property.

Gauge Numeric Indicator Properties

DecimalColor – The Color of the decimal digits.

DecimalDimColor – The Color of the dim decimal digit segments.

Note, this property pertains solely to the digital (or segmented) Numeric Indicator Styles.

DigitPlacement – Determines whether the displayed digits are placed Near, Center, or Far on the indicator display.

Digits – The collection of defined Digits (as set via the NumberOfDigits property).  Each defined Digit, and its associated properties, are accessible via this collection. See Numeric Indicator Elements.

EmptyString – The text string to display on the indicator when the indicator Value is empty (double.NaN).

FormatString – This property lets you set a .Net Format string to use when formatting the Value Text. (See .Net documentation for Format Specifier details).

NumberOfDecimals – The number of decimal digits to display.

NumberOfDigits – The total number of digits to display.  This number includes both whole unit digits as well as the decimal digits (See NumberOfDecimals) – it also includes any displayable decimal point and sign.

Padding – Extra padding can be specified for the indicator using this property.

Note, the padding is not around each individual digit, but rather encompasses the entire indicator (ie. the area between the displayed digits and its border).

Ranges – The collection of defined Indicator Ranges.  Indicator Ranges can be used to change indicator colors, fonts, text, etc when the Value of the indicator falls within a defined Range.

SegmentWidth – The width or thickness of the digital indicator segments. This value is specified as a percentage of the width/height of the indicator.

SeparatorColor – The Color of the separator area.  The separator area is the area between each digit.

SeparatorWidth – The width of the area allocated between each digit, specified as a percentage of the width of the indicator.

ShearFactor – The shear coefficient used for italicizing the displayed Digits. This property only effects Digital style indicators.

ShowDecimalPoint – Determines whether the decimal point is displayed.

ShowDimColonPoints – Determines whether the dim digital Colon points are displayed.

ShowDimDecimalPoint – Determines whether the dim digital Decimal Point is displayed.

ShowDimSegments – Determines whether the dim digital segments are displayed.

ShowLeadingZeros – Determines whether leading zeros are added to the displayed Value text.

Note, if the Value is formatted via a set FormatString, then this property is ignored.

SignVisibility – Determines the visibility of the sign for the Value being displayed.  The sign can always be displayed, never displayed, or optionally displayed only when the Value is either positive or negative.

Style – The Style of the indicator, which can be set to one of the following:

Mechanical

Digital7Segment

Digital16Segment

Gauge State Indicator Properties

Angle – The angle of rotation to apply to the text and image.

Image – The Image to display, in place of the default state rendering.

RoundRectangleArc – The arc or radius used when drawing RoundRectangular Style Indicators. It is measured as a percentage of the indicator’s width/height.

Style – The style of the State indicator, which can be set as Circle, Rectangle, or RoundRectangle.

TextAlignment – The alignment of the text within the Indicator’s bounding rectangle (TopLeft, MiddleCenter, etc).

TextColor – The Color of the displayed Text.

TextHorizontalOffset – The horizontal offset of the displayed Text. This property can be used to nudge the Text horizontally from it’s default calculated TextAlignment position.

TextVerticalOffset –The vertical offset of the displayed Text. This property can be used to nudge the Text vertically from it’s default calculated TextAlignment position.


Numeric Indicator Elements

When the Numeric Indicator “NumberOfDigits” property is set, a collection of NumericElements is allocated to define the digits.  Normally these Elements are updated when a new Indicator Text or Value property is set.  If you choose to do so, you can set each Digits[n]’s properties yourself.

Note, that setting the indicator Value or Text properties will reinitialize each digit[n] to reflect the new setting.

NumericElement Properties

BackColor – Defines the Gradient fill colors of the background area of the digit, as well as how it is filled (Center, Horizontally, etc).

ColonPointsOn – Determines whether the Colon Points are on.

DecimalPointOn – Determines whether the Decimal Point is on.

DigitColor – The Color of the digit.

DigitDimColor – The Color of the dim digit segments.

ShowDimColonPoints – Determines whether the dim Colon points are displayed.

ShowDimDecimalPoint – Determines whether the dim Decimal Point is displayed.

ShowDimSegments – Determines whether the dim segments are displayed.

Value – The value of the Digit (a char value – e.g. ‘1’, ‘e’, etc).


Templatized ToolTips

Tooltips can be set for most every item present in the Gauge. The ToolTip text can be a simple string (e.g. “My ToolTip Text”) or something more complicated that attempts to convey more relevant information to the user.  In order to convey more information, you have the ability to provide templatized text for each ToolTip.

There are 5 built-in templates – Name, Value, StartValue, EndValue, and TagName, Value, and Tag are available to all Pointer styles, whereas the StartValue and EndValue templates only make sense for Section and Range items. The general form of a templatized text entry is:

[Template{FormatSpecifier}]

Where the “{FormatSpecifier}” is optional. If provided, the FormatSpecifier must be in braces. If the “Template” is a built-in template (such as “Value”) then the FormatSpecifier must conform to a normal .Net Format specifier.  If the “Template” is a user defined one, then the FormatSpecifier can be defined at the user’s discretion (note, though, that it must not contain braces or brackets). You can also extend these templates as you need.  Here is an example, from the sample app, of how to define and use these templates.  In the following example, the ToolTip text is using the built-in “Value” template with a Fixed-Point format specifier (F2). It is also using a user defined template “CtoF” with a Fixed-Point format specifier (F3).

C# Example

public void Init()
{
    gauge.GetDisplayTemplateText += GaugeControlGetDisplayTemplateText;
 
    gauge.LinearScales[0].Pointers[0].Tooltip = "[Value{F2}]°C ([CtoF{F3}]°F)";
}
 
private void GaugeControlGetDisplayTemplateText(
        object sender, GetDisplayTemplateTextEventArgs e)
{
    GaugePointer pointer = e.GaugeItem as GaugePointer;
 
    if (pointer != null)
    {
        // If the GaugeItem is a Pointer, then we have 2 simple user
        // defined templates that we have defined
 
        switch (e.DisplayTemplate)
        {
            case "CtoF": // Celsius to Fahrenheit conversion
 
                double n = pointer.Value * 9 / 5 + 32;
 
                e.DisplayText = String.IsNullOrEmpty(e.DisplayFormat) == false
                                    ? String.Format("{0:" + e.DisplayFormat + "}", n)
                                    : (Math.Round(n, 2)).ToString();
                break;
 
            case "OutOf": // "n out of 100"
 
                e.DisplayText = ((int) (pointer.Value * 100)).ToString() + " out of 100";
                break;
        }
    }
}

VB Example

Public Sub Init()
	AddHandler gauge.GetDisplayTemplateText, AddressOf GaugeControlGetDisplayTemplateText
 
	gauge.LinearScales(0).Pointers(0).Tooltip = "[Value{F2}]°C ([CtoF{F3}]°F)"
End Sub
 
Private Sub GaugeControlGetDisplayTemplateText(sender As Object, e As GetDisplayTemplateTextEventArgs)
	Dim pointer As GaugePointer = TryCast(e.GaugeItem, GaugePointer)
 
	If pointer IsNot Nothing Then
		' If the GaugeItem is a Pointer, then we have 2 simple user
		' defined templates that we have defined

		Select Case e.DisplayTemplate
			Case "CtoF"
				' Celsius to Fahrenheit conversion
				Dim n As Double = pointer.Value * 9 \ 5 + 32
 
				e.DisplayText = If([String].IsNullOrEmpty(e.DisplayFormat) = False, [String].Format("{0:" & Convert.ToString(e.DisplayFormat) & "}", n), (Math.Round(n, 2)).ToString())
				Exit Select
 
			Case "OutOf"
				' "n out of 100"
				e.DisplayText = CInt(pointer.Value * 100).ToString() & " out of 100"
				Exit Select
		End Select
	End If
End Sub

Frame Events

PreRenderFrame – Occurs before the Gauge Frame is rendered. Further system rendering of the Frame at this level can be canceled by setting the EventArgs.Cancel property to true.

C# Code Sample

public void Init()
{
    gauge.PreRenderGaugeContent += GcUserRenderingPreRenderGaugeContent;
}
 
private void GcUserRenderingPreRenderGaugeContent(
    object sender, RenderGaugeContentEventArgs e)
{
    using (LinearGradientBrush br =
        new LinearGradientBrush(e.Bounds, Color.White, Color.White, -90))
    {
        ColorBlend cb = new ColorBlend(_Colors.Length);
        cb.Colors = _Colors;
        cb.Positions = _Positions;
 
        br.InterpolationColors = cb;
 
        e.Graphics.FillRectangle(br, e.Bounds);
    }
}

VB Code Sample

Public Sub Init()
	AddHandler gauge.PreRenderGaugeContent, AddressOf GcUserRenderingPreRenderGaugeContent
End Sub
 
Private Sub GcUserRenderingPreRenderGaugeContent(sender As Object, e As RenderGaugeContentEventArgs)
	Using br As New LinearGradientBrush(e.Bounds, Color.White, Color.White, -90)
		Dim cb As New ColorBlend(_Colors.Length)
		cb.Colors = _Colors
		cb.Positions = _Positions
 
		br.InterpolationColors = cb
 
		e.Graphics.FillRectangle(br, e.Bounds)
	End Using
End Sub

PostRenderFrame – Occurs after the Gauge Frame has been rendered.

Gauge Events

PreRenderGaugeContent – Occurs after the Frame has been rendered, but before any Gauge content is rendered (CircularScales, LinearScales, or GaugeItems).  Further system rendering of the Gauge at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderGaugeContent – Occurs after all Gauge content has been rendered

GetDisplayTemplateText – When a Template Text is encountered that is not one of the known, built-in templates, the Gauge will call out to this event to retrieve the formatted, templatized text.  (See Templatized ToolTip Text)

Scale Events

PreRenderScale – Occurs before each Scale is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScale – Occurs after each Scale has been rendered.

Range Events

PreRenderScaleRanges – Occurs before any Scale Range is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleRanges – Occurs after every Scale Range has been rendered

PreRenderScaleRange – Occurs before each Scale Range is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleRange – Occurs after each Scale Range has been rendered.

Section Events

PreRenderScaleSections – Occurs before any Scale Section is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleSections – Occurs after every Scale Section has been rendered

PreRenderScaleSection – Occurs before each Scale Section is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleSection – Occurs after each Scale Section has been rendered.

Pointer Events

PreRenderScalePointers – Occurs before any Scale Pointer is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScalePointers – Occurs after every Scale Pointer has been rendered

PreRenderScalePointer – Occurs before each Scale Pointer is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScalePointer – Occurs after each Scale Pointer has been rendered.

ScaleEnter – Occurs when a Pointer enters a Scale.

ScaleLeave – Occurs when a Pointer leaves a Scale.

RangeEnter – Occurs when a Pointer enters a Range.

RangeLeave – Occurs when a Pointer leaves a Range.

SectionEnter – Occurs when a Pointer enters a Section.

SectionLeave – Occurs when a Pointer leaves a Section.

PointerChanging – Occurs when a Pointer’s Value is interactively changing.  The current Value of the Pointer has not yet been set. The NewValue provided in the EventArgs parameter can be evaluated and changed or the pointer change process canceled via setting the EventArgs.Cancel to true.

PointerChanged – Occurs when a Pointer’s Value has been interactively changed.

C# Example

private void Init()
{
    gcPointerChange.PointerChanged += GcPointerChangePointerChanged;
}
 
private void GcPointerChangePointerChanged(object sender, PointerChangedEventArgs e)
{
    // Locate the "Planned" GaugeItem, and update its text
    // to reflect the pointer change
 
    GaugeText item = gcPointerChange.GaugeItems["Planned"] as GaugeText;
 
     if (item != null)
        item.Text = String.Format("(Planned {0:C0})", e.Pointer.Value * 1000);
 
    e.Pointer.FillColor.Color1 = (e.Pointer.Value >= 65) ? Color.Lime : Color.Yellow;
}

VB Example

Public Sub Init()
    AddHandler gcPointerChange.PointerChanged , AddressOf GcPointerChangePointerChanged
End Sub
 
Private Sub GcPointerChangePointerChanged(sender As Object, e As PointerChangedEventArgs)
	' Locate the "Planned" GaugeItem, and update its text
	' to reflect the pointer change

	Dim item As GaugeText = TryCast(gcPointerChange.GaugeItems("Planned"), GaugeText)
 
	If item IsNot Nothing Then
		item.Text = [String].Format("(Planned {0:C0})", e.Pointer.Value * 1000)
	End If
 
	e.Pointer.FillColor.Color1 = If((e.Pointer.Value >= 65), Color.Lime, Color.Yellow)
End Sub

GetPointerPath – Occurs when a Pointer’s GraphicsPath is needed.  This event lets you totally redefine the shape of the given Pointer.

TickMark Events

PreRenderScaleTickMarks – Occurs before Scale TickMarks are rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleTickMarks – Occurs after Scale TickMarks have been rendered.

PreRenderScaleTickMarkLabels– Occurs before Scale TickMark labels are rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleTickMarkLabels – Occurs after Scale TickMark labels have been rendered.

GaugePin Events

PreRenderScaleGaugePin– Occurs before each Scale Min/Max Pin is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleGaugePin – Occurs after each Scale Min/Max Pin has been rendered.

CustomLabel Events

PreRenderScaleCustomLabel– Occurs before each Scale Custom Label is rendered.  Further system rendering of the Scale at this level can be canceled by setting the EventArgs.Cancel property to true.

PostRenderScaleCustomLabel– Occurs after each Scale Custom Label has been rendered.

GaugeIndicator Events

PreRenderIndicator – Occurs before each Indicator is rendered.  Further system rendering of the indicator can be cancelled by setting the EventArgs.Cancel property to true.

PostRenderIndicator – Occurs after each Indicator is rendered.

PreRenderIndicatorDigit – Occurs before each Indicator Digit is rendered.  Further system rendering of the digit can be cancelled by setting the EventArgs.Cancel property to true.

PostRenderIndicatorDigit – Occurs after each Indicator Digit  is rendered.

GetDigitSegments – Occurs when an Indicator’s digit segment pattern is needed.

The GetDigitalSegments callout event provides you with the opportunity to define, or redefine, the segment layout for the given digit value.  The layout of the segments for both the 7 and 16 segment indicators are shown below:

Digital7

So, for example, if you wanted to define the degree symbol (‘°’) you could define it as being represented by turning on segments 0, 1, 2, and 3.  This would be caluclated as follows:

int segments = (1<<0)  +  (1<<1) + (1<<2) + (1<<3);

or as

int segments = 1 + 2 + 4 + 8;

int segments = 15;

Digital16

Likewise, to define the letter ‘X’ for a 16 segment digit, one could do so as follows, utilizing segments 3, 5, 10, and 12:

int segments = (1<<3)  +  (1<<5) + (1<<10) + (1<<12);

or as

int segments = 8 + 32 + 1024 + 4096;

int segments = 5160;

C# Example

private void Init()
{
    gaugeControl1.GetDigitSegments += GaugeControl1GetDigitSegments;
}
 
void GaugeControl1GetDigitSegments(object sender, GetDigitSegmentsEventArgs e)
{
    if (e.Indicator.Name.Equals("NumIndicator16") == true)
    {
        // Let's redefine what the asterisk should look like for
        // this indicator using all available segments.
 
        switch (e.Digit)
        {
            case '*':
                e.Segments = 0xFFFF;
                break;
        }
    }
}

VB Example

Public Sub Init()
   AddHandler gaugeControl1.GetDigitSegments , AddressOf GaugeControl1GetDigitSegmentsEnd Sub
End Sub
 
Private Sub GaugeControl1GetDigitSegments(sender As Object, e As GetDigitSegmentsEventArgs)
	If e.Indicator.Name.Equals("NumIndicator16") = True Then
		' Let's redefine what the asterisk should look like for
                ' this indicator using all available segments

                Select Case e.Digit
			Case "*"C
				e.Segments = &amp;Hffff
				Exit Select
		End Select
	End If
End Sub

 


GaugeControl programmatic use

A Gauge control with a simple Circular Scale can be created via the following:

C# Sample

GaugeControl gauge = new GaugeControl();
gauge.Frame.Style = GaugeFrameStyle.Circular;
 
GaugeCircularScale scale = new GaugeCircularScale();
scale.Name = "MyScale";
 
GaugePointer pointer = new GaugePointer();
pointer.Name = "MyPointer";
pointer.Style = PointerStyle.Needle;
scale.Pointers.Add(pointer);
 
GaugeSection section = new GaugeSection();
section.Name = "MySection";
section.StartValue = 10;
section.EndValue = 50;
scale.Sections.Add(section);
 
GaugeRange range = new GaugeRange();
range.Name = "MyRange";
range.StartValue = 60;
range.EndValue = 90;
scale.Ranges.Add(range);
 
gauge.CircularScales.Add(scale);
 
Controls.Add(gauge);

VB Example

Dim gauge As New GaugeControl()
gauge.Frame.Style = GaugeFrameStyle.Circular
 
Dim scale As New GaugeCircularScale()
scale.Name = "MyScale"
 
Dim pointer As New GaugePointer()
pointer.Name = "MyPointer"
pointer.Style = PointerStyle.Needle
scale.Pointers.Add(pointer)
 
Dim section As New GaugeSection()
section.Name = "MySection"
section.StartValue = 10
section.EndValue = 50
scale.Sections.Add(section)
 
Dim range As New GaugeRange()
range.Name = "MyRange"
range.StartValue = 60
range.EndValue = 90
scale.Ranges.Add(range)
 
gauge.CircularScales.Add(scale)
 
Controls.Add(gauge)

Collection Referencing

The GaugeControl has 3 main collections:

CircularScales – The collection of all Circular Scale elements.

LinearScales – The collection of all Linear Scale elements.

GaugeItems – The collection of all Gauge level Text and Image elements

Each item in a given collection can be referenced via index or by the Name of the element.

gauge1.CircularScales[0].Name = “NewName”;                     // or

gauge1.CircularScales[“OldName”].Name = “NewName”;

The Name property in each element is not constrained by the system to be unique, therefore you can add multiple items to a given collection that all have the same name, but you should be aware that in doing so the system will not be able to distinguish between them if you attempt to reference them by name (it will always access the first one it finds).


Support Functions

GetPointer(string pointerName)

GetPointer(string scaleName, string pointerName)

This routine locates a Pointer from the given pointerName (or scaleName, pointerName pair) and returns a reference to it.  If either the scaleName or the pointerName is not located, null is returned.

GetPointerValue(string pointerName)

GetPointerValue(string scaleName, string pointerName)

This routine locates a Pointer from the given pointerName (or scaleName, pointerName pair) and returns it’s Value.  If either the scaleName or the pointerName is not located, an exception is thrown.

SetPointerValue(string pointerName, double value[, dampen])

SetPointerValue(string scaleName, string pointerName, double value[, dampen])

This routine locates a Pointer from the given pointerName (or scaleName, pointerName pair) and sets it’s Value.  If either the scaleName or the pointerName is not located, an exception is thrown. The optional ‘dampen’ parameter, will enable or disable any dampening of the Value for the call.

GetGaugeItemFromPoint(Point pt)

This routine will return a reference to the GaugeItem present at the given Point. All accessible items in the GaugeControl are, at their root level, GaugeItems.  There is a hierarchy to how the items are located. All collections are scanned in collection order according to the following hierarchy: Pointers Circular Ranges, Sections, MinPin, MaxPin Linear Ranges, Sections, MinPin, MaxPin GaugeItems (Text and Image)


Related posts:

  1. ComboTree Quick Start Guide
  2. WinForms Schedule Control Quick Start Guide
  3. Micro-Charts for WinForms Quick Start Guide
  4. How to select all days in week when week number is clicked in MonthCalendarAdv control