ListBox class

A ListBox is a Win32 native control that displays a vertically-scrolling list of items, optionally laid out in multiple columns, from which the user picks one item — or any number of items, when MultiSelect is non-zero. Each item is a string, with an optional LongPtr value the application can store alongside it through ItemData. The control is normally placed on a Form or UserControl at design time. The default property is Text and the default event is Click.

Private Sub Form_Load()
    With List1
        .AddItem "Apple"
        .AddItem "Banana"
        .AddItem "Cherry"
        .ItemData(0) = 100
        .ItemData(1) = 200
        .ItemData(2) = 300
        .ListIndex = 0
    End With
End Sub

Private Sub List1_Click()
    Debug.Print "Picked: " & List1.Text & " (data = " & List1.ItemData(List1.ListIndex) & ")"
End Sub

• Style
• Editing the list
• Selection
• Multi-column display
• Checkbox style
• Data binding
• OLE drag and drop
• Properties
• Methods
• Events

Style

Style selects one of three rendering modes (ListBoxConstants):

Constant	Value	Layout
vbListBoxStandard	0	Plain text items, the default.
vbListBoxCheckbox	1	Each item shows an independent check box that the user can toggle without changing the selection.
vbListBoxColorSwatch	2	Each item shows a colour swatch in front of its text, drawn in the colour stored in ItemData.

Changing Style at run time recreates the underlying window, preserving the items, ItemData values, current selection, scroll position, and (in checkbox mode) check states. Sorted, MultiSelect, IntegralHeight, and UseTabStops recreate the window the same way.

MultiSelect is meaningful only with vbListBoxStandard. The other styles always behave as if MultiSelect were vbMultiSelectNone — the per-item toggle of vbListBoxCheckbox replaces the multi-selection feature, and the colour swatch is purely a display variant.

Editing the list

Items are held inside the OS list-box control; the List and ItemData arrays are projections onto that storage. Items are added with AddItem, removed with RemoveItem, and the whole list is cleared with Clear. After each AddItem call, NewIndex reports the position the item was inserted at — useful when Sorted is True and the position is not predictable from the call.

List1.Sorted = True
List1.AddItem "Cherry"
List1.AddItem "Apple"           ' Inserted at index 0 — List1.NewIndex = 0
List1.ItemData(List1.NewIndex) = 42

Indexing past the end of the list raises run-time error 5 (Invalid procedure call or argument). Out of range or otherwise rejected calls to AddItem and RemoveItem raise the same error.

Selection

ListIndex is the zero-based index of the focused item, or -1 when nothing is focused. Text returns the text at that index. In single-select mode (vbMultiSelectNone) the focused item is also the selected item, and assigning to ListIndex selects it and raises Click if the value actually changes. In vbMultiSelectSimple and vbMultiSelectExtended the focused item is independent of the selection set; use Selected to read or write the selection state of any individual item, and SelCount to count them. SelectedIndices returns the selected indices as a Collection for convenient iteration.

Dim idx As Variant
For Each idx In List1.SelectedIndices()
    Debug.Print List1.List(idx)
Next

Assigning a string to Text searches the list with an exact, case-insensitive match (using LB_FINDSTRINGEXACT) and selects that entry if found; if no entry matches, ListIndex is set to -1 and the current selection is cleared. Reading Text when ListIndex is -1 raises run-time error 5.

Multi-column display

When Columns is greater than zero, the OS lays the items out in that many side-by-side columns and gives the control a horizontal scroll bar instead of the usual vertical one. The column width is automatically set to the control’s pixel width divided by Columns — assigning a new Width does not re-divide the columns; you must reassign Columns to refresh the layout.

The single-column / multi-column distinction is fixed at the moment the underlying window is created. At run time, Columns can be raised or lowered between non-zero values to re-divide the same control, but switching between zero and non-zero raises run-time error 380 (Invalid property value). Set Columns to its desired non-zero value at design time when a multi-column layout is wanted.

Checkbox style

In vbListBoxCheckbox mode each item draws a small check box in front of its text, sized from MaxCheckboxSize (in pixels at 96 DPI; scaled by the system DPI). The user toggles a check box by clicking it, by clicking the item and pressing Space, or by clicking the item itself when it is already the focused item. Each toggle raises ItemCheck with the affected index. Selected reads or writes the per-item check state in this mode (instead of the selection state). The focused item is still tracked through ListIndex, and the standard Click event still fires when the focus moves between items.

The check states are kept in an internal array that is preserved across AddItem and RemoveItem calls (existing items keep their state; new items start unchecked).

Data binding

Setting DataSource and DataField connects the control’s Text to a field of a Data control’s recordset. The bound field is read as a string on each move, and assigning to Text marks the recordset as dirty by setting DataChanged to True. A field whose value cannot be coerced to a string is treated as an empty string rather than raising.

OLE drag and drop

When OLEDragMode is set to vbOLEDragAutomatic, dragging an item from the list starts an OLE drag whose Text data is either the dragged item’s string (in single-select mode) or every selected item’s text concatenated, separated by vbCrLf (in vbMultiSelectSimple or vbMultiSelectExtended). OLEDropMode controls drop-target behaviour and is restricted to vbOLEDropNone or vbOLEDropManual.

Properties

Anchors

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

Appearance

Determines how the control’s border is drawn by the OS. A member of AppearanceConstants: vbAppearFlat or vbAppear3d (default). Combined with BorderStyle: a 3-D appearance plus single border yields the standard sunken client edge; flat appearance plus single border yields a one-pixel outline.

BackColor

The background colour of the list area, as an OLE_COLOR. Defaults to the system window-background colour. Items drawn in the selected state ignore BackColor in favour of the system highlight colour.

BorderStyle

A member of ControlBorderStyleConstants: vbNoBorder (0) or vbFixedSingleBorder (1, default). Changing it at run time re-syncs the border without recreating the window.

CausesValidation

Determines whether the previously focused control’s Validate event runs before this control receives the focus. Boolean, default True.

Columns

The number of columns in a multi-column layout, or 0 for a single-column list with a vertical scroll bar. Long, default 0. See Multi-column display.

Syntax: object.Columns [ = value ]

Switching between zero and non-zero at run time raises run-time error 380 (Invalid property value). Re-assigning between two non-zero values is allowed and re-divides the visible area.

Container

The control that hosts this list box — 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 list box. Always vbListBox.

DataChanged

Whether the bound Text 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 Text. String.

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 list box is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked list boxes 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

Determines whether the control accepts user input. A disabled list box still shows its contents but is dimmed and ignores keyboard and mouse interaction. Boolean, default True.

Font

The StdFont used to render item text. The convenience properties FontName, FontSize, FontBold, FontItalic, FontStrikethru, and FontUnderline read or write the corresponding members of this object. Changing the font rescales each item’s row height when IntegralHeight is True, and forces a recalculation of the row height in vbListBoxCheckbox and vbListBoxColorSwatch modes.

ForeColor

The text colour for entries that are not currently selected, as an OLE_COLOR. Defaults to the system window-text colour. Disabled entries draw in the system grey-text colour, and selected entries draw in the system highlight-text colour, regardless of this setting.

Height

The control’s height, in twips by default (or in the container’s ScaleMode units). When IntegralHeight is True, the OS quantises this on Initialize to a whole number of rows. Single.

HelpContextID

A Long identifying a topic in the application’s help file, retrieved when the user presses F1 while the control has focus.

hWnd

The Win32 window handle for the underlying list box, as a LongPtr. Read-only. Useful for passing to API functions.

Index

When the control 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.

IntegralHeight

When True (default), the OS adjusts the control’s height so that the visible portion shows whole rows rather than partial ones. When False, the control honours Height exactly and the bottom row may be clipped. Boolean. Changing this at run time recreates the underlying window.

ItemData

A LongPtr that the application can associate with each item. Indexed by the same zero-based position used by List.

Syntax: object.ItemData( Index ) [ = value ]

Index

required A Long zero-based item position.

In vbListBoxColorSwatch mode, ItemData is read by the painting code as the OLE_COLOR to draw in the swatch — a typical use is to fill it with a list of palette colours and let the user pick one. In the other styles ItemData is purely application-defined.

List1.AddItem "Highlight"
List1.ItemData(List1.NewIndex) = vbYellow

Values stored at design time through the form designer are kept as Long rather than LongPtr so that designed forms remain platform-agnostic; at run time the property is LongPtr, sign-extending the design-time value where necessary.

Left

The horizontal distance from the left edge of the container to the left edge of the control. Single.

List

The text of an item, indexed by zero-based position. Setting List(Index) removes the existing item at that position and reinserts the new value at the same index — note that this can change the resulting position when Sorted is True.

Syntax: object.List( Index ) [ = string ]

Index

required A Long zero-based item position. Out-of-range indices raise run-time error 5.

ListCount

The number of items in the list, as a Long. Read-only.

ListIndex

The zero-based index of the focused item, or -1 if no item is focused. Long. In multi-select modes the focused item and the selected items are independent — see Selected. Assigning a value that differs from the current one focuses that item and raises Click.

MaxCheckboxSize

The maximum size of the per-item check box drawn in vbListBoxCheckbox mode, in pixels at 96 DPI. Long, default 15. The actual size used is the smaller of this value (scaled by the system DPI) and the row height computed from the current font, so the box never exceeds a row.

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.

MultiSelect

The selection mode. A member of MultiSelectConstants: vbMultiSelectNone (0, default — single selection), vbMultiSelectSimple (1 — each click toggles), or vbMultiSelectExtended (2 — Shift for ranges, Ctrl for individual toggles). Changing this at run time recreates the underlying window; the items, ItemData values, focused item, and (in vbListBoxCheckbox mode) check states are restored, but multi-item selections are not. Effective only in vbListBoxStandard mode — see Style.

Name

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

NewIndex

The zero-based index at which the most recent AddItem call inserted its item, or -1 if no item has been added since the control was created. Particularly useful when Sorted is True and the resulting position cannot be predicted from the call. Long, read-only.

OLEDragMode

Whether the control acts as an automatic OLE drag source. A member of OLEDragConstants: vbOLEDragManual (0, default — call OLEDrag from code) or vbOLEDragAutomatic (1 — dragging an item starts an OLE drag whose Text data is the dragged item’s text in single-select mode, or every selected item’s text separated by vbCrLf in multi-select mode).

OLEDropMode

How the control responds to OLE drops. A restricted member of OLEDropConstants: vbOLEDropNone or vbOLEDropManual. Automatic-drop mode is not supported on a ListBox.

Opacity

The control’s opacity as a percentage (0–100, default 100). Values outside the range are clamped on Initialize. Requires Windows 8 or later for child controls.

Parent

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

RightToLeft

Note

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

SelCount

The number of items currently selected, as a Long. Read-only. Always 0 or 1 when MultiSelect is vbMultiSelectNone or when Style is non-standard.

Selected

The selection state of an individual item — or, in vbListBoxCheckbox mode, the check state.

Syntax: object.Selected( Index ) [ = boolean ]

Index

required A Long zero-based item position.

In vbListBoxStandard mode, reading Selected(Index) returns True when that item is selected, and assigning a value updates the selection. In single-select mode (vbMultiSelectNone), assigning True selects that item; assigning False has no observable effect. In multi-select modes, assignments toggle the corresponding item’s membership in the selection set independently of the focused item. Each assignment that changes the state raises Click.

In vbListBoxCheckbox mode, Selected(Index) reads or writes the per-item check state. Each assignment that changes the state raises ItemCheck.

In vbListBoxColorSwatch mode, Selected(Index) behaves as in single-select standard mode (the swatch styling is purely a display variant).

Sorted

When True, items added with AddItem are inserted in alphabetical order regardless of the Index argument; when False (default), they are inserted at the requested position (or appended). Boolean. Changing this at run time recreates the underlying window with the existing items re-added.

Style

Selects one of the three rendering modes. A member of ListBoxConstants: vbListBoxStandard (0, default), vbListBoxCheckbox (1), or vbListBoxColorSwatch (2). See Style above for the layout and behaviour differences. Changing Style at run time recreates the underlying window.

TabIndex

The position of the control in the form’s TAB-key navigation order. Long.

TabStop

Whether the user can reach the control by pressing the TAB key. Boolean, default True. A disabled control is skipped regardless of this setting.

Tag

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

Text

The text of the focused item, or an empty string when ListIndex is -1. Default property.

Syntax: object.Text [ = string ]

Reading Text returns List(ListIndex) — reading it when no item is focused raises run-time error 5 (Invalid procedure call or argument). Setting Text searches the list for an exact, case-insensitive match (using LB_FINDSTRINGEXACT) and selects the matching item if found; if no item matches, ListIndex is set to -1 and the current selection is cleared.

ToolTipText

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

Top

The vertical distance from the top of the container to the top of the control. Single.

TopIndex

The zero-based index of the item shown at the top of the visible area. Long. Assigning a value scrolls the list so that item is at the top; the Scroll event is raised when the value actually changes.

TransparencyKey

An OLE_COLOR that, when set, becomes fully transparent in the rendered control. Default -1 disables the effect. Requires Windows 8 or later for child controls.

UseTabStops

When True (default), vbTab characters embedded in item text are expanded to the OS’s standard list-box tab stops, so multi-column-aligned text can be rendered in a single-column list. When False, tab characters are drawn literally. Boolean. Changing this at run time recreates the underlying window.

Visible

Whether the control is shown. Boolean, default True.

VisualStyles

Whether the OS theme engine should be used when drawing the control. Boolean, default True. Affects the rendering of the per-item check box in vbListBoxCheckbox mode (themed vs. classic flat-style box).

WhatsThisHelpID

A Long identifying a “What’s This?” help-pop-up topic in the application’s help file. See ShowWhatsThis.

WheelScrollEvent

When True (default), mouse-wheel notifications over the control raise the Scroll event; when False, the wheel still scrolls the list but Scroll is suppressed. Boolean. VB6 never raised Scroll for wheel events; set this to False to match that behaviour exactly.

Width

The control’s width. Single. In a multi-column layout, also determines the column width — see Multi-column display.

Methods

AddItem

Inserts a new item into the list and stores the resulting position in NewIndex. In vbListBoxCheckbox mode the new item is unchecked; existing items keep their check state.

Syntax: object.AddItem Value [, Index ]

Value

required A String giving the text of the new item.

Index

optional A Long zero-based position to insert at. Omit to append to the end. Out-of-range indices raise run-time error 5. Ignored when Sorted is True.

Clear

Removes every item from the list, including any associated ItemData values and check states.

Syntax: object.Clear

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a MouseDown handler when DragMode is vbManual.

Syntax: object.Drag [ Action ]

Action

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

Move

Repositions and optionally resizes the control 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 control, raising the OLEStartDrag event so the application can populate the DataObject.

Syntax: object.OLEDrag

Refresh

Forces an immediate repaint of the control.

Syntax: object.Refresh

RemoveItem

Removes the item at the given zero-based position, along with its ItemData value. Items below it shift up by one, and (in vbListBoxCheckbox mode) their check states shift up with them.

Syntax: object.RemoveItem Index

Index

required A Long zero-based position.

SelectedIndices

Returns the zero-based indices of every currently-selected item as a Collection of Long values, in ascending order. Useful for iterating multi-selections without scanning Selected for every index.

Syntax: object.SelectedIndices

Dim idx As Variant
For Each idx In List1.SelectedIndices()
    Debug.Print idx & ": " & List1.List(idx)
Next

SetFocus

Moves the input focus to the control. The control must be both Visible and Enabled, or run-time error 5 (Invalid procedure call or argument) is raised.

Syntax: object.SetFocus

ShowWhatsThis

Displays the topic identified by WhatsThisHelpID as a “What’s This?” pop-up.

Syntax: object.ShowWhatsThis

ZOrder

Brings the control to the front or back of its sibling stack.

Syntax: object.ZOrder [ Position ]

Position

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

Events

Click

Raised after the focused item changes — whether the user clicked a different entry, used the keyboard to move the focus, or code assigned a different value to ListIndex or Selected. Also raised when the previously selected item is cancelled (LBN_SELCANCEL). Default event.

Syntax: object_Click( )

DblClick

Raised when the user double-clicks an entry. Typically used to act on the highlighted item — for example, opening it.

Syntax: object_DblClick( )

DragDrop

Raised on the destination control when a manual 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 drag operation is in progress.

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

GotFocus

Raised when the control receives the input focus.

Syntax: object_GotFocus( )

Initialize

Raised once, immediately after the underlying window is created and the design-time items have been added. New in twinBASIC — VB6 had no equivalent on this control.

Syntax: object_Initialize( )

ItemCheck

Raised in vbListBoxCheckbox mode each time the check state of an item changes — whether the user clicked its check box, pressed Space, or code assigned to Selected. Not raised in the other styles.

Syntax: object_ItemCheck( Item As Integer )

Item

The zero-based index of the toggled item.

Note

Items beyond index 32768 do not raise ItemCheck because the event signature uses Integer. Read Selected directly to inspect higher-indexed items.

KeyDown

Raised when the user presses any key while the control has focus.

Syntax: object_KeyDown( KeyCode As Integer, Shift As Integer )

KeyPress

Raised when the user types a character that produces an ANSI keystroke.

Syntax: object_KeyPress( KeyAscii As Integer )

KeyUp

Raised when the user releases a key while the control has focus.

Syntax: object_KeyUp( KeyCode As Integer, Shift As Integer )

LostFocus

Raised when the control loses the input focus.

Syntax: object_LostFocus( )

MouseDown

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

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

MouseMove

Raised when the cursor moves over the control.

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 control.

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. Fires whether the drag was initiated automatically (with OLEDragMode set to vbOLEDragAutomatic) or by an explicit OLEDrag call.

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

Scroll

Raised when the visible portion of the list scrolls — by the scroll bar, the keyboard, or (when WheelScrollEvent is True) the mouse wheel. The new offset can be read from TopIndex.

Syntax: object_Scroll( )

Validate

Raised when the focus is moving to another control whose CausesValidation is True. Setting Cancel to True keeps the focus on this control.

Syntax: object_Validate( Cancel As Boolean )