WIP.CustomControls.md

CustomControls Package — Working Notes

See WIP.md for the cross-package maintenance guide.

Two source-side packages, one doc-side package (docs/Reference/Built-In/CustomControls/). The source halves split by role: a DESIGNER framework (the abstract surface a custom control hooks into: ICustomControl, ICustomForm, the CustomControlContext / CustomFormContext / CustomControlTimer / CustomControlsCollection CoClasses, the SerializeInfo / Canvas UDTs and the enums) and a runtime half (the eight concrete Waynes… controls, shared appearance helpers and mixin base classes).

The public user-facing surface, grouped by role:

Concrete controls

Each is Class <Name> (no Public modifier — implicitly public), tagged [CustomControl("/miscellaneous/frm<X>.png")] (designer icon) and [COMCreatable(False)] (cannot be New'd through COM; instantiated by the designer).

Control	Implements	Co-located public types
WaynesButton	ICustomControl + BaseControlFocusable (mixin)	WaynesButtonState (private, but exposed)
WaynesForm	ICustomControl + BaseForm (mixin)	— (uses WindowsFormOptions from support file)
WaynesFrame	ICustomControl + BaseControl (mixin)	—
WaynesGrid	ICustomControl + BaseControlFocusable (mixin)	Column, CellRenderingOptions
WaynesLabel	ICustomControl + BaseControl (mixin)	—
WaynesSlider	ICustomControl + BaseControlFocusable (mixin)	WaynesSliderState, SliderDirection & SliderDisplayValueFormat (nested enums)
WaynesTextBox	ICustomControl + BaseControlFocusable (mixin)	WaynesTextBoxState
WaynesTimer	ICustomControl + BaseControl (mixin)	—

Each control pulls in the "mixin" base classes (BaseControl, BaseControlFocusable, BaseForm) with the twinBASIC Implements <Base> Via _BaseControl = New <Base> syntax. The base classes get no doc page (they are private and user code never names them), but their inherited members must be folded into each control's Properties listing, as VB-package controls list their inherited surface. The visible inherited surface, by mixin:

• BaseControl → Name, Left, Top, Width, Height, Anchors, Dock, Visible.
• BaseControlFocusable → all of BaseControl + TabIndex, TabStop.
• BaseForm → FormDesignerId, Name, Left, Top, Width, Height, Controls.

The state-holder classes (WaynesButtonState, WaynesSliderState, WaynesTextBoxState) and WindowsFormOptions are declared Private Class but exposed on the parent control via Public WithEvents NormalState As WaynesButtonState (etc.). As with WebView2EnvironmentOptions, document them as sub-pages of the parent control in the folder-style layout.

Shared appearance helpers

These helpers are reachable through Public WithEvents … properties on one or more of the eight controls:

Class	Reached as
Anchors	<control>.Anchors (via the mixin base)
Corners	<state>.Corners, CellRenderingOptions.Corners, <sliderState>.BackgroundCorners, BlockCorners
Corner	Corners.TopLeft / .TopRight / .BottomLeft / .BottomRight
Borders	<state>.Borders, CellRenderingOptions.Borders, <sliderState>.BackgroundBorders, BlockBorders
Border	element of Borders.Elements(); also TextRendering.Outlines()
Fill	<state>.BackgroundFill, <sliderState>.BlockFill, CellRenderingOptions.Fill, Border.Fill, Line.Fill, TextRendering.Fill
FillColorPoint	element of FillColorPoints.Values()
FillColorPoints	Fill.ColorPoints
Line	WaynesGrid.VerticalLineOptions / .HorizontalLineOptions / .ResizerBar
Padding	TextRendering.Padding
TextRendering	<state>.TextRendering, WaynesLabel.TextRendering, CellRenderingOptions.TextRendering
FontStyle	TextRendering.Font
WindowsFormOptions	WaynesForm.WindowsOptions (only one consumer)

Each helper that has a small companion shares its page with it: Corner inlines under Corners.md, Border under Borders.md, FillColorPoint and FillColorPoints under Fill.md, FontStyle under TextRendering.md. WindowsFormOptions is the exception: its only consumer is WaynesForm, so it is a folder-style sub-page of WaynesForm/, as WebView2 does with EnvironmentOptions. The TextDecorator(s) / UDTs / MathSupport / ColorSupport / mixin-bases content is package-internal and gets no doc page.

DESIGNER framework surface

The framework half, which a control author writes against. Documented under docs/Reference/Built-In/CustomControls/Framework/:

Symbol	Kind	Role
ICustomControl	Interface	what every concrete control implements: Initialize(Context), Destroy(), Paint(Canvas)
ICustomForm	Interface	analogous surface for form-class custom controls
CustomControlContext	CoClass	passed to ICustomControl.Initialize; offers GetSerializer(), Repaint(), CreateTimer(), ChangeFocusedElement()
CustomFormContext	CoClass	extends CustomControlContext with Show() / Close()
CustomControlTimer	CoClass	returned by CustomControlContext.CreateTimer(); Interval, Enabled, OnTimer event
CustomControlsCollection	CoClass	the Controls collection on a form — Count, Item, Add, Remove, _NewEnum
SerializeInfo	UDT	obtained from Context.GetSerializer(); exposes RuntimeUISrz* operations (deserialize, mode flags, …)
Canvas	UDT	parameter to ICustomControl.Paint; exposes RuntimeUICCCanvasAddElement + DPI / size getters

Both UDTs follow a pattern unique to twinBASIC: a Pointer As LongPtr field plus Public DeclareWide PtrSafe Function/Sub … Lib "<runtimeuisrz>" Alias "#N" pseudo-DLL declarations bound directly into the type. A caller sees them as instance methods on the UDT (Canvas.RuntimeUICCCanvasAddElement(descriptor)). Document them as methods, and do not show the Lib "<…>" / Alias "#N" / PreserveSig / DLLStackCheck decoration (the same treatment as Assert's pseudo-DLL plumbing). The verbose RuntimeUISrz* / RuntimeUICC* names are the public API: keep them as they are.

Each CoClass has an underscore-prefixed default interface (_CustomControlTimer, _CustomControlContext, _CustomFormContext, _CustomControlsCollection, _CustomControlTimerEvents), an implementation detail of the COM [Default]/[Default, Source] pattern. Fold its members onto the CoClass page; don't give the interfaces their own pages.

Enumerations

Public enums under docs/Reference/Built-In/CustomControls/Enumerations/:

• CornerShape, FillPattern, TextAlignment, TextOverflowMode, DockMode, FontWeight, StartupPosition, BorderStyle, WindowState — straightforward value enums.
• Customtate — probable typo for CustomState. Has the same three members as WindowState (tbNormal / tbMinimized / tbMaximized) and isn't referenced anywhere else in the package. Document it (since it's Public), but add a > [!NOTE] callout flagging the typo and pointing readers to WindowState.
• ColorRGBA, PixelCount, PointSize — these are declared as Enum only because twinBASIC doesn't yet have a Type Foo = Long alias syntax. Each carries a FIXME comment ("Substitute for an ALIAS to Long") and a single [_MAX] = 0 placeholder member. Document them as typedefs for Long (the underlying storage type), not as real enums. Say in each that user code sees the alias, as in Public Width As CustomControls.PixelCount. These enum stand-ins go away when the alias syntax lands.

Plus the two enums nested inside WaynesSlider: SliderDirection and SliderDisplayValueFormat. They live on the WaynesSlider/index.md page rather than under Enumerations/ (locally scoped to the slider).