Inherits from: DesktopCanvas

A toggle switch control drawn entirely in code, pill-shaped, with a moving ball, an optional text for each state and optional light effects (soft shadow, ball shading, recessed track).

pbSwitch is a subclass of DesktopCanvas that displays a two-state switch, in the style of modern mobile interfaces.

• The control's height defines the diameter of the ball and of the rounded ends; its width defines the length of the switch.
• The state is exposed through the Value property (True = ball on the right, "On"; False = ball on the left, "Off").
• Each state has its own background color, text color and label.
• The control reacts to the mouse (hover, press, release) and to the keyboard (Space, Return and Enter keys).
• It handles keyboard focus and can draw a focus ring.
• Three optional effects give it some depth: a soft ball shadow, a light shading of the ball and a recessed track. They all use the same light direction (upper left).
• The AfterDrawingSwitch event lets you draw on top of the standard rendering.

• Properties
• Events
• Enumerations
• Notes
• Sample code
• Compatibility

The properties are grouped by category:

Value As Boolean

The state of the switch. True: ball on the right ("On"). False: ball on the left ("Off").

When the value is changed from code and actually differs from the current one, the control is refreshed and the ValueChanged event is raised with ByCode = True. Assigning the value already in effect does nothing.

MySwitch.Value = True

OnRight As Boolean

Equivalent to Value: True if the ball is on the right. Assigning a new value behaves like assigning Value.

OnLeft As Boolean

The inverse of Value: True if the ball is on the left. Assigning a new value behaves like assigning Value with the opposite value.

Enabled As Boolean

Enables or disables the control. When disabled:

• the background is derived from Color.FillColor, darkened by 10%;
• the text is light gray (&cEFEFEF);
• the ball is drawn with Color.DarkBevelColor;
• hover and press effects are ignored;
• the ball shading and the recessed track effects are not drawn (flat look).

Tag As Variant

A free-form value available to the developer (not used by the class).

OnText As String

The text displayed when Value = True. An empty or whitespace-only text is not drawn. The text is truncated to the available space.

OffText As String

The text displayed when Value = False. Same rules as OnText.

TextAlignment As TextAlignments

How the texts are positioned. See the TextAlignments enumeration.

OnTextDeltaX As Integer

Horizontal offset (in pixels) applied to the OnText text.

OffTextDeltaX As Integer

Horizontal offset (in pixels) applied to the OffText text.

DeltaTextY As Double

Vertical offset (in pixels) applied to both texts, for fine adjustment of their vertical alignment.

Each change to one of these properties refreshes the control.

AutoOnTextColor As Boolean

If True, the color of the OnText text is chosen automatically (black or white) according to the brightness of OnBackColor (see Notes). If False, OnTextColor is used.

AutoOffTextColor As Boolean

Same as above for OffText, using OffBackColor and OffTextColor.

OnTextColor As Color

Color of the OnText text, used only if AutoOnTextColor = False.

OffTextColor As Color

Color of the OffText text, used only if AutoOffTextColor = False.

OnBackColor As Color

Background color when Value = True. Default: &c00B02D (green).

OffBackColor As Color

Background color when Value = False. Default: &cBB0000 (red).

BorderVisible As Boolean

Draws a border around the switch. The border is also drawn when the control has focus and the focus ring is allowed.

BorderColor As Color

Color of the border. If the control has focus and both AllowFocus and AllowFocusRing are True, the border is drawn with Color.HighlightColor instead.

The light effects of the ball (shading and shadow) are described in the 3D effects section.

BallLeftColor As Color

Color of the ball when it is on the left (Value = False).

BallRightColor As Color

Color of the ball when it is on the right (Value = True).

BallMargin As Integer

Margin, in pixels, between the ball and the edge of the switch. Negative values are ignored. Default: 3.

BallAnimation As Boolean

If True, the ball stretches toward the center of the control while the mouse button or a key is pressed (an iOS-like deformation effect). If False, the ball stays circular.

BallBorderVisible As Boolean

Draws an outline around the ball.

BallBorderColor As Color

Color of the ball outline (if BallBorderVisible = True).

Three optional effects give some depth to the control. They are all 0 by default: the control then keeps a flat look. They share the same light direction, coming from the upper left, so they combine consistently:

A subtle combination, for example TrackInsetIntensity = 60, BallShadingIntensity = 40 and BallShadowIntensity = 50, gives a realistic relief.

The effects are rendered as translucent images that are cached, and only recomputed when the size, the position of the ball, the background color or the settings change. Hovering the control therefore remains inexpensive.

TrackInsetIntensity As Integer

Intensity of the recessed effect of the track, from 0 (flat track, the default) to 100. Values outside this range are clamped.

The body of the switch looks sunk into the surface, a few millimeters deep: an inner shadow runs along the upper-left edges, and a thin light lip along the lower-right edges, with a progressive fade toward the inside. The effect is drawn above the background and the border, and below the ball and the texts. It is not drawn when the control is disabled.

A value between 40 and 70 gives a natural result.

TrackInsetDepth As Integer

Depth of the recess, in pixels, from 1 to 20. Values outside this range are clamped. Default: 4. This property has no visible effect if TrackInsetIntensity = 0.

BallShadingIntensity As Integer

Intensity of the light shading of the ball, from 0 (flat ball, the default) to 100. Values outside this range are clamped.

The shading style is chosen with BallShadingStyle. In the Convex style (the default), instead of a uniform color, the ball is shaded as a slightly flattened sphere, with the same light direction as the rest of the control (upper left): the upper-left side is slightly lightened and the lower-right side is darkened, with a progressive transition. The shading follows the shape of the ball when it is stretched. It is not drawn when the control is disabled.

Read the rest on GitHub