Buttons
Light wrapper around worksheet shapes for creating, positioning, and formatting linelist buttons. Supports large, small, and geo button scopes with automatic placement offset calculations.
Depends on: Checking, ILLFormat, ProjectError
Version: 1.0 (2026-02-09)
Factory
create #
Factory returning an initialised interface
Signature:
Public Function Create(ByVal outrng As Range, ByVal codeName As String, _
ByVal scope As Byte) As IButtons
Parameters:
outrng: Range. Anchor cell for the button.codeName: String. Name assigned to the shape.scope: Byte. ButtonScope controlling size and format.
Returns: IButtons. Ready to use.
Properties
output-range #
Anchor range used for placement
Signature:
Public Property Get OutputRange() As Range
Returns: Range. Top-left anchor cell.
output-range-set #
Update the anchor range used for placement
Signature:
Public Property Set OutputRange(ByVal rng As Range)
Parameters:
rng: Range. Providing the top-left anchor cell.
name #
Shape name assigned in the worksheet
Signature:
Public Property Get Name() As String
Returns: String. Shape identifier.
shape-scope #
Formatting scope applied to the button
Signature:
Public Property Get ShapeScope() As Byte
Returns: Byte. ButtonScope value.
Operations
add #
Create the worksheet shape at the configured location
Signature:
Public Sub Add(Optional ByVal actionCommand As String = vbNullString, _
Optional ByVal shapeLabel As String = vbNullString)
Parameters:
actionCommand: String. Macro to invoke on click. Defaults to vbNullString.shapeLabel: String. Label displayed on the button. Defaults to vbNullString.
format #
Apply the appropriate visual design to the button
Signature:
Public Sub Format(ByVal design As ILLFormat)
Parameters:
design: ILLFormat. Formatter responsible for styling the shape.
Checkings
has-checkings #
Whether diagnostic entries have been recorded
Signature:
Private Property Get HasCheckings() As Boolean
Returns: Boolean. True when at least one entry exists.
checking-values #
Retrieve the diagnostic log entries
Signature:
Private Property Get CheckingValues() As Object
Returns: Object. The checking instance, or Nothing.
Internal members (not exported)
Properties
self #
Self-reference as IButtons
Signature:
Public Property Get Self() As IButtons
Returns: IButtons. Self-reference.
name-set #
Store the shape name assigned in the worksheet
Signature:
Public Property Let Name(ByVal nm As String)
Parameters:
nm: String. Identifier for the shape.
shape-scope-set #
Store the formatting scope applied to the button
Signature:
Public Property Let ShapeScope(ByVal scope As Byte)
Parameters:
scope: Byte. ButtonScope value.
Shape Queries
shape-exists #
Whether the button shape already exists on the worksheet
Signature:
Private Property Get ShapeExists() As Boolean
Returns: Boolean. True when the named shape is present.
shape-object #
Retrieve the underlying shape or raise when absent
Signature:
Private Property Get ShapeObject() As Shape
Returns: Shape. Object representing the button.
Checkings
log-check #
Append a diagnostic entry to the internal checking log
Signature:
Private Sub LogCheck(ByVal label As String, _
Optional ByVal scope As Byte = checkingNote)
Parameters:
label: String. Message describing the issue or action.scope: Byte. Severity scope for the log entry.
Error Handling
throw-error #
Raise a typed project error
Signature:
Private Sub ThrowError(ByVal errNumb As Long, ByVal errorMessage As String)
Parameters:
errNumb: Long. ProjectError error code.errorMessage: String. Descriptive error message.
Helpers
target-range #
Ensure the internal anchor range is available
Signature:
Private Function TargetRange() As Range
Returns: Range. Anchor used for calculations.
target-worksheet #
Retrieve the worksheet hosting the button
Signature:
Private Function TargetWorksheet() As Worksheet
Returns: Worksheet. Containing the anchor range.
resolve-dimensions #
Resolve button dimensions from the scope definition
Signature:
Private Function ResolveDimensions(ByVal scope As Byte) As TDimensions
Parameters:
scope: Byte. ButtonScope value.
Returns: TDimensions. Width and height in points.
resolve-position #
Compute the top-left coordinates for the button
Signature:
Private Function ResolvePosition(ByVal anchor As Range) As TPosition
Parameters:
anchor: Range. Positional reference.
Returns: TPosition. Left and top offsets.
effective-label #
Determine the label displayed on the button
Signature:
Private Function EffectiveLabel(ByVal providedLabel As String, ByVal fallbackName As String) As String
Parameters:
providedLabel: String. Caller-provided label.fallbackName: String. Fallback when the label is blank.
Returns: String. Label text.