Label class

A Label is a windowless lightweight control for displaying read-only text. Labels are typically used as static captions next to input controls (“Name:”, “Email:”), as status displays that code keeps up to date, or as keyboard-mnemonic anchors that route Alt+ keystrokes to the next focusable control. Because the Label has no hWnd of its own, it is much cheaper than a TextBox configured to be read-only — but it is also non-interactive in the keyboard sense: it cannot take focus, raise key events, or be selected with the TAB key.

The default property is Caption and the default event is Click.

Private Sub Form_Load()
    lblName.Caption  = "&Name:"            ' Alt+N forwards focus to the next control
    lblName.AutoSize = True
    txtName.Text     = ""                  ' the TextBox that receives Alt+N
End Sub

Private Sub Timer1_Timer()
    lblClock.Caption = Format$(Now, "hh:mm:ss")
End Sub

• Windowless rendering
• Mnemonics and access keys
• Caption layout
• Rotation
• Border styles
• Background
• Data binding
• Properties
• Methods
• Events

Windowless rendering

Like Image, a Label has no hWnd. The framework paints it directly onto its parent’s drawing surface during the parent’s paint cycle. The trade-offs are the same:

• No focus, no keyboard input, no KeyDown / KeyPress / KeyUp / GotFocus / LostFocus / Validate.
• No hWnd to pass to API functions, and no SetFocus.
• Cannot host child controls.

For text the user can edit (or that needs to take focus), use TextBox with Locked = True instead.

Mnemonics and access keys

Labels do not take focus themselves, but they participate in keyboard-mnemonic routing. With UseMnemonic True (the default), an ampersand in Caption marks the next character as a mnemonic — pressing Alt+ that character moves the focus to the next focusable control in tab order after the label. Use && to display a literal ampersand. Set UseMnemonic to False to disable the special handling and have ampersands rendered verbatim.

lblName.Caption = "&Name:"           ' Alt+N → next control (typically txtName)
lblHelp.Caption = "Use && to escape" ' renders as: Use & to escape

The convention is to place the Label immediately before the control it captions in tab order, so the mnemonic naturally lands on that control.

Caption layout

Alignment and VerticalAlignment together position the caption within the label’s rectangle:

Property	Members
Alignment	vbLeftJustify (0, default), vbRightJustify (1), vbCenter (2)
VerticalAlignment	vbVerticalAlignTop (0, default), vbVerticalAlignMiddle (1), vbVerticalAlignBottom (2)

WordWrap, when True, breaks the caption into multiple lines at white-space whenever it would otherwise exceed Width. LineSpacing inserts extra vertical gap (in twips) between lines.

AutoSize, when True, resizes the label to fit its caption every time the caption, font, border, or word-wrap setting changes. Auto-sizing measures the current font in the parent’s device context, so it produces correct results on high-DPI displays. When AutoSize is False, the caption is clipped to the label’s rectangle (still respecting WordWrap and the alignment settings).

Rotation

Angle rotates the rendered caption, in degrees, anti-clockwise around the top-left of the control’s rectangle. 0 is the natural orientation, 90 is a quarter-turn anti-clockwise, and so on. The control’s bounding rectangle does not change — large rotation angles can therefore push the visible text outside the rectangle. Hit-testing for Click and the mouse events still uses the unrotated rectangle.

Border styles

BorderStyle chooses between three styles:

Constant	Value	Description
vbNoBorder	0	No border (default).
vbFixedSingleBorder	1	A sunken Win32-style border. Appearance selects 3-D or flat.
vbCustomBorder	2	Per-edge custom border configured through BorderCustomOptions.

With vbCustomBorder, BorderCustomOptions returns an object whose .Left, .Top, .Right, and .Bottom properties each carry independent Size (line thickness, in twips), Padding (inset between the border and the caption, in twips), and Color values:

lblBox.BorderStyle = vbCustomBorder
With lblBox.BorderCustomOptions
    .Top.Size = 30 :  .Top.Color = vbRed :   .Top.Padding = 60
    .Bottom.Size = 30 : .Bottom.Color = vbRed : .Bottom.Padding = 60
End With

Background

BackStyle chooses between vbBFOpaque (default — paint BackColor under the caption) and vbBFTransparent (don’t paint a background — whatever the parent has drawn shows through). Transparent labels are essential when overlaying captions on a PictureBox, an Image, or a custom-painted form background. New labels created in report mode default to vbBFTransparent.

Data binding

Setting DataSource and DataField connects Caption to a field of a Data control’s recordset. The bound field is read as a string on each move, and assigning to Caption marks the recordset as dirty. DataFieldAggregate and DataFieldAggregateValue are used by the report engine to display running totals.

Properties

Alignment

The horizontal placement of Caption within the label’s rectangle. A member of AlignmentConstants: vbLeftJustify (0, default), vbRightJustify (1), or vbCenter (2).

Anchors

The set of edges of the parent that the label’s corresponding edges follow when the parent resizes. Read-only — assign individual .Left, .Top, .Right, .Bottom flags through the returned Anchors object.

Angle

The rotation of the rendered caption, in degrees, anti-clockwise around the top-left of the control’s rectangle. Double, default 0.

Appearance

The style of the border, as a member of AppearanceConstants: vbAppearFlat or vbAppear3d (default). Only meaningful when BorderStyle is vbFixedSingleBorder.

AutoSize

Whether the label resizes itself to fit its Caption, Font, border, and word-wrap settings. Boolean, default False. When True, the resize happens whenever any of those inputs change.

BackColor

The colour painted behind the caption when BackStyle is vbBFOpaque. OLE_COLOR, defaults to the system 3-D face colour.

BackStyle

Whether the label paints a background. A member of BackFillStyleConstants: vbBFOpaque (1, default — paint BackColor) or vbBFTransparent (0 — let whatever the parent has drawn show through).

BorderCustomOptions

Per-edge configuration for the vbCustomBorder style. Read-only; the returned object exposes .Left, .Top, .Right, .Bottom sub-objects, each with Size, Padding, and Color properties. See Border styles.

BorderStyle

The style of border drawn around the label. A member of ControlBorderStyleConstantsCustom: vbNoBorder (0, default), vbFixedSingleBorder (1), or vbCustomBorder (2). See Border styles.

Caption

The text rendered by the label. String. Default property.

Syntax: object.Caption [ = string ]

An ampersand marks the next character as a mnemonic when UseMnemonic is True; && produces a literal ampersand. Assigning a value that differs from the current one raises a Change event; assigning the current value is a silent no-op.

Container

The control that hosts this label — typically the form, a Frame, or a UserControl. Read with Get, change with Set.

ControlType

A read-only ControlTypeConstants value identifying this control as a label. Always vbLabel.

DataChanged

Whether the bound Caption has been written to since the last save or refresh from the DataSource. Boolean. Setting DataChanged = True also marks the bound recordset as dirty.

DataField

The name of the field, in the recordset of the bound DataSource, whose value is mirrored by Caption. String.

DataFieldAggregate

The kind of running aggregate the report engine should accumulate into DataFieldAggregateValue. A member of Label.AggregateConstants:

Constant	Value	Description
vbAggregateNone	0	No aggregation (default).
vbAggregateSum	1	Sum the bound numeric value across the rows visited by the report.

Used only when the label is rendered inside a Report section.

DataFieldAggregateValue

The accumulated aggregate value computed by the report engine, exposed as a Decimal. Updated by the engine while a report is being generated; user code can read it from event handlers but does not normally write to it.

DataFormat

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

DataMember

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

DataSource

A reference to a Data control (or other DataSource provider) whose recordset supplies the value for DataField. Set with Set.

Dock

Where the label is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked labels ignore Anchors.

DragIcon

A StdPicture used as the mouse cursor while the control is being drag-and-dropped (see Drag and DragMode).

DragMode

Whether the control should drag itself when the user holds the mouse over it. A member of DragModeConstants: vbManual (0, default — call Drag from code) or vbAutomatic (1).

Enabled

Whether the label accepts mouse input and renders Caption in the normal text colour. A disabled label still paints, but in the system grey-text colour, and ignores mouse events. Boolean, default True.

Font

The StdFont used to render Caption. The convenience properties FontBold, FontItalic, FontName, FontSize, FontStrikethru, and FontUnderline read or write the corresponding members of this object. Defaults to Segoe UI, 8 pt.

FontBold

Shortcut for Font.Bold. Boolean.

FontItalic

Shortcut for Font.Italic. Boolean.

FontName

Shortcut for Font.Name. String, default "Segoe UI".

FontSize

Shortcut for Font.Size. Single, in points. Default 8.

FontStrikethru

Shortcut for Font.Strikethrough. Boolean.

FontUnderline

Shortcut for Font.Underline. Boolean.

ForeColor

The text colour for Caption, as an OLE_COLOR. Defaults to the system button-text colour. Replaced with the system grey-text colour when Enabled is False.

Height

The control’s height, in twips by default (or in the container’s ScaleMode units). Double. Computed automatically while AutoSize is True.

Index

When the label is part of a control array, the Long zero-based index of this instance within the array. Reading Index on a non-array instance raises run-time error 343 (Object not an array). Read-only at run time.

Left

The horizontal distance from the left edge of the container to the left edge of the label. Double.

LineSpacing

Extra vertical space inserted between lines of a wrapped or multi-line caption, in twips. Long, default 0.

LinkItem

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

LinkMode

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

LinkTimeout

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

LinkTopic

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

MouseIcon

A StdPicture used as the mouse cursor when MousePointer is vbCustom and the pointer is over the control.

MousePointer

The mouse cursor shown when the pointer is over the control. A member of MousePointerConstants.

Name

The unique design-time name of the control on its parent form. Read-only at run time.

OLEDropMode

How the label responds to OLE drops. A restricted member of OLEDropConstants: vbOLEDropNone (0, default) or vbOLEDropManual (1). Automatic drop is not supported on a Label; assigning vbOLEDropAutomatic raises run-time error 5 (Invalid procedure call or argument).

Parent

A reference to the Form (or UserControl) that ultimately contains the control. Read-only.

RightToLeft

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC. Use Alignment vbRightJustify to right-align the caption.

TabIndex

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC. The label is non-focusable, so the value would only affect mnemonic-routing — that is currently driven by the design-time Z-order instead.

Tag

A free-form String the application can use to associate custom data with the control. Ignored by the framework.

ToolTipText

A multi-line String displayed as a tooltip when the user hovers over the label.

Top

The vertical distance from the top of the container to the top of the label. Double.

UseMnemonic

Whether & in Caption marks the next character as a keyboard mnemonic. Boolean, default True. With False, ampersands are rendered verbatim.

VerticalAlignment

The vertical placement of the caption within the label’s rectangle. A member of VerticalAlignmentConstants: vbVerticalAlignTop (0, default), vbVerticalAlignMiddle (1), or vbVerticalAlignBottom (2).

Visible

Whether the label is shown. Boolean, default True.

WhatsThisHelpID

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC. See ShowWhatsThis.

Width

The control’s width, in twips by default (or in the container’s ScaleMode units). Double. Computed automatically while AutoSize is True.

WordWrap

Whether the caption breaks into multiple lines at white-space when it would otherwise exceed Width. Boolean, default False.

Methods

Drag

Begins, completes, or cancels a manual VB-style drag operation. Distinct from OLE drag — see OLEDrag.

Syntax: object.Drag [ Action ]

Action

optional A member of DragConstants: vbCancel (0), vbBeginDrag (1, default), or vbEndDrag (2).

LinkExecute

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

Syntax: object.LinkExecute Command

LinkPoke

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

Syntax: object.LinkPoke

LinkRequest

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

Syntax: object.LinkRequest

LinkSend

Note

Reserved for compatibility with VB6’s DDE feature; not currently implemented in twinBASIC.

Syntax: object.LinkSend

Move

Repositions and optionally resizes the label in a single call.

Syntax: object.Move Left [, Top [, Width [, Height ] ] ]

Left

required A Single giving the new horizontal position.

Top, Width, Height

optional New values for the corresponding properties. Omitted values are left unchanged.

OLEDrag

Initiates an OLE drag operation from the label, raising the OLEStartDrag event so the application can populate the DataObject.

Syntax: object.OLEDrag

Refresh

Forces an immediate repaint of the label’s rectangle on the parent’s drawing surface.

Syntax: object.Refresh

ShowWhatsThis

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

Syntax: object.ShowWhatsThis

ZOrder

Brings the label to the front or back of the windowless-sibling stack within its container.

Syntax: object.ZOrder [ Position ]

Position

optional A member of ZOrderConstants: vbBringToFront (0, default) or vbSendToBack (1).

Events

Change

Raised when Caption is assigned a value that differs from its current contents.

Syntax: object_Change( )

Click

Raised when the user single-clicks the label’s rectangle. Default event.

Syntax: object_Click( )

DblClick

Raised when the user double-clicks the label’s rectangle.

Syntax: object_DblClick( )

DragDrop

Raised on the destination control when a manual VB-style drag operation ends over it.

Syntax: object_DragDrop( Source As Control, X As Single, Y As Single )

DragOver

Raised on the control under the cursor while a manual VB-style drag operation is in progress.

Syntax: object_DragOver( Source As Control, X As Single, Y As Single, State As Integer )

Initialize

Raised once, after the label has been wired into its container’s paint cycle but before it is first painted. Useful for last-minute setup that depends on container state.

Syntax: object_Initialize( )

LinkClose

Note

Reserved for compatibility with VB6’s DDE feature; not currently raised in twinBASIC.

LinkError

Note

Reserved for compatibility with VB6’s DDE feature; not currently raised in twinBASIC.

LinkNotify

Note

Reserved for compatibility with VB6’s DDE feature; not currently raised in twinBASIC.

LinkOpen

Note

Reserved for compatibility with VB6’s DDE feature; not currently raised in twinBASIC.

MouseDown

Raised when the user presses any mouse button over the label.

Syntax: object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

Raised when the cursor moves over the label.

Syntax: object_MouseMove( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseUp

Raised when the user releases a mouse button over the label.

Syntax: object_MouseUp( Button As Integer, Shift As Integer, X As Single, Y As Single )

OLECompleteDrag

Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted.

Syntax: object_OLECompleteDrag( Effect As Long )

OLEDragDrop

Raised on the destination control when the user drops data on it.

Syntax: object_OLEDragDrop( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single )

OLEDragOver

Raised on the destination control while an OLE drag passes over it.

Syntax: object_OLEDragOver( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single, State As Integer )

OLEGiveFeedback

Raised on the source control during a drag so the application can adjust the cursor or other visual feedback.

Syntax: object_OLEGiveFeedback( Effect As Long, DefaultCursors As Boolean )

OLESetData

Raised on the source control when the destination requests data in a format that was registered but not yet supplied.

Syntax: object_OLESetData( Data As DataObject, DataFormat As Integer )

OLEStartDrag

Raised on the source control at the start of an OLE drag, so the application can populate the DataObject and choose the allowed effects.

Syntax: object_OLEStartDrag( Data As DataObject, AllowedEffects As Long )