WklGauge

Dim myWklGauge As WklGauge
Set myWklGauge = Me!ControlName.Object

A value on a scale with colored ranges: a half or three-quarter circle, or a horizontal or vertical bar with further bars and a legend.

None

Use it for a load, a fill level or a count against a limit on a start page or a status page. The ranges (AddRange) decide the color: the value is drawn in the strong color of the kind of the range it lies in, so a gauge, a status label and a badge show “warn” in the same amber. Outside every range the color is neutral.

Fill it in one of two ways: unbound, code sets Value (for example from a timer that reads a service); bound, Control Source names a field or expression and Access writes it into Value on every record change. Value is never written back, so a calculated control source works.

A new value glides to its place in a quarter of a second, unless Animate is False or Windows animations are off. When the value moves into another range, RangeChange occurs and, with Announce, screen readers hear the new statement; a new value in the same range is not announced, so a gauge updated every second stays quiet. UI Automation presents a progress bar whose name is the whole statement (Statement) and whose range value is the number between Min and Max.

A horizontal or vertical gauge can show further bars (AddBar, BarValue), each in its own kind, side by side or stacked, with a legend. The values of the bars belong to the running form and are not saved with it; the bars themselves (key, caption, kind) are.

An ActiveX control: inserted into a form in design view (Form Design › Controls › ActiveX Controls); reports are not supported. VBA reaches it through the Object property of the control, where ControlName is the name of the control on the form.

Private Sub Form_Load()
    With Me!gauCpu.Object
        .Caption = "CPU"
        .Unit = "%"
        .AddRange 0, 70, wskOk, True
        .AddRange 70, 90, wskWarn, True
        .AddRange 90, 100, wskBad, True
        .Marker = 80
        .Key = "cpu"
    End With
End Sub
 
Private Sub Form_Timer()
    Me!gauCpu.Object.Value = DLookup("Cpu", "qryServiceStatus")
End Sub

None

Property Get Value() As Variant
Property Let Value(RHS As Variant)

Gets or sets the value shown on the scale.

None

Property value: Variant – A number, or Null for no value (“–” is shown and nothing is filled).

A value below Min or above Max is drawn at the end of the scale and marked; Statement adds “Below the minimum” or “maximum exceeded”. Text and other values raise wkeInvalidValue; an empty text counts as Null.

Read/write.

None

Declared by WklGauge.

Property Get Min() As Double
Property Let Min(RHS As Double)

Gets or sets the start of the scale.

None

Property value: Double – A number; the default is 0.

Min and Max can be set in any order. While Max is not greater than Min, the gauge draws “Check Min/Max” and Statement says what is wrong.

Read/write.

None

Declared by WklGauge.

Property Get Max() As Double
Property Let Max(RHS As Double)

Gets or sets the end of the scale.

None

Property value: Double – A number greater than Min; the default is 100.

Read/write.

None

Declared by WklGauge.

Property Get Shape() As WklGaugeShape
Property Let Shape(RHS As WklGaugeShape)

Gets or sets the outline of the gauge.

None

Property value: `WklGaugeShape` – A `WklGaugeShape` constant; the default is wgeHalfCircle.

Read/write.

None

Declared by WklGauge.

Property Get Style() As WklGaugeStyle
Property Let Style(RHS As WklGaugeStyle)

Gets or sets how the gauge shows its value.

None

Property value: `WklGaugeStyle` – A `WklGaugeStyle` constant; the default is wgfFill.

Read/write.

None

Declared by WklGauge.

Property Get Caption() As String
Property Let Caption(RHS As String)

Gets or sets the caption above the gauge.

None

Property value: String – A text, for example “CPU”; empty for none.

The caption also starts the statement for screen readers (“CPU: 87 %, Warnung”).

Read/write.

None

Declared by WklGauge.

Property Get Unit() As String
Property Let Unit(RHS As String)

Gets or sets the unit after the value.

None

Property value: String – A text such as “%”, “ms” or “sessions”; empty for none.

Read/write.

None

Declared by WklGauge.

Property Get Format() As String
Property Let Format(RHS As String)

Gets or sets the format of the value.

None

Property value: String – An Access format such as “0.0” or “#,##0”; empty for the general format.

Read/write.

None

Declared by WklGauge.

Property Get Hint() As String
Property Let Hint(RHS As String)

Gets or sets a line under the value.

None

Property value: String – A text, for example “Mittel 5 min”; empty for none.

Read/write.

None

Declared by WklGauge.

Property Get Marker() As Variant
Property Let Marker(RHS As Variant)

Gets or sets a mark on the scale, for example a target or a limit.

None

Property value: Variant – A number, or Null (default) for no mark.

Read/write.

None

Declared by WklGauge.

Property Get Animate() As Boolean
Property Let Animate(RHS As Boolean)

Gets or sets whether new values glide to their place.

None

Property value: Boolean – True (default) or False.

The movement is off when Windows animations are off (Settings › Accessibility › Visual effects), in design view and when printing.

Read/write.

None

Declared by WklGauge.

Property Get ShowValue() As Boolean
Property Let ShowValue(RHS As Boolean)

Gets or sets whether value and unit are shown in the center or next to the bar.

None

Property value: Boolean – True (default) or False.

Read/write.

None

Declared by WklGauge.

Property Get BackColor() As OLE_COLOR
Property Let BackColor(RHS As OLE_COLOR)

Gets or sets the background color.

None

Property value: OLE_COLOR – A color number; the default is the window background.

Read/write.

None

Declared by WklGauge.

Property Get ForeColor() As OLE_COLOR
Property Let ForeColor(RHS As OLE_COLOR)

Gets or sets the color of caption, value, hint, needle and marker.

None

Property value: OLE_COLOR – A color number; the default is the window text color.

Read/write.

None

Declared by WklGauge.

Property Get FontName() As String
Property Let FontName(RHS As String)

Gets or sets the font.

None

Property value: String – A font name; the default is “Segoe UI”.

Read/write.

None

Declared by WklGauge.

Property Get FontSize() As Long
Property Let FontSize(RHS As Long)

Gets or sets the font size of the caption, in points.

None

Property value: Long – 6 to 72; the default is 9. The value in the center is drawn twice as large.

Read/write.

None

Declared by WklGauge.

Property Get Announce() As Boolean
Property Let Announce(RHS As Boolean)

Gets or sets whether screen readers hear a change of range.

None

Property value: Boolean – True (default) or False.

Read/write.

None

Declared by WklGauge.

Sub AddRange(ByVal From As Double, ByVal To As Double, ByVal Kind As WklStatusKind, Optional ByVal Percent As Boolean = False)

Adds a colored range to the scale.

Ranges are drawn as pale bands of their kind behind the value. Where ranges overlap, the one added last decides the color. A kind outside the enumeration raises wkeInvalidValue.

None

Declared by WklGauge.

Sub ClearRanges()

Removes all ranges.

None

None

None

Declared by WklGauge.

Property Get RangeCount() As Long

Gets the number of ranges.

None

Property value: Long – The number of ranges.

Read-only.

None

Declared by WklGauge.

Sub AddBar(ByVal Key As String, ByVal Caption As String, Optional ByVal Kind As WklStatusKind = wskNeutral)

Adds a further bar to a horizontal or vertical gauge, or changes caption and kind of the bar with this key.

A gauge with bars shows them instead of Value; a circular gauge ignores bars. An existing bar keeps its value when it is added again.

None

Declared by WklGauge.

Property Get BarValue(ByVal Key As String) As Variant
Property Let BarValue(ByVal Key As String, RHS As Variant)

Gets or sets the value of a bar.

Property value: Variant – A number, or Null for no value.

An unknown key raises wkeKeyNotFound; a value that is no number raises wkeInvalidValue. Bar values are not saved with the form.

Read/write.

None

Declared by WklGauge.

Sub RemoveBar(ByVal Key As String)

Removes a bar.

None

None

Declared by WklGauge.

Sub ClearBars()

Removes all bars.

None

None

None

Declared by WklGauge.

Property Get BarCount() As Long

Gets the number of bars.

None

Property value: Long – The number of bars.

Read-only.

None

Declared by WklGauge.

Property Get Stacked() As Boolean
Property Let Stacked(RHS As Boolean)

Gets or sets whether the bars are stacked into one bar.

None

Property value: Boolean – True for one stacked bar; False (default) for one bar per key.

Read/write.

None

Declared by WklGauge.

Property Get ShowLegend() As Boolean
Property Let ShowLegend(RHS As Boolean)

Gets or sets whether the legend of the bars is shown.

None

Property value: Boolean – True (default) or False.

Read/write.

None

Declared by WklGauge.

Property Get Statement() As String

Gets the statement screen readers hear.

None

Property value: String – For example “CPU: 87 %, Warnung”, “CPU: kein Wert”, or for bars “Letzte 5 Minuten: Abweisungen 12, Fehler 3”.

Read-only.

None

Declared by WklGauge.

Property Get Key() As String
Property Let Key(RHS As String)

Gets or sets the key that Click passes on.

None

Property value: String – A text, for example the name of the list a click opens; empty by default.

Read/write.

None

Declared by WklGauge.

Property Get ColorScheme() As WklColorScheme
Property Let ColorScheme(RHS As WklColorScheme)

Gets or sets the color scheme the control draws in.

None

Property value: `WklColorScheme` – wcoAutomatic (default), wcoLight, wcoDark or wcoHighContrast.

wcoAutomatic follows, in this order, Windows high contrast mode, then the color set of the database design (Access: Design › Themes or Colors), and draws light when the database has no design or the control is on an Excel or Word UserForm. Office's own design setting and the Windows app mode are not followed: a database looks the same on every PC. In high contrast mode the control always uses the system colors. The scheme colors background and text (while BackColor and ForeColor keep the system defaults), the track, the range bands and the fills; a BackColor you set wins over the scheme. Every text keeps a contrast of at least 4.5:1. The control reads the database design after it is first drawn, never while Access draws the form, and again when the form opens anew. The value is saved with the form.

Read/write.

None

Declared by WklGauge.

Property Get PrintStyle() As WklPrintStyle
Property Let PrintStyle(RHS As WklPrintStyle)

Gets or sets when the ranges are told apart by pattern as well as by color.

None

Property value: `WklPrintStyle` – wpsAutomatic (default), wpsColor or wpsPatterns.

On a black-and-white or grayscale printout colors of similar lightness become the same gray. With patterns, each range carries a hatch of its status kind (bad cross-hatched and darkest, warn diagonal, ok dotted), the value fill carries the hatch of its range, and the track is outlined with a mark where two ranges meet. wpsAutomatic draws them only for a printer, a PDF or the print preview of a report; on the screen the control stays in color. wpsPatterns draws them also on the screen, for readers who cannot rely on color. Windows high contrast mode always tells the series apart by dash pattern. The value is saved with the form or report.

Read/write.

None

Declared by WklGauge.

Event Click(ByVal Key As String)

Occurs when the user clicks the gauge.

In a form module: Private Sub <ControlName>_Click(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklGauge.

Event RangeChange(ByVal OldRange As Long, ByVal NewRange As Long)

Occurs when the value moves into another range.

In a form module: Private Sub <ControlName>_RangeChange(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklGauge.